Config

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 格式示例，支持注释 opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

Locations

You can place your config in a couple of different locations and they have a different order of precedence.

[!NOTE] Configuration files are merged together, not replaced.

Config sources are loaded in this order (later sources override earlier ones):

Remote config (from .well-known/opencode) - organizational defaults
Global config (~/.config/opencode/opencode.json) - user preferences
Custom config (OPENCODE_CONFIG env var) - custom overrides
Project config (opencode.json in project) - project-specific settings
.opencode directories - agents, commands, plugins
Inline config (OPENCODE_CONFIG_CONTENT env var) - runtime overrides
Managed config files (/Library/Application Support/opencode/ on macOS) - admin-controlled
macOS managed preferences (.mobileconfig via MDM) - highest priority, not user-overridable

Remote

Organizations can provide default configuration via the .well-known/opencode endpoint.

// 远程配置示例 - 用于组织级默认配置 opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Place your global OpenCode config in ~/.config/opencode/opencode.json.

Per project

Add opencode.json in your project root.

[!TIP] Place project specific config in the root of your project.

Custom path

Specify a custom config file path using the OPENCODE_CONFIG environment variable.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Custom directory

Specify a custom config directory using the OPENCODE_CONFIG_DIR environment variable.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Managed settings

Organizations can enforce configuration that users cannot override.

// 各平台的托管配置目录

Platform	Path
macOS	`/Library/Application Support/opencode/`
Linux	`/etc/opencode/`
Windows	`%ProgramData%\opencode`

Schema

The server/runtime config schema is defined in opencode.ai/config.json.

Your editor should be able to validate and autocomplete based on the schema.

TUI

Use a dedicated tui.json (or tui.jsonc) file for TUI-specific settings.

// TUI 配置文件示例 tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

Server

// 服务器配置选项 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Available options:

port - 监听端口
hostname - 监听主机名，启用 mdns 时默认为 0.0.0.0
mdns - 启用 mDNS 服务发现，允许局域网内其他设备发现 OpenCode 服务器
mdnsDomain - 自定义 mDNS 域名，默认为 opencode.local
cors - 额外的 CORS 允许源，值必须是完整来源 (scheme + host + optional port)

Shell

// Shell 配置 - 指定交互终端使用的 Shell opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "shell": "pwsh"
}

Tools

// 工具管理配置 - 控制 LLM 可以使用哪些工具 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Models

// 模型配置 - 设置主要模型和小模型 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Provider options:

timeout - 请求超时时间（毫秒），默认 300000
chunkTimeout - 流式响应块之间的超时时间
setCacheKey - 确保始终为指定 provider 设置缓存键

Policies

// 策略配置 - 实验性功能，控制允许或拒绝 OpenCode 对配置资源执行操作 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

Image attachments

// 图片附件配置 - 控制图片大小限制和自动调整 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

Themes

// 主题配置 - 在 tui.json 中设置 UI 主题 tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

Agents

// Agent 配置 - 为特定任务配置专门的 Agent 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-5",
      "prompt": "You are a code reviewer.",
      "tools": {
        "write": false,
        "edit": false,
      },
    },
  },
}

Default agent

// 默认 Agent 配置 - 设置默认使用的 Agent opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

// 分享功能配置 - 控制 /share 功能的行为 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

"manual" - 允许通过命令手动分享（默认）
"auto" - 自动分享新对话
"disabled" - 完全禁用分享

Commands

// 自定义命令配置 opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
  },
}

Keybinds

// 键盘快捷键配置 tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "command_list": "ctrl+p"
  }
}

Snapshot

// 快照配置 - 控制文件变更跟踪（用于撤销功能） opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false
}

Autoupdate

// 自动更新配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

false - 禁用自动更新
"notify" - 不自动更新但有新版本时通知

Formatters

// 代码格式化器配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}

LSP Servers

// LSP 服务器配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

Permissions

// 权限配置 - 控制哪些操作需要用户批准 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Compaction

// 上下文压缩配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

auto - 上下文满时自动压缩（默认 true）
prune - 删除旧的工具输出来节省 token（默认 false）
reserved - 压缩时保留的 token 缓冲区

Watcher

// 文件监视器忽略模式配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

MCP servers

// MCP 服务器配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

Plugins

// 插件配置 - 扩展 OpenCode 功能 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Instructions

// 指令文件配置 - 为模型提供额外指令 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Disabled providers

// 禁用 provider 配置 - 阻止某些 provider 被加载 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

Enabled providers

// 启用 provider 白名单 - 只有列入的 provider 才会启用 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

[!NOTE] disabled_providers 优先级高于 enabled_providers

Experimental

// 实验性功能配置 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

Variables

Env vars

使用 {env:VARIABLE_NAME} 引用环境变量：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Files

使用 {file:path/to/file} 引用文件内容：

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Config

Config

Format

Locations

Remote

Global

Per project

Custom path

Custom directory

Managed settings

Schema

TUI

Server

Shell

Tools

Models

Policies

Image attachments

Themes

Agents

Default agent

Sharing

Commands

Keybinds

Snapshot

Autoupdate

Formatters

LSP Servers

Permissions

Compaction

Watcher

MCP servers

Plugins

Instructions

Disabled providers

Enabled providers

Experimental

Variables

Env vars

Files