叶云梦天

OpenCode 项目配置文件完全指南：用 opencode.json 掌控你的 AI 编程环境

引言

OpenCode 作为一款功能强大的终端 AI 编程助手，其灵活性很大程度上来自于它的配置系统。除了我们之前介绍过的 AGENTS.md 规则文件和 Skills 技能系统，OpenCode 还提供了一个核心的 JSON 配置文件——opencode.json，它是控制模型选择、权限策略、Agent 行为、集成工具的中央枢纽。

无论你是个人开发者还是团队管理者，掌握 opencode.json 的配置方式，都能让你对 AI 编程环境拥有更精细的控制力。本文将从头到尾拆解每一项配置选项，并结合实际场景给出最佳实践建议。

配置文件的位置与优先级

OpenCode 的配置系统采用了多层合并机制——不同位置的配置文件会被合并在一起，而不是相互覆盖。这意味着你可以把通用设置放在全局配置里，把项目特定配置放在项目根目录，两者互不冲突。

配置源的加载顺序如下（越靠后优先级越高）：

远程配置（来自 .well-known/opencode）——组织级默认配置

全局配置（~/.config/opencode/opencode.json）——用户个人偏好

自定义配置（通过 OPENCODE_CONFIG 环境变量指定）

项目配置（项目根目录的 opencode.json）——项目特定设置

.opencode 目录——agents、commands、plugins 等

内联配置（通过 OPENCODE_CONFIG_CONTENT 环境变量指定）

托管配置（macOS 的 /Library/Application Support/opencode/、Linux 的 /etc/opencode/）

macOS MDM 托管偏好（.mobileconfig 文件）——最高优先级，不可被覆盖

对于日常开发来说，我们最常打交道的是全局配置和项目配置这两个层级。一个简单的例子：如果全局配置设置了 autoupdate: true，而项目配置设置了 model: "anthropic/claude-sonnet-4-5"，那么最终生效的配置会同时包含这两个设置。

# 全局配置路径（Linux/macOS）
~/.config/opencode/opencode.json

# 全局配置路径（Windows）
%USERPROFILE%\.config\opencode\opencode.json

# 项目配置路径
/your-project/opencode.json

当你在项目中运行 opencode 时，它会从当前目录向上查找，直到找到 Git 仓库的根目录，加载沿途的 opencode.json 文件。这意味着 monorepo 项目可以在不同子包中放置不同的配置文件。

文件格式与 Schema

OpenCode 同时支持 JSON 和 JSONC（带注释的 JSON）两种格式。我个人推荐使用 opencode.jsonc 的命名方式，这样可以为配置项添加注释，便于团队协作时理解各项配置的意图。

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

添加 $schema 字段后，VS Code 等编辑器可以提供自动补全和校验功能，这对新手尤其友好。完整的 Schema 定义可以在 opencode.ai/config.json 查看。

核心配置项详解

模型与提供商

这是每个用户最先需要配置的部分。通过 model 字段指定默认模型，通过 provider 字段配置 API 密钥和高级选项：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    },
    "openai": {
      "options": {
        "timeout": 300000
      }
    }
  }
}

几个关键参数说明：

model：主模型，格式为 provider-id/model-id
small_model：轻量任务（如标题生成）所用的模型，通常用更便宜的 haiku 类模型
timeout：请求超时时间（毫秒），默认 300000（5分钟），可设为 false 取消限制
chunkTimeout：流式响应中每个 chunk 的超时时间
setCacheKey：确保请求携带缓存键，可降低 API 费用

如果你想灵活切换模型而不修改配置文件，可以使用环境变量：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

提供商白名单与黑名单

在团队或企业环境中，你可能需要限制可用的 AI 提供商。OpenCode 提供了 enabled_providers（白名单）和 disabled_providers（黑名单）两个选项：

{
  // 只允许使用 Anthropic 和 OpenAI
  "enabled_providers": ["anthropic", "openai"],

  // 或禁用特定提供商
  "disabled_providers": ["gemini", "groq"]
}

需要注意的是，disabled_providers 的优先级高于 enabled_providers。如果某个提供商同时出现在两个列表中，它将被禁用。

Agent 配置

OpenCode 允许为不同任务定义专门的 Agent，每个 Agent 可以有自己的模型、System Prompt 和工具权限：

{
  "agent": {
    "code-reviewer": {
      "description": "专注于代码审查，检查安全性和性能问题",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一名资深代码审查员，专注于安全、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    },
    "test-writer": {
      "description": "为代码编写测试",
      "model": "anthropic/claude-haiku-4-5",
      "prompt": "你是一名测试工程师，专注于编写全面且可维护的测试。"
    }
  },
  "default_agent": "code-reviewer"
}

你可以用 default_agent 指定启动时的默认 Agent。这个 Agent 必须是主 Agent（不能是 subagent）。内置的 build 和 plan Agent 也可以作为默认值。

subagent_depth 控制子 Agent 能够嵌套调用的深度。默认为 1，即主 Agent 可以启动子 Agent，但子 Agent 不能再启动更深的子 Agent：

{
  "subagent_depth": 2  // 允许子 Agent 再启动一层子 Agent
}

Shell 配置

OpenCode 的终端工具默认会自动检测当前系统的 Shell，但你也可以手动指定：

{
  "shell": "pwsh"     // Windows 上使用 PowerShell
}

{
  "shell": "/bin/zsh"  // Linux/macOS 上使用 Zsh
}

工具开关

你可以精细控制 Agent 能够使用的工具：

{
  "tools": {
    "write": true,     // 文件写入
    "edit": true,      // 文件编辑
    "bash": true,      // 命令行执行
    "read": true,      // 文件读取
    "grep": true,      // 内容搜索
    "glob": true,      // 文件匹配
    "task": true,      // 子 Agent 任务
    "webfetch": true,  // 网页抓取
    "websearch": true  // 网页搜索
  }
}

如果你在某些项目中只想让 AI 做代码审查，可以关掉写入类工具：

{
  "tools": {
    "write": false,
    "edit": false,
    "bash": false
  }
}

权限控制

默认情况下，OpenCode 允许所有操作不需要确认。对于谨慎的开发者或企业环境，建议开启权限审批：

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

权限粒度可以很细，甚至可以针对特定命令做更严格的控制：

{
  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "rm -rf *": "deny",
      "git push --force": "deny"
    }
  }
}

策略控制

使用实验性的 policies 配置可以限制特定资源的操作：

{
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

上下文压缩

长对话会消耗大量 Token，OpenCode 的 compaction 系统可以自动压缩上下文：

{
  "compaction": {
    "auto": true,        // 当上下文满了自动压缩
    "prune": false,      // 是否清理旧工具输出以节省 Token
    "reserved": 10000    // 压缩时保留的 Token 缓冲
  }
}

快照系统

OpenCode 默认启用快照系统，用于跟踪 Agent 的文件变更，方便你使用 /undo 和 /redo 回滚操作：

{
  "snapshot": false  // 对于大型仓库可禁用快照以提升性能
}

注意：禁用快照后，你将无法通过 UI 回滚 Agent 的修改。如果项目代码量特别大、子模块特别多，快照系统可能导致索引缓慢和磁盘占用增大，这时可以考虑关闭。

文件监听

可以通过 watcher 配置忽略不需要监听的目录，避免不必要的性能开销：

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

代码格式化

启用代码格式化功能，让 OpenCode 在修改代码后自动运行 formatter：

{
  "formatter": true
}

也可以进行更精细的控制：

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

LSP 集成

启用 LSP（Language Server Protocol）可以让 OpenCode 获得语法检查和代码智能感知能力：

{
  "lsp": true
}

同样支持精细配置，比如禁用某个语言的 LSP：

{
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

MCP 服务器

MCP（Model Context Protocol）服务器扩展了 OpenCode 的能力边界。配置方式非常简洁：

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://context7.com/mcp",
      "enabled": true
    },
    "my-local-server": {
      "type": "local",
      "command": ["node", "./mcp-server/index.js"]
    }
  }
}

插件系统

通过 npm 包名加载社区插件：

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

插件文件也可以直接放在 .opencode/plugins/ 或 ~/.config/opencode/plugins/ 目录下。

指令文件

instructions 字段允许你指定额外的规则文件，OpenCode 会将这些文件的内容注入到 Agent 的 System Prompt 中：

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

路径支持 glob 模式，你可以一次性导入整个规则目录。

自定义命令

在配置中直接定义可复用的命令模板：

{
  "command": {
    "test": {
      "template": "运行完整的测试套件并生成覆盖率报告，集中关注失败的测试用例并给出修复建议。",
      "description": "运行测试并分析覆盖率",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的新 React 组件，使用 TypeScript，包含完整的类型定义和基本结构。",
      "description": "快速创建 React 组件"
    }
  }
}

自动更新

控制 OpenCode 在启动时是否自动下载新版本：

{
  "autoupdate": false     // 关闭自动更新
}

{
  "autoupdate": "notify"  // 不自动下载，但提示有新版本
}

注意：如果你通过 Homebrew 等包管理器安装 OpenCode，自动更新功能不会生效。

分享功能

控制对话分享的行为：

{
  "share": "auto"     // 自动分享新对话
}

可选值：

"manual"：手动分享，需要显式执行 /share 命令（默认）
"auto"：自动分享所有新对话
"disabled"：完全禁用分享功能

服务端配置

如果你使用 opencode serve 或 opencode web 命令，可以配置 Web 服务参数：

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

图片附件

当你在对话中拖拽图片时，OpenCode 会自动调整图片大小以适配模型的限制：

{
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

TUI 独立配置

TUI（终端界面）相关的设置建议放在独立的 tui.json 文件中：

// ~/.config/opencode/tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

项目级别的 TUI 设置可以在项目根目录放置 tui.json。

变量替换

OpenCode 的配置支持两种变量替换机制，这对保护敏感信息和提升配置灵活性非常有帮助。

环境变量引用

使用 {env:VARIABLE_NAME} 语法引用环境变量：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

文件内容引用

使用 {file:path} 语法加载文件内容，常用于管理 API Key 或引入大段指令：

{
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

文件路径可以是相对于配置文件目录的路径，也可以是绝对路径（以 / 或 ~ 开头）。

实战配置模板

下面是一个生产级项目的 opencode.jsonc 模板，涵盖了大部分常用配置：

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

  // 模型配置
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",

  // 提供商配置
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  },

  // 权限管理 —— 所有修改操作需要确认
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "write": "ask"
  },

  // 上下文管理
  "compaction": {
    "auto": true,
    "reserved": 8000
  },

  // 文件监听排除
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      ".git/**",
      "*.log",
      "coverage/**"
    ]
  },

  // 代码格式化
  "formatter": true,

  // LSP 集成
  "lsp": true,

  // 自定义命令
  "command": {
    "lint": {
      "template": "运行 ESLint 和 Prettier 检查，报告所有错误和警告，集中在项目 src 目录。",
      "description": "代码质量检查"
    },
    "test": {
      "template": "运行 jest 测试套件，显示覆盖率报告，重点分析未通过的测试。",
      "description": "运行测试",
      "model": "anthropic/claude-haiku-4-5"
    }
  },

  // 规则文件
  "instructions": [".cursor/rules/*.md", "CONTRIBUTING.md"]
}

最佳实践

1. 分层配置

将全局性的偏好（API Key、主题、快捷键）放在全局 ~/.config/opencode/opencode.json 中；将项目特有的约束（模型选择、权限策略、格式化规则）放在项目 opencode.json 中，并提交到 Git 仓库让整个团队共享。

2. 使用环境变量保护敏感信息

永远不要把 API Key 硬编码在配置文件中，特别是需要提交到 Git 仓库的项目配置。使用 {env:API_KEY} 或 {file:~/.secrets/key} 来引用敏感数据。

3. 善用 $schema

在配置文件中加入 $schema 字段，这样你的编辑器就能提供自动补全和配置校验。这是避免配置拼写错误最简单有效的方法。

4. 团队协作时开启权限确认

在企业项目中，建议在项目级配置中将 edit 和 bash 设为 "ask" 模式，防止 AI 在不经确认的情况下执行危险操作。

5. 为不同任务创建专用 Agent

不要只使用默认的 build Agent。为代码审查、测试编写、文档生成等不同任务创建专门的 Agent，每个 Agent 配置合适的模型和工具权限，这样既节省 Token 又提升输出质量。

6. 定期审视 experimental 选项

实验性选项可能随时变化或被移除。如果你的配置依赖实验性特性，建议密切关注 OpenCode 的更新日志。

总结

opencode.json 不仅仅是一个配置文件——它是你与 OpenCode 之间的"使用合约"。通过合理配置，你可以：

精确控制 AI 使用哪些模型和提供商
建立适度安全的事前审批机制
为不同场景定制专门的 Agent
让整个团队共享统一的开发规范

OpenCode 的配置系统设计得相当灵活，从环境变量到文件引用，从全局到项目层级，每一项都经过深思熟虑。花一点时间梳理你的需求，定制一份属于你的 opencode.json，AI 编程的效率和安全性都会得到质的提升。

OpenCode 项目配置文件完全指南：用 opencode.json 掌控你的 AI 编程环境

OpenCode 项目配置文件完全指南：用 opencode.json 掌控你的 AI 编程环境

引言

配置文件的位置与优先级

文件格式与 Schema

核心配置项详解

模型与提供商

提供商白名单与黑名单

Agent 配置

Shell 配置

工具开关

权限控制

策略控制

上下文压缩

快照系统

文件监听

代码格式化

LSP 集成

MCP 服务器

插件系统

指令文件

自定义命令

自动更新

分享功能

服务端配置

图片附件

TUI 独立配置

变量替换

环境变量引用

文件内容引用

实战配置模板

最佳实践

1. 分层配置

2. 使用环境变量保护敏感信息

3. 善用 $schema

4. 团队协作时开启权限确认

5. 为不同任务创建专用 Agent

6. 定期审视 experimental 选项

总结

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客