231 lines
5.2 KiB
Plaintext
231 lines
5.2 KiB
Plaintext
---
|
|
title: Config
|
|
description: Using the opencode JSON config.
|
|
---
|
|
|
|
You can configure opencode using a JSON config file.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"theme": "opencode",
|
|
"model": "anthropic/claude-sonnet-4-20250514",
|
|
"autoshare": false,
|
|
"autoupdate": true
|
|
}
|
|
```
|
|
|
|
This can be used to configure opencode globally or for a specific project.
|
|
|
|
---
|
|
|
|
### 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. This is useful for configuring providers or modes specific to 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.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
### Modes
|
|
|
|
opencode comes with two built-in modes: _build_, the default with all tools enabled. And _plan_, restricted mode with file modification tools disabled. You can override these built-in modes or define your own custom modes with the `mode` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"mode": {
|
|
"build": { },
|
|
"plan": { },
|
|
"my-custom-mode": { }
|
|
}
|
|
}
|
|
```
|
|
|
|
[Learn more here](/docs/modes).
|
|
|
|
---
|
|
|
|
### Models
|
|
|
|
You can configure the providers and models you want to use in your opencode config through the `provider` and `model` options.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"provider": {},
|
|
"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).
|
|
|
|
---
|
|
|
|
### Logging
|
|
|
|
Logs are written to:
|
|
|
|
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
|
- **Windows**: `%APPDATA%\opencode\log\`
|
|
|
|
You can configure the minimum log level through the `log_level` option.
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"log_level": "INFO"
|
|
}
|
|
```
|
|
|
|
With the following options:
|
|
|
|
| Level | Description |
|
|
| ------- | ---------------------------------------- |
|
|
| `DEBUG` | All messages including debug information |
|
|
| `INFO` | Informational messages and above |
|
|
| `WARN` | Warnings and errors only |
|
|
| `ERROR` | Errors only |
|
|
|
|
The **default** log level is `INFO`. If you are running opencode locally in
|
|
development mode it's set to `DEBUG`.
|
|
|
|
---
|
|
|
|
### 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).
|
|
|
|
---
|
|
|
|
### 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).
|
|
|
|
---
|
|
|
|
### 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": {
|
|
"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": ["{file:./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.
|