OpenCode 的分层配置看似只是“哪个文件覆盖哪个文件”，实际涉及团队规范、个人偏好、项目差异与临时运行参数之间的边界设计。如果只追求统一，项目会失去调整空间；如果允许任意覆盖，团队默认又容易形同虚设。合理做法不是减少配置层，而是明确每一层的职责、覆盖范围和审查方式。
先理解配置合并与优先级
OpenCode 支持 JSON 与 JSONC 配置。不同来源的配置通常采用合并方式加载，而不是由高优先级文件完整替换低优先级文件。发生键名冲突时，后加载的值覆盖先加载的值；没有冲突的设置则会共同保留。根据 官方配置文档[1]，常见层级包括组织远程配置、用户全局配置、自定义路径配置、项目配置、.opencode 目录配置以及内联运行配置等。
在项目目录内部，OpenCode 会从项目根目录向当前工作目录查找配置。直接放置的 opencode.json 或 opencode.jsonc 会按照目录层级合并，越接近当前目录的配置越晚生效。需要特别注意的是，.opencode 目录中的配置会在直接配置之后处理，因此可能覆盖距离当前目录更近的直接配置。除非团队确实需要这种效果，否则不宜在同一项目树中随意混用两种组织形式。
将团队默认设计成稳定基线
团队默认配置应承载跨项目普遍适用、变动频率较低的内容，例如推荐模型、基础权限策略、通用代理、共享命令、插件清单和默认关闭的 MCP 服务。它的定位是提供开箱即用的合理起点，而不是写入每个项目都必须无条件接受的全部细节。
组织可通过远程配置提供基础层，开发者也可在全局配置中保存个人范围的偏好。团队需要区分“建议默认值”和“强制约束”：前者允许项目覆盖，后者如果仅依赖普通低优先级配置，实际上无法阻止后续层修改。真正不可覆盖的安全或合规要求，应优先通过受管配置、权限系统、CI 检查或基础设施策略落实，而不是假设成员不会改动本地文件。
让项目覆盖保持最小且可解释
项目级配置适合表达仓库自身的客观差异，例如特定模型要求、项目专用代理、代码生成约束、仓库命令以及仅对当前系统有效的工具集成。建议项目文件只声明与团队默认不同的键，不要复制整份公共配置。这样既能减少重复，也能让代码评审快速识别项目究竟改了什么。
判断某项配置归属时，可以使用一个简单标准：如果切换到另一个仓库后仍然成立，它更可能属于团队层或用户层；如果由当前仓库的技术栈、目录结构或交付流程决定，它更适合进入项目层。
每个覆盖项还应说明原因。JSONC 支持注释，可用于记录覆盖背景、责任人、关联任务及复查条件。若团队选择 JSON，则可在仓库文档中建立配置说明。注释不必冗长，但应回答“为什么不能沿用默认值”，避免临时调整逐渐演变成无人敢删的永久配置。
控制个人偏好与临时覆盖
全局配置适合编辑器体验、个人常用模型或本机运行习惯，但不应承载项目正常工作所必需的设置。否则项目可能只在少数成员机器上运行，其他开发者难以复现。判断方法很直接：删除个人全局配置后，项目仍应具备可理解、可执行的基础行为。
通过环境变量指定的自定义配置或内联配置优先级较高，适合 CI、容器任务、故障排查和一次性实验。由于这类覆盖不一定进入版本库，最容易产生“本地结果正确但无法复现”的问题。团队应限制其使用场景，并要求关键流水线显式记录所采用的配置来源，禁止把长期项目差异隐藏在个人启动脚本中。
建立可执行的治理规则
- 维护配置职责清单：列出组织层、全局层、项目层和运行时层分别允许保存的内容。
- 项目配置纳入评审：涉及模型、权限、插件、代理或外部服务的变更，应由代码所有者审核。
- 使用配置 Schema：在文件中加入官方 Schema 地址，以获得字段校验和编辑器自动补全，并减少拼写错误。
- 检查敏感信息：令牌、密码和私有凭据不得写入项目配置，应通过受控的密钥或环境变量机制提供。
- 验证最终生效结果：排查问题时，不只查看某一个文件，而要按加载顺序检查同名键在哪里被覆盖。
单体仓库需要额外约束
在单体仓库中，根目录配置可保存所有子项目共享的规则，包目录只覆盖确实不同的部分。团队应统一使用直接配置或 .opencode 目录作为主要组织方式，避免两套形式交叉叠加。若必须混用，应在根目录文档中写明实际优先级，并设置最小示例帮助成员验证最终配置。
总结
兼顾团队一致性与项目可控性的关键，是把低优先级层做成稳定、宽松且安全的默认基线，把高优先级层限制为最小、透明且可审查的差异。团队配置负责降低接入成本，项目配置负责表达仓库事实，个人配置负责改善本机体验，运行时覆盖只处理短期场景。再配合职责清单、Schema 校验、代码评审和最终配置检查，分层优先级就不会成为隐性冲突来源，而会转化为清晰、可维护的协作机制。
