mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-20 09:14:22 +01:00
eb398f1951
Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com> Co-authored-by: rekram1-node <rekram1-node@users.noreply.github.com>
411 lines
9.5 KiB
Plaintext
411 lines
9.5 KiB
Plaintext
---
|
|
title: Config
|
|
description: Using the OpenCode JSON config.
|
|
---
|
|
|
|
You can configure OpenCode using a JSON config file.
|
|
|
|
---
|
|
|
|
## Format
|
|
|
|
OpenCode supports both **JSON** and **JSONC** (JSON with Comments) formats.
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
// Theme configuration
|
|
"theme": "opencode",
|
|
"model": "anthropic/claude-sonnet-4-20250514",
|
|
"autoupdate": true,
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Locations
|
|
|
|
You can place your config in a couple of different locations and they have a
|
|
different order of precedence.
|
|
|
|
---
|
|
|
|
### Global
|
|
|
|
Place your global OpenCode config in `~/.config/opencode/opencode.json`. You'll want to use the global config for things like themes, providers, or keybinds.
|
|
|
|
---
|
|
|
|
### Per project
|
|
|
|
You can also add a `opencode.json` in your project. It takes precedence over the global config. This is useful for configuring providers or modes specific to your project.
|
|
|
|
:::tip
|
|
Place project specific config in the root of your project.
|
|
:::
|
|
|
|
When OpenCode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
|
|
|
|
This is also safe to be checked into Git and uses the same schema as the global one.
|
|
|
|
---
|
|
|
|
### Custom path
|
|
|
|
You can also specify a custom config file path using the `OPENCODE_CONFIG` environment variable. This takes precedence over the global and project configs.
|
|
|
|
```bash
|
|
export OPENCODE_CONFIG=/path/to/my/custom-config.json
|
|
opencode run "Hello world"
|
|
```
|
|
|
|
---
|
|
|
|
### Custom directory
|
|
|
|
You can specify a custom config directory using the `OPENCODE_CONFIG_DIR`
|
|
environment variable. This directory will be searched for agents, commands,
|
|
modes, and plugins just like the standard `.opencode` directory, and should
|
|
follow the same structure.
|
|
|
|
```bash
|
|
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
|
|
opencode run "Hello world"
|
|
```
|
|
|
|
Note: The custom directory is loaded after the global config and `.opencode` directories, so it can override their settings.
|
|
|
|
---
|
|
|
|
## Schema
|
|
|
|
The config file has a schema that's defined in [**`opencode.ai/config.json`**](https://opencode.ai/config.json).
|
|
|
|
Your editor should be able to validate and autocomplete based on the schema.
|
|
|
|
---
|
|
|
|
### TUI
|
|
|
|
You can configure TUI-specific settings through the `tui` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"tui": {
|
|
"scroll_speed": 3
|
|
}
|
|
}
|
|
```
|
|
|
|
[Learn more about using the TUI here](/docs/tui).
|
|
|
|
---
|
|
|
|
### Tools
|
|
|
|
You can manage the tools an LLM can use through the `tools` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"tools": {
|
|
"write": false,
|
|
"bash": false
|
|
}
|
|
}
|
|
```
|
|
|
|
[Learn more about tools here](/docs/tools).
|
|
|
|
---
|
|
|
|
### Models
|
|
|
|
You can configure the providers and models you want to use in your OpenCode config through the `provider`, `model` and `small_model` options.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"provider": {},
|
|
"model": "anthropic/claude-sonnet-4-20250514",
|
|
"small_model": "anthropic/claude-3-5-haiku-20241022"
|
|
}
|
|
```
|
|
|
|
The `small_model` option configures a separate model for lightweight tasks like title generation. By default, OpenCode tries to use a cheaper model if one is available from your provider, otherwise it falls back to your main model.
|
|
|
|
You can also configure [local models](/docs/models#local). [Learn more](/docs/models).
|
|
|
|
---
|
|
|
|
### Themes
|
|
|
|
You can configure the theme you want to use in your OpenCode config through the `theme` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"theme": ""
|
|
}
|
|
```
|
|
|
|
[Learn more here](/docs/themes).
|
|
|
|
---
|
|
|
|
### Agents
|
|
|
|
You can configure specialized agents for specific tasks through the `agent` option.
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"agent": {
|
|
"code-reviewer": {
|
|
"description": "Reviews code for best practices and potential issues",
|
|
"model": "anthropic/claude-sonnet-4-20250514",
|
|
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
|
|
"tools": {
|
|
// Disable file modification tools for review-only agent
|
|
"write": false,
|
|
"edit": false,
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents).
|
|
|
|
---
|
|
|
|
### Sharing
|
|
|
|
You can configure the [share](/docs/share) feature through the `share` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"share": "manual"
|
|
}
|
|
```
|
|
|
|
This takes:
|
|
|
|
- `"manual"` - Allow manual sharing via commands (default)
|
|
- `"auto"` - Automatically share new conversations
|
|
- `"disabled"` - Disable sharing entirely
|
|
|
|
By default, sharing is set to manual mode where you need to explicitly share conversations using the `/share` command.
|
|
|
|
---
|
|
|
|
### Commands
|
|
|
|
You can configure custom commands for repetitive tasks through the `command` option.
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"command": {
|
|
"test": {
|
|
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
|
|
"description": "Run tests with coverage",
|
|
"agent": "build",
|
|
"model": "anthropic/claude-3-5-sonnet-20241022",
|
|
},
|
|
"component": {
|
|
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
|
|
"description": "Create a new component",
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands).
|
|
|
|
---
|
|
|
|
### Keybinds
|
|
|
|
You can customize your keybinds through the `keybinds` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"keybinds": {}
|
|
}
|
|
```
|
|
|
|
[Learn more here](/docs/keybinds).
|
|
|
|
---
|
|
|
|
### Autoupdate
|
|
|
|
OpenCode will automatically download any new updates when it starts up. You can disable this with the `autoupdate` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"autoupdate": false
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Formatters
|
|
|
|
You can configure code formatters through the `formatter` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"formatter": {
|
|
"prettier": {
|
|
"disabled": true
|
|
},
|
|
"custom-prettier": {
|
|
"command": ["npx", "prettier", "--write", "$FILE"],
|
|
"environment": {
|
|
"NODE_ENV": "development"
|
|
},
|
|
"extensions": [".js", ".ts", ".jsx", ".tsx"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
[Learn more about formatters here](/docs/formatters).
|
|
|
|
---
|
|
|
|
### Permissions
|
|
|
|
By default, opencode **allows all operations** without requiring explicit approval. You can change this using the `permission` option.
|
|
|
|
For example, to ensure that the `edit` and `bash` tools require user approval:
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"permission": {
|
|
"edit": "ask",
|
|
"bash": "ask"
|
|
}
|
|
}
|
|
```
|
|
|
|
[Learn more about permissions here](/docs/permissions).
|
|
|
|
---
|
|
|
|
### MCP servers
|
|
|
|
You can configure MCP servers you want to use through the `mcp` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mcp": {}
|
|
}
|
|
```
|
|
|
|
[Learn more here](/docs/mcp-servers).
|
|
|
|
---
|
|
|
|
### Instructions
|
|
|
|
You can configure the instructions for the model you're using through the `instructions` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
|
|
}
|
|
```
|
|
|
|
This takes an array of paths and glob patterns to instruction files. [Learn more
|
|
about rules here](/docs/rules).
|
|
|
|
---
|
|
|
|
### Disabled providers
|
|
|
|
You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"disabled_providers": ["openai", "gemini"]
|
|
}
|
|
```
|
|
|
|
The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
|
|
|
|
- It won't be loaded even if environment variables are set.
|
|
- It won't be loaded even if API keys are configured through `opencode auth login`.
|
|
- The provider's models won't appear in the model selection list.
|
|
|
|
---
|
|
|
|
## Variables
|
|
|
|
You can use variable substitution in your config files to reference environment variables and file contents.
|
|
|
|
---
|
|
|
|
### Env vars
|
|
|
|
Use `{env:VARIABLE_NAME}` to substitute environment variables:
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"model": "{env:OPENCODE_MODEL}",
|
|
"provider": {
|
|
"anthropic": {
|
|
"models": {},
|
|
"options": {
|
|
"apiKey": "{env:ANTHROPIC_API_KEY}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If the environment variable is not set, it will be replaced with an empty string.
|
|
|
|
---
|
|
|
|
### Files
|
|
|
|
Use `{file:path/to/file}` to substitute the contents of a file:
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"instructions": ["./custom-instructions.md"],
|
|
"provider": {
|
|
"openai": {
|
|
"options": {
|
|
"apiKey": "{file:~/.secrets/openai-key}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
File paths can be:
|
|
|
|
- Relative to the config file directory
|
|
- Or absolute paths starting with `/` or `~`
|
|
|
|
These are useful for:
|
|
|
|
- Keeping sensitive data like API keys in separate files.
|
|
- Including large instruction files without cluttering your config.
|
|
- Sharing common configuration snippets across multiple config files.
|