OpenCode 通过 opencode.json（或 opencode.jsonc）配置文件控制所有运行时行为。全局配置放在 ~/.config/opencode/opencode.json，项目配置放在项目根目录。多个配置文件按优先级合并（不是覆盖），后者优先级更高。支持 {env:VAR} 和 {file:path} 变量替换，敏感信息（如 API Key）不必硬写在配置里。

OpenCode 配置文件（config）

OpenCode 使用 opencode.json（或带注释的 opencode.jsonc）作为配置文件，控制模型选择、权限、MCP 服务器等所有运行时行为。

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

---

配置文件位置与优先级

配置文件合并加载，不是替换——后加载的配置只覆盖冲突的键，非冲突键保留。

例如全局配置设了 autoupdate: true，项目配置设了 model: "..."，最终两个配置都生效。

优先级顺序（从低到高）

1. 远端配置（.well-known/opencode）— 组织级默认值
2. 全局配置（~/.config/opencode/opencode.json）— 用户偏好
3. 自定义配置（OPENCODE_CONFIG 环境变量）
4. 项目配置（项目根目录的 opencode.json）
5. .opencode 目录（agents/commands/plugins 等）
6. 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）— 运行时覆盖
7. 系统管理配置（macOS: /Library/Application Support/opencode/，Linux: /etc/opencode/，Windows: %ProgramData%\opencode）
8. macOS MDM 配置（最高优先级，用户无法覆盖）

小技巧：.opencode/ 和 ~/.config/opencode/ 目录下的子目录使用复数名称（agents/、commands/、plugins/ 等），单数形式（如 agent/）向后兼容仍支持。

全局配置

~/.config/opencode/opencode.json   # 运行时配置
~/.config/opencode/tui.json        # TUI 界面配置

全局配置适合存放 provider API Key、默认模型等用户级偏好。

项目配置

./opencode.json    # 项目运行时配置
./tui.json         # 项目 TUI 配置（可选）

项目配置建议提交到 Git，与团队共享。OpenCode 启动时从当前目录往上查找，直到 Git 根目录。

自定义路径

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

---

变量替换

配置文件中支持变量替换，适合引用环境变量或独立文件中的敏感信息。

引用环境变量

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

变量未设置时替换为空字符串。

引用文件内容

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

文件路径支持相对路径（相对于配置文件目录）和绝对路径（/ 或 ~ 开头）。

---

常用配置项

model / small_model

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model 用于标题生成等轻量任务，未指定时自动选择更便宜的模型（没有则 fallback 到主模型）。

provider 选项

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

• timeout：请求超时（ms），默认 300000，设为 false 禁用
• chunkTimeout：流式响应块超时（ms），超时则中止请求
• setCacheKey：确保始终设置缓存键

server

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

用于 opencode serve 和 opencode web 命令。mdns 开启后局域网内其他设备可发现你的 OpenCode 服务器。

permission

默认允许所有操作，可以改为每次操作前确认：

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

取值："allow"（允许）、"ask"（执行前确认）、"deny"（禁止）。

autoupdate

{
  "autoupdate": false
}

• true（默认）：自动下载新版本
• false：不自动更新
• "notify"：有新版本时提示，但不自动更新

仅对非 Homebrew 等包管理器安装的版本有效。

snapshot

OpenCode 默认开启快照功能，用于 /undo 回滚文件变更。大型仓库或多子模块项目可关闭以节省磁盘：

{
  "snapshot": false
}

关闭后 UI 中的撤销功能将不可用。

compaction

控制上下文压缩行为：

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

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

share

{
  "share": "manual"
}

• "manual"：手动通过 /share 命令分享（默认）
• "auto"：自动分享新会话
• "disabled"：禁用分享功能

default_agent

{
  "default_agent": "plan"
}

指定默认使用的 agent（必须是 primary agent）。不存在或为 subagent 时 fallback 到 "build" 并打印警告。

disabled_providers / enabled_providers

{
  "disabled_providers": ["openai", "gemini"],
  "enabled_providers": ["anthropic"]
}

disabled_providers 优先级高于 enabled_providers。被禁用的 provider 不会加载，其模型不出现在选择列表中。

instructions

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

指定额外的指令文件（支持 glob），与 AGENTS.md 合并加载。也可以是远程 URL（5 秒超时）。

watcher

{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

配置文件监听忽略模式（glob 语法），排除噪声目录。

formatter

{
  "formatter": {
    "prettier": { "disabled": true },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

---

TUI 配置（tui.json）

TUI 界面配置独立放在 tui.json（或 tui.jsonc），与运行时配置分离：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "keybinds": {
    "leader": "ctrl+x"
  },
  "scroll_speed": 3,
  "scroll_acceleration": { "enabled": true },
  "diff_style": "auto",
  "mouse": true
}

用 OPENCODE_TUI_CONFIG 环境变量指定自定义 TUI 配置路径。

注意：旧版在 opencode.json 中的 theme、keybinds、tui 键已废弃，迁移时会自动处理。

---

验证配置

用 $schema 字段开启编辑器自动补全和校验：

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

查看实际生效的合并配置：

opencode debug config

---

常见问题

Q: 项目配置和全局配置同时存在时，哪个生效？

A: 两者都生效，按优先级合并。项目配置优先级更高，冲突时项目配置的值覆盖全局配置。非冲突的配置项两者共同生效。

Q: 如何在不暴露 API Key 的情况下共享项目配置？

A: 在 opencode.json 中用 {env:ANTHROPIC_API_KEY} 引用环境变量，每个团队成员在自己的 .bashrc/.zshrc 中配置实际的 Key，配置文件本身可以安全提交到 Git。

Q: JSONC 和 JSON 格式有什么区别？

A: JSONC 支持注释（// 和 /* */），其他完全相同。文件名用 .jsonc 后缀即可，OpenCode 自动识别。