配置 OpenCode

OpenCode 使用 JSON 或 JSONC（JSON with Comments，比标准 JSON 多了 // 行注释和尾随逗号支持，调试团队配置时方便很多）配置。新手不需要先复制完整官方示例，先理解配置文件如何合并、哪个位置适合放什么、哪些设置不该一开始就改。

先给结论：配置越少，越容易排错

OpenCode 配置的目标是让行为可预测，不是把所有能力一次性打开。第一次只需要让 provider、模型和项目规则可用；server、tools、provider options、MCP、formatter、Agent、Plugin 都应该按需要逐步加。

flowchart LR
  Connect["/connect 保存凭据"] --> Models["/models 确认可用模型"]
  Models --> Global["全局配置：个人偏好"]
  Models --> Project["项目配置：团队共享默认值"]
  Project --> Validate["Schema / 类型检查"]
  Validate --> Minimal["出错时回到最小配置重测"]

  style Connect fill:#dbeafe,stroke:#3b82f6
  style Project fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Minimal fill:#fee2e2,stroke:#ef4444

配置是合并，不是只读一个文件

OpenCode 的配置不是简单替换，而是多层合并。后加载的配置在键冲突时覆盖前面的配置，非冲突设置会保留。

这意味着：你在全局配置里设置主题，在项目配置里设置模型，最终两者都会生效。排错时不要只看一个文件，要看所有配置来源。

加载优先级怎么记

官方配置会从多个来源加载，后面的来源优先级更高：

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）——管理员级别，需 root/admin 权限写入。
8. macOS 托管偏好（通过 MDM 推送的 .mobileconfig）——优先级最高，用户无法覆盖。

新手最常用的是全局配置和项目配置，其他入口先不要碰。OPENCODE_CONFIG_CONTENT 这类内联覆盖适合临时或自动化场景，不适合长期靠记忆维护。最后两层（托管配置 + MDM）一般只在企业部署里出现：如果你发现某些设置改不动，先用 opencode debug config 看实际生效值，确认是不是被托管配置接管了。

新手应该把配置放哪里

如果一个设置只服务你自己，放全局；如果团队成员都应该遵守，放项目；如果只是临时试验，用环境变量，试完清理。

最小配置策略

第一次配置只需要解决一个问题：让 OpenCode 在当前项目里可控可用。

优先顺序：

1. 通过 /connect 配 provider 凭据。
2. 用 /models 确认模型可用。
3. 只在需要时写默认 model。
4. 只在团队需要共享时写项目 opencode.json。
5. 使用 schema 做校验。

不要为了“完整”一次性配置 TUI、server、tools、provider、theme、agent、MCP、formatter。改得越多，排错越难。

tools 和 server 先保守

tools 会影响 Agent 能做什么，例如是否能写文件、运行 bash、访问外部工具。server 会影响 opencode serve 和 opencode web 的网络暴露方式。

新手原则：

• 不需要 Web 或远程访问，就不要改 server。
• 不理解风险前，不要放宽 tools。
• 需要浏览器客户端访问 server 时，才考虑 CORS（跨源资源共享白名单）。
• 共享配置里不要写只适合你本机的端口和 hostname。
• 如果要绑定 0.0.0.0，先处理认证和网络边界。

配置排错顺序

配置出问题时，先回到最小可用状态：

确认 /connect 凭据
  ↓
确认 /models 能看到模型
  ↓
临时移除项目级复杂配置
  ↓
检查环境变量覆盖
  ↓
再逐项恢复 server / tools / provider options

不要一边改 provider、一边改 tools、一边改 server。一次只改一个变量，才能知道问题是谁引入的。

新手常见坑

• 全量复制官方 config 示例。
• 不知道配置会合并，误判某个旧设置已经失效。
• 把项目配置当个人配置用。
• 用环境变量覆盖后忘记清理。
• 不看 schema 提示，靠试错改 JSON。
• 一次改很多项，无法定位问题。

怎么判断配置健康

健康标准：

• 全局配置和项目配置职责分开。
• 项目 opencode.json 可以提交给团队。
• 本机私有信息没有进仓库。
• 当前模型、tools 和 instructions 来源可解释。
• 配置能通过 schema 校验。
• 出问题时可以回到最小配置重测。

接下来去哪

官方资料

• OpenCode Config：https://opencode.ai/docs/config
• OpenCode Models：https://opencode.ai/docs/models
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Server：https://opencode.ai/docs/server