第五章：配置详解 —— 用新版 schema 定制 OpenCode

这一章重点修正很多旧教程里的过时写法。2026 年的 OpenCode 配置核心关键词是 opencode.json、provider、model、small_model、mcp 和 .opencode 目录。

1. 配置文件放在哪里？

官方文档明确支持多层配置，并且这些配置会合并，而不是简单覆盖。

• 全局配置：~/.config/opencode/opencode.json
• 项目配置：项目根目录下的 opencode.json
• TUI 配置：~/.config/opencode/tui.json
• 项目扩展目录：.opencode/agents、.opencode/commands、.opencode/skills

OpenCode 同时支持 JSON 和 JSONC 。如果你想写注释，更推荐用 JSONC。

2. 一份最小可用配置

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "share": "manual"
}

其中 model 是主力模型，small_model 是给标题生成、轻量任务等场景准备的更便宜模型。

3. 旧写法和新写法的区别

4. 常见配置场景

设置默认模型

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex"
}

如果你使用 OpenCode Zen，这种写法最直观。其他 provider 同理，格式都是 provider/model。

给内置 provider 指定 baseURL

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://your-gateway.example.com/v1"
      }
    }
  }
}

这适合你接入代理网关、企业统一中转层或 OpenAI 兼容接口。模型名字仍然要以 /models 显示结果为准。

给 provider 配置全局请求选项

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

这是新版 schema 里已经明确支持的通用 provider 级配置，适合网络不稳定或流式返回较慢的环境。

把主力模型和轻量模型分开

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

这是非常值得新手尽早掌握的配置技巧。复杂任务交给主力模型，标题生成、轻量总结之类的小任务交给 small_model，通常能在不明显损失体验的前提下降低成本。

把敏感信息从配置文件里拆出去

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

官方配置支持 {env:变量名} 和 {file:路径} 两种变量替换。对团队协作来说，这是比把 API Key 直接写进 opencode.json 更安全的做法。

• `AGENTS.md`：描述项目背景、约束、代码规范。
• `opencode.json`：项目级默认模型、权限、MCP、命令。
• `.opencode/agents`：自定义代理。
• `.opencode/commands`：把重复任务封装成命令。
• `.opencode/skills`：补充团队专属能力。

官方文档还特别说明：这些目录现在以复数命名为主，例如 agents/、commands/、skills/。 单数目录还兼容，但已经属于向后兼容路径。

6. 高需求配置技巧

技巧一：把“个人偏好”和“项目规则”分开

• 全局配置：放你个人常用模型、主题、快捷键、全局插件。
• 项目配置：放这个仓库必须统一的内容，例如默认 agent、watcher ignore、MCP、instructions。
• `AGENTS.md`：写人类规范和上下文，不要把所有规则都硬塞进 JSON。

很多用户觉得“配置越来越乱”，本质上是把个人习惯、团队要求和一次性实验全堆在一个文件里。

技巧二：给大仓库配置 watcher ignore

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**", ".next/**"]
  }
}

对前端、Monorepo 或构建输出较多的项目，这能明显减少噪音。用户体感上会更像“OpenCode 更懂项目”，其实背后经常只是你把无关目录排除了。

技巧三：先收紧权限，再慢慢放开

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

对刚开始用 OpenCode 的用户，这个配置特别有价值。它能让你先观察 OpenCode 想怎么改、想执行什么命令，再逐步把信任建立起来。

技巧四：用 instructions 管团队规范

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

如果你的团队已经有 Cursor Rules、贡献规范或测试约定，不需要重写一份新的 Prompt，直接通过 instructions 引入通常更稳。

7. MCP 配置的正确方向

如果你想让 OpenCode 直接连接 Jira、浏览器、数据库或内部平台，先记住一条： 新版官方配置文档使用的是 mcp 字段。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

如果你接的是本地 MCP server，请优先对照当前官方 schema 或文档示例来写，不要直接复制旧博客里的 mcpServers 模板。遇到配置冲突时，可以运行 opencode debug config 检查最终生效结果。

8. 高频踩坑与排错清单