OpenCode:为代码仓库配置 AI 编程代理
OpenCode 是开源编程代理,提供终端、桌面和网页界面。实际效果取决于所连接的模型,以及提供给它的代码仓库上下文。本文依据 2026 年 11 月 15 日核查的 v2 文档;旧教程可能采用不同的配置字段。安装指南列出了受支持的软件包和 /connect 提供商连接命令。
连接仓库与模型提供商
安装适合操作系统的版本,进入项目目录并运行 opencode。使用 /connect 配置当前账号可访问的提供商。客户端能正常工作,不代表模型调用免费:仍需遵守提供商的计费和数据处理规则。
在仓库创建 opencode.jsonc,加入下方 schema。配置参考解释了项目、全局和受管理配置之间的关系。如果设置没有生效,应检查这些层级;受管理配置可以覆盖项目选项。不要把凭据写入会提交的文件。
明确命令执行边界
下面的 v2 示例要求执行 shell 命令前确认,禁止推送,并在访问项目外目录前询问:
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git push *", "effect": "deny" },
{ "action": "external_directory", "resource": "*", "effect": "ask" }
]
}
最后一条匹配的权限规则生效,也要检查特定代理的覆盖规则。这些属于工具权限,并不是操作系统级沙箱。权限参考说明了动作名称和匹配行为。
调查一个具体缺陷
遇到表单重复提交,可以先交给 Plan:“追踪提交处理函数和网络请求,说明为什么点击一次产生两次请求,并提出最小修正。”Plan 避免修改普通项目文件,但 shell 命令仍受权限规则控制。Build 负责实施修改,具体区别见代理参考。
把定位到的文件和验收要求交给 Build:每次点击只发一个请求,保留现有校验,并添加重复提交的回归检查。要求复用现有测试框架,报告真实的命令输出。解释听起来合理,并不能证明代码正确。
采用前检查结果
查看 git diff,执行相关测试和仓库要求的检查,审查意外出现的依赖或生成文件变更。保留干净的 Git 检查点:文件系统撤销无法逆转远程操作或数据库修改。用同一缺陷比较不同提供商,记录审查时间、剩余失败和实际调用费用。这才是可用的选型记录,无需编造跑分,也不能假设所有模型行为一致。