mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-10 05:08:32 +00:00
444 lines
8.4 KiB
Text
444 lines
8.4 KiB
Text
---
|
|
title: "Config"
|
|
description: "Configure OpenCode."
|
|
---
|
|
|
|
<Tip>
|
|
You shouldn't have to configure OpenCode manually. Ask OpenCode to update its configuration for you.
|
|
</Tip>
|
|
|
|
## Format
|
|
|
|
OpenCode supports both **JSON** and **JSONC** (JSON with Comments) configuration files.
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"model": "openai/gpt-5.2-custom",
|
|
"providers": {
|
|
"openai": {
|
|
"models": {
|
|
"gpt-5.2-custom": {
|
|
"modelID": "gpt-5.2",
|
|
"name": "GPT-5.2 Custom"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Locations
|
|
|
|
OpenCode loads global configuration from:
|
|
|
|
```text
|
|
~/.config/opencode/opencode.json(c)
|
|
```
|
|
|
|
Project-specific configuration can use either form:
|
|
|
|
```text
|
|
/home/user/projects/my-app/opencode.json(c)
|
|
/home/user/projects/my-app/.opencode/opencode.json(c)
|
|
```
|
|
|
|
When OpenCode starts, it searches for configuration files from the current
|
|
directory upward to the project root. The files are merged, and configuration
|
|
closer to the current directory takes precedence.
|
|
|
|
For example, consider a monorepo with OpenCode started from
|
|
`/home/user/projects/acme/packages/web`:
|
|
|
|
```text
|
|
~/.config/opencode/opencode.json
|
|
|
|
/home/user/projects/acme/
|
|
├── opencode.json
|
|
└── packages/
|
|
└── web/
|
|
├── opencode.json
|
|
└── src/
|
|
```
|
|
|
|
OpenCode applies these files from lowest to highest precedence:
|
|
|
|
1. `~/.config/opencode/opencode.json`
|
|
2. `/home/user/projects/acme/opencode.json`
|
|
3. `/home/user/projects/acme/packages/web/opencode.json`
|
|
|
|
Settings in the package config override matching settings from the repository
|
|
config, which override matching settings from the global config. Settings that
|
|
do not conflict are preserved from every file.
|
|
|
|
## Schema
|
|
|
|
The complete OpenCode configuration schema is available at
|
|
[opencode.ai/config.json](https://opencode.ai/config.json).
|
|
|
|
Add the `$schema` field to your configuration file to enable validation and
|
|
autocomplete in editors that support JSON Schema:
|
|
|
|
```json title="opencode.json"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json"
|
|
}
|
|
```
|
|
|
|
Use the schema as the source of truth for available fields, accepted values,
|
|
and nested configuration shapes.
|
|
|
|
### Shell
|
|
|
|
Set the shell used by the terminal and shell tools.
|
|
|
|
```jsonc
|
|
{
|
|
"shell": "/bin/zsh"
|
|
}
|
|
```
|
|
|
|
### Model
|
|
|
|
Set the default model in `provider/model` format. Add `#variant` to select a
|
|
specific model variant.
|
|
|
|
```jsonc
|
|
{
|
|
"model": "anthropic/claude-sonnet-4-5#high"
|
|
}
|
|
```
|
|
|
|
See the [models guide](https://opencode.ai/docs/models/) for model selection
|
|
and local models.
|
|
|
|
### Default agent
|
|
|
|
Choose the primary agent used when a session does not select one explicitly.
|
|
|
|
```jsonc
|
|
{
|
|
"default_agent": "build"
|
|
}
|
|
```
|
|
|
|
See the [agents guide](https://opencode.ai/docs/agents/) for built-in and custom
|
|
agents.
|
|
|
|
### Autoupdate
|
|
|
|
Control automatic updates. Set this to `false` to disable updates or `"notify"`
|
|
to receive update notifications.
|
|
|
|
```jsonc
|
|
{
|
|
"autoupdate": false
|
|
}
|
|
```
|
|
|
|
### Sharing
|
|
|
|
Control whether sessions can be shared manually, shared automatically, or not
|
|
shared at all.
|
|
|
|
```jsonc
|
|
{
|
|
"share": "manual"
|
|
}
|
|
```
|
|
|
|
See the [sharing guide](https://opencode.ai/docs/share/) for more details.
|
|
|
|
### Username
|
|
|
|
Set the username displayed in conversations.
|
|
|
|
```jsonc
|
|
{
|
|
"username": "alice"
|
|
}
|
|
```
|
|
|
|
### Permissions
|
|
|
|
Define ordered rules that allow, deny, or ask before an agent uses a tool on a
|
|
matching resource.
|
|
|
|
```jsonc
|
|
{
|
|
"permissions": [
|
|
{
|
|
"action": "bash",
|
|
"resource": "git push *",
|
|
"effect": "ask"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
See the [permissions guide](https://opencode.ai/docs/permissions/) for rule
|
|
matching and available actions.
|
|
|
|
### Agents
|
|
|
|
Override built-in agents or define specialized agents with their own model,
|
|
instructions, mode, and permissions.
|
|
|
|
```jsonc
|
|
{
|
|
"agents": {
|
|
"reviewer": {
|
|
"description": "Review changes without editing files",
|
|
"mode": "subagent",
|
|
"system": "Focus on correctness, security, and missing tests.",
|
|
"permissions": [
|
|
{ "action": "edit", "resource": "*", "effect": "deny" }
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [agents guide](https://opencode.ai/docs/agents/) for all agent options
|
|
and file-based agents.
|
|
|
|
### Snapshots
|
|
|
|
Enable or disable the snapshots used by undo and revert behavior.
|
|
|
|
```jsonc
|
|
{
|
|
"snapshots": false
|
|
}
|
|
```
|
|
|
|
### Watcher
|
|
|
|
Ignore files and directories that should not trigger filesystem updates.
|
|
|
|
```jsonc
|
|
{
|
|
"watcher": {
|
|
"ignore": ["dist/**", "coverage/**"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Formatter
|
|
|
|
Enable built-in formatters, disable formatting entirely, or configure formatter
|
|
commands by name.
|
|
|
|
```jsonc
|
|
{
|
|
"formatter": {
|
|
"prettier": {
|
|
"command": ["bunx", "prettier", "--write", "$FILE"],
|
|
"extensions": [".js", ".ts", ".tsx"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [formatters guide](https://opencode.ai/docs/formatters/) for built-in
|
|
formatters and custom commands.
|
|
|
|
### LSP
|
|
|
|
Enable built-in language servers, disable them, or configure servers by name.
|
|
|
|
```jsonc
|
|
{
|
|
"lsp": {
|
|
"typescript": {
|
|
"command": ["typescript-language-server", "--stdio"],
|
|
"extensions": [".ts", ".tsx"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [LSP guide](https://opencode.ai/docs/lsp/) for language server setup.
|
|
|
|
### Attachments
|
|
|
|
Control how oversized image attachments are resized or rejected before they are
|
|
sent to a model.
|
|
|
|
```jsonc
|
|
{
|
|
"attachments": {
|
|
"image": {
|
|
"auto_resize": true,
|
|
"max_width": 2000,
|
|
"max_height": 2000,
|
|
"max_base64_bytes": 5242880
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Tool output
|
|
|
|
Set the maximum number of lines and bytes retained from a tool result.
|
|
|
|
```jsonc
|
|
{
|
|
"tool_output": {
|
|
"max_lines": 2000,
|
|
"max_bytes": 51200
|
|
}
|
|
}
|
|
```
|
|
|
|
### MCP
|
|
|
|
Configure local and remote Model Context Protocol servers. Global timeouts can
|
|
be overridden by an individual server.
|
|
|
|
```jsonc
|
|
{
|
|
"mcp": {
|
|
"servers": {
|
|
"playwright": {
|
|
"type": "local",
|
|
"command": ["bunx", "@playwright/mcp"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [MCP guide](https://opencode.ai/docs/mcp-servers/) for remote servers,
|
|
OAuth, environment variables, and timeouts.
|
|
|
|
### Compaction
|
|
|
|
Control automatic context compaction and how much recent context it preserves.
|
|
|
|
```jsonc
|
|
{
|
|
"compaction": {
|
|
"auto": true,
|
|
"keep": {
|
|
"tokens": 8000
|
|
},
|
|
"buffer": 20000
|
|
}
|
|
}
|
|
```
|
|
|
|
### Skills
|
|
|
|
Add directories or URLs that OpenCode should search for agent skills.
|
|
|
|
```jsonc
|
|
{
|
|
"skills": ["./team-skills", "https://example.com/.well-known/skills/"]
|
|
}
|
|
```
|
|
|
|
See the [skills guide](https://opencode.ai/docs/skills/) for skill structure and
|
|
automatic discovery under `.opencode/skills/`.
|
|
|
|
### Commands
|
|
|
|
Define reusable slash commands as named prompt templates.
|
|
|
|
```jsonc
|
|
{
|
|
"commands": {
|
|
"review": {
|
|
"description": "Review the current changes",
|
|
"template": "Review the current diff for correctness and missing tests."
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [commands guide](https://opencode.ai/docs/commands/) for arguments,
|
|
models, agents, and file-based commands.
|
|
|
|
### Instructions
|
|
|
|
Load additional instruction files, globs, or URLs into the agent's context.
|
|
|
|
```jsonc
|
|
{
|
|
"instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"]
|
|
}
|
|
```
|
|
|
|
See the [rules guide](https://opencode.ai/docs/rules/) for project instructions
|
|
and `AGENTS.md`.
|
|
|
|
### References
|
|
|
|
Make local directories or Git repositories available as named supporting
|
|
context.
|
|
|
|
```jsonc
|
|
{
|
|
"references": {
|
|
"docs": {
|
|
"path": "../product-docs",
|
|
"description": "Product behavior and terminology"
|
|
},
|
|
"effect": {
|
|
"repository": "Effect-TS/effect",
|
|
"branch": "main"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [references guide](https://opencode.ai/docs/references/) for shorthand,
|
|
visibility, and path resolution.
|
|
|
|
### Plugins
|
|
|
|
Load plugins from packages or local files. Use the object form when a plugin
|
|
accepts options.
|
|
|
|
```jsonc
|
|
{
|
|
"plugins": [
|
|
"opencode-example-plugin",
|
|
{
|
|
"package": "./plugins/local.ts",
|
|
"options": {
|
|
"enabled": true
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
See the [plugins guide](/plugins) for plugin development and configuration.
|
|
|
|
### Providers
|
|
|
|
Configure providers and add or override their models, request settings,
|
|
headers, and model variants.
|
|
|
|
```jsonc
|
|
{
|
|
"providers": {
|
|
"openai": {
|
|
"models": {
|
|
"gpt-5.2-custom": {
|
|
"modelID": "gpt-5.2",
|
|
"name": "GPT-5.2 Custom",
|
|
"limit": {
|
|
"context": 200000,
|
|
"output": 32000
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
See the [providers guide](https://opencode.ai/docs/providers/) for credentials,
|
|
custom endpoints, provider packages, and model configuration.
|