配置
OpenCode 使用 JSON 配置系统进行自定义。配置模式定义在 opencode.ai/config.json，支持编辑器验证和自动补全。
格式支持
OpenCode 同时支持 JSON 和 JSONC（带注释的 JSON）格式。
{
"$schema": "https://opencode.ai/config.json",
"theme": "opencode",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true
}配置位置和优先级
设置会 合并而非替换。加载顺序（后面的覆盖前面的冲突项）：
- 远程配置 – 来自
.well-known/opencode的组织默认设置 - 全局配置 –
~/.config/opencode/opencode.json中的用户偏好 - 自定义配置 –
OPENCODE_CONFIG环境变量 - 项目配置 – 项目根目录的
opencode.json .opencode目录 – Agents、命令、插件- 内联配置 –
OPENCODE_CONFIG_CONTENT环境变量
全局配置
在 ~/.config/opencode/opencode.json 中放置用户级偏好：
{
"theme": "catppuccin",
"model": "anthropic/claude-sonnet-4-5"
}项目配置
在项目根目录添加 opencode.json 用于项目特定设置。
自定义路径
export OPENCODE_CONFIG=/path/to/config.json
opencode run "Hello world"配置模式
TUI 设置
{
"tui": {
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto"
}
}服务器设置
{
"server": {
"port": 4096,
"hostname": "0.0.0.0",
"mdns": true,
"cors": ["http://localhost:5173"]
}
}工具配置
{
"tools": {
"write": false,
"bash": false
}
}模型和 Provider
{
"provider": {},
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}Agents
{
"agent": {
"code-reviewer": {
"description": "代码审查最佳实践",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "你是一个代码审查者...",
"tools": {
"write": false,
"edit": false
}
}
}
}自定义命令
{
"command": {
"test": {
"template": "运行完整测试套件并生成覆盖率报告。",
"description": "运行带覆盖率的测试",
"agent": "build"
}
}
}权限
{
"permission": {
"edit": "ask",
"bash": "ask"
}
}上下文压缩
{
"compaction": {
"auto": true,
"prune": true
}
}MCP 服务器
{
"mcp": {}
}插件
{
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}变量替换
环境变量
{
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}文件内容
{
"provider": {
"openai": {
"options": {
"apiKey": "{file:~/.secrets/openai-key}"
}
}
}
}