opencode.jsonc 配置指南：提交前做对 7 个检查

重点不只是文件放在哪里。把 opencode.jsonc 当成可审查的非密钥配置层：凭据留在仓库外，先弄清全局配置与项目配置如何合并，再验证 Provider、模型、权限和回滚路径，最后再提交给团队共用。

OpenCode 官方配置文档说明支持 JSON 和 JSONC，因此注释适合解释某个设置为什么存在。建议把注释写成运维说明：谁拥有这个选择、什么时候验证过、用哪个命令能证明它仍然有效。

好的配置文件不存密钥。模型选择、shell 偏好、工具开关、权限姿态和项目路径可以写进配置；API key、provider token、私有 base URL、代理密码和部署凭据应放在环境变量或对应 Provider 的凭据流程里。

官方文档把配置位置和优先级列得很清楚，并说明配置文件会合并而不是完全替换。这意味着全局偏好可能与项目里的模型或权限规则叠加，只有同一个键冲突时才由更高优先级覆盖。

个人使用时，全局配置适合放 Provider、编辑器习惯和个人 shell；团队协作时，项目配置更适合放所有人都应看到的规则，比如默认模型、忽略路径、命令姿态、MCP 决策和权限边界。

Provider 和模型字段应从当前官方文档或 Provider 控制台复制，不要用营销名称猜。JSON 语法正确不代表模型 ID 一定可用，错误通常会在真实请求时才暴露。

只在确实有价值时区分主模型和小模型，例如为了成本、速度、上下文窗口、本地可用性或合规要求。把选择理由写清楚，理由变化时就重新审查配置，而不是继续继承旧值。

权限是 opencode.jsonc 里最容易影响安全的部分。编辑和 shell 命令先保持 ask，等仓库证明哪些动作重复、可逆、低风险后，再把固定测试或格式化命令改成窄范围 allow。

不要因为一个提示很烦就放开整类命令。安装依赖、删除文件、迁移数据库、部署、push、密钥文件和仓库外目录都应保持 deny 或显式确认。agent 或 MCP 需要例外时，例外应靠近对应角色或集成。

加入官方 schema URL 可以让编辑器提示和校验字段。Schema 不是完整安全审查，但能提前发现拼错的键、错误的值结构和过时的假设。

Schema 之后还要人工检查：每个键是否非密钥、注释是否准确、项目规则是否真的该进仓库、哪些值会随版本变化。配置应让下一位维护者能读懂，而不只是让编辑器接受。

提交新 opencode.jsonc 前，先在一次性或低风险仓库里测试。可用时运行配置调试命令，再启动 OpenCode，列模型、读文件、做一次轻量编辑、执行预期测试命令，并确认被 deny 的动作确实不会运行。

验证结果最好写在配置旁或 PR 说明里：操作系统、shell、Provider、模型 ID、测试命令和回滚方式。这样配置不是猜测，而是可复现基线。

1. 创建最小文件先写 schema、模型选择和一个审查过的权限姿态。
2. 校验语法运行 JSONC-aware 校验或编辑器 schema 校验。
3. 确认层级判断全局、项目、自定义路径或托管配置谁生效。
4. 跑小任务读文件、做轻量编辑并执行一个已知命令。
5. 测试 deny尝试一个应被阻止的动作，确认它不会执行。
6. 记录回滚写清如何删除规则或不加载该配置启动。

配置出问题时，先隔离层级。按 JSONC 语法、当前目录、Git 根目录发现、全局覆盖、项目覆盖、环境变量、Provider 可用性、权限提示的顺序查，不要直接重写所有配置。

Windows 场景下，要把文件位置和 shell 行为分开看。项目配置有效，不代表集成终端能读到 Provider 环境变量；shell 字段也可能指向当前机器不存在的命令。