opencode 配置详解:opencode.json

opencode 用 opencode.json 或 opencode.jsonc(带注释的 JSON)配置。加上 $schema 后编辑器可获得校验与自动补全:

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

文件位置与优先级

配置文件是合并而非替换——只有冲突的 key 才由后面的来源覆盖。加载顺序(后者优先):

远程配置——域名下的 .well-known/opencode,组织默认
全局配置——~/.config/opencode/opencode.json
自定义路径——OPENCODE_CONFIG 环境变量
项目配置——项目根目录的 opencode.json
.opencode 目录——agents/、commands/、modes/、plugins/、skills/、themes/、tools/(复数名;单数名也兼容)
自定义目录——OPENCODE_CONFIG_DIR 环境变量:指向一整个额外配置目录,在全局与 .opencode 目录之后加载
内联配置——OPENCODE_CONFIG_CONTENT 环境变量
受管配置——管理员控制的文件
macOS 受管偏好——MDM 下发,最高优先级

即:全局默认 → 项目覆盖 → 受管策略兜底。

关键字段

model / small_model——默认模型与小任务廉价模型,格式 provider/model。
provider——provider 专属选项(API key 也可走环境变量,见 providers 文档)。
agent——定义或覆盖 agents;default_agent 指定主 agent。
mcp——MCP server 定义(local 命令型或 remote URL 型)。
plugin——启动时加载的 npm 插件包(见插件开发指南)。
permission——细粒度工具权限(edit、shell、webfetch 等;shell 工具由 bash 改名而来,见权限指南)。
formatter——按语言的代码格式化器。
lsp——LSP server 覆盖。
tools——启停单个内置工具。
command——内联定义或覆盖斜杠命令(见命令指南)。
snapshot——文件快照/回滚追踪。
autoupdate——启动自更新。
theme、keybinds、tui——已废弃,自动迁移(见下)。
disabled_providers / enabled_providers——限制 provider 列表。
instructions——AGENTS.md 之外的额外指令文件。

TUI 配置是独立文件

界面设置在 tui.json / tui.jsonc——滚动速度、diff 样式、光标样式、鼠标与桌面 attention 通知:

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "diff_style": "auto",
  "cursor": { "style": "block", "blinking": true },
  "attention": { "enabled": true, "notifications": true, "sound": true }
}

用 OPENCODE_TUI_CONFIG 指向自定义路径。opencode.json 里的旧版 theme/keybinds/tui 会被自动迁移。

团队建议

项目级 opencode.json 提交到 Git 共享默认;个人偏好放全局文件。
域名可通过 /.well-known/opencode 下发组织默认,合并层级低于全局配置。
密钥走环境变量,不进提交的文件。

文件位置与优先级

关键字段

TUI 配置是独立文件

团队建议

延伸阅读