官方教程中文版个性化
配置 OpenCode
基于 OpenCode 官方 Config 文档，帮助新手理解 opencode.json、配置合并、优先级和最小配置策略。
OpenCode 使用 JSON 或 JSONC 配置。新手不需要先复制完整官方示例，先理解配置文件如何合并、哪个位置适合放什么、哪些设置不该一开始就改。
先理解配置合并
OpenCode 的配置不是简单替换，而是多层合并。后加载的配置在键冲突时覆盖前面的配置，非冲突设置会保留。
这意味着：你在全局配置里设置主题，在项目配置里设置模型，最终两者都会生效。排错时不要只看一个文件，要看所有配置来源。
配置优先级怎么记
官方加载顺序大致是：
- 远程组织配置。
- 全局配置。
OPENCODE_CONFIG指定的自定义配置。- 项目根目录
opencode.json。 .opencode目录里的 agents、commands、plugins 等。OPENCODE_CONFIG_CONTENT内联配置。
后面的来源优先级更高。新手最常用的是全局配置和项目配置，其他入口先不要碰。
新手应该把配置放哪里
建议分工：
- 全局配置：主题、个人偏好、默认模型、个人 provider。
- 项目配置：这个项目需要共享的模型、tools、agents、instructions。
.opencode目录：项目级 agents、commands、plugins、skills、themes 等结构化扩展。- 环境变量覆盖：临时测试或 CI 场景。
不要把个人 API key、个人路径、本机实验配置提交到项目仓库。
最小配置策略
新手第一次配置只需要解决一个问题：让 OpenCode 在当前项目里可用。
优先顺序：
- 先通过
/connect配 provider 凭据。 - 再用
/models确认模型可用。 - 只在需要时写默认 model。
- 只在团队需要共享时写项目
opencode.json。 - 使用 schema 做校验。
不要为了“完整”配置 TUI、server、tools、provider、theme、agent、MCP、formatter。改得越多，排错越难。
tools 和 server 配置要谨慎
tools 会影响 Agent 能做什么，例如是否能写文件、运行 bash。server 会影响 opencode serve 和 opencode web 的网络暴露方式。
新手原则：
- 不需要 web server，就不要改 server。
- 不理解风险前，不要放宽 tools。
- 需要浏览器客户端访问 server 时，才考虑 CORS。
- 共享配置里不要写只适合你本机的端口和 hostname。
新手常见坑
- 全量复制官方 config 示例。
- 不知道配置会合并，误判某个旧设置还在生效。
- 把项目配置当个人配置用。
- 用环境变量覆盖后忘记清理。
- 不看 schema 提示，靠试错改 JSON。
- 一次改很多项，无法定位问题。
怎么判断配置健康
健康标准：
- 全局配置和项目配置职责分开。
- 项目
opencode.json可以提交给团队。 - 本机私有信息没有进仓库。
- 当前模型、tools 和 instructions 来源可解释。
- 配置能通过 schema 校验。
- 出问题时可以回到最小配置重测。
配置的目标是让 OpenCode 行为可预测，不是把所有能力一次性打开。
官方资料
© Anomaly
最近更新：2026年5月4日