适用场景
这套方案适合已经习惯在终端里干活、希望把 AI 编码能力装进自己仓库的开发者：不想被某一家云端 IDE 绑定，想用自有或自建的模型 API（包括公司内网的 OpenAI 兼容网关），同时需要一套能审计、能限权的自动化改动流程。它解决的问题是：让"读仓库 → 改代码 → 跑测试 → 提交"这条链路在终端里闭环，而不是在浏览器里复制粘贴。
环境与前置条件
- 操作系统：macOS、Linux 均可；Windows 建议在 WSL2 里跑，原生 PowerShell 的体验以官方文档为准。
- 运行时：需要 Node.js（LTS 版本即可）用于 npm 安装方式；如果用官方安装脚本，脚本会自行处理依赖。具体最低版本以官方文档当前版本为准。
- 终端：支持 256 色的现代终端（iTerm2、Windows Terminal、Ghostty、Kitty 等），TUI 界面依赖终端转义序列，老旧终端可能出现花屏。
- 磁盘：CLI 本体占用很小，预留 500MB 给依赖和缓存即可。
- 模型侧：一个可用的 API Key（Anthropic、OpenAI、Google 或任意 OpenAI 兼容端点），并确认该端点支持流式输出与工具调用（function calling）。不支持工具调用的模型在编码任务里基本不可用。
- Git：仓库需已初始化并至少有一次提交，方便用
git diff检查智能体的改动。
分步骤部署
第 1 步：安装 CLI
两种常见安装方式，任选其一。
官方安装脚本：
```bash
curl -fsSL https://opencode.ai/install | bash
```
（脚本地址与安装路径以官方文档当前版本为准，安装完成后脚本会打印实际落地目录。）
npm 方式：
```bash
npm install -g opencode-ai
```
Homebrew、Scoop 等其他渠道以官方文档为准。安装完成后确认命令可用：
```bash
opencode --version
```
能打印出版本号就说明二进制已经进入 PATH。如果提示 command not found，把安装脚本打印的 bin 目录加进 shell 配置：
```bash
export PATH="$HOME/.opencode/bin:$PATH"
```
写入 ~/.zshrc 或 ~/.bashrc 后重新打开终端。
第 2 步：登录模型账号
```bash
opencode auth login
```
交互界面里会列出可选的模型提供方，方向键选择后粘贴 API Key。凭据通常保存在 ~/.local/share/opencode/auth.json，该文件权限建议保持 600：
```bash
chmod 600 ~/.local/share/opencode/auth.json
```
查看已登录的提供方：
```bash
opencode auth list
```
能看到刚登录的提供方即成功。
第 3 步：接入自有模型 API（OpenAI 兼容端点）
如果用的是公司内网网关、vLLM、Ollama、LiteLLM 这类服务，用自定义 provider 接入。项目根目录新建 opencode.json：
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"internal": {
"npm": "@ai-sdk/openai-compatible",
"name": "Internal Gateway",
"options": {
"baseURL": "https://your-gateway.example.com/v1",
"apiKey": "{env:INTERNAL_API_KEY}"
},
"models": {
"coding-model": {
"name": "Coding Model"
}
}
}
}
}
```
要点说明：
baseURL一般要以/v1结尾，写错会出现 404。{env:INTERNAL_API_KEY}是配置文件的变量引用语法，避免把密钥写进 Git 仓库；配置里也支持{file:...}引用本地文件。models下的键名就是调用时使用的模型 ID，必须与网关实际暴露的名字一致，name只是显示名。
设置环境变量后重启终端：
```bash
export INTERNAL_API_KEY="你的密钥"
opencode models
```
opencode models 能列出 internal/coding-model 就说明接入成功。
第 4 步：写仓库规则文件 AGENTS.md
在仓库根目录创建 AGENTS.md，这是智能体每次启动都会读取的项目说明：
```markdown
项目说明
技术栈
- 前端：Vite + React + TypeScript
- 后端：Node.js + Fastify
- 测试：Vitest
约定
- 提交信息用中文，格式
类型: 描述 - 新增依赖前必须说明理由
- 所有导出函数补 JSDoc
- 不要改动
migrations/下的历史文件
常用命令
- 安装依赖：
pnpm install - 跑测试：
pnpm test - 类型检查：
pnpm typecheck
```
在 TUI 里输入 /init 也可以让智能体扫描仓库自动生成一份初稿，再手工精修。文件不超过一屏效果通常更好。
第 5 步：配置权限
默认行为以官方文档为准，建议显式声明，避免智能体在没打招呼的情况下执行破坏性命令。在同一份 opencode.json 里加：
```json
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"bash": {
"*": "ask",
"git status": "allow",
"git diff*": "allow",
"git log*": "allow",
"ls*": "allow",
"cat*": "allow",
"rm -rf*": "deny",
"curl*": "deny"
}
}
}
```
三个取值：allow 直接执行，ask 每次弹窗确认，deny 直接拒绝。规则按最长匹配优先，所以 git diff* 会盖住 *。刚开始建议全部 ask，跑顺了再逐步放开只读命令。
第 6 步：定义子智能体
子智能体适合把"只读审查""写测试""改文档"这类职责拆开，避免一个智能体既改代码又给自己打分。在项目里建 .opencode/agent/reviewer.md：
```markdown
---
description: 只读代码审查，输出问题清单，不修改任何文件
mode: subagent
temperature: 0.1
tools:
write: false
edit: false
bash: false
---
你是资深代码审查员。收到代码变更后，按以下顺序输出：
1. 逻辑错误与边界条件
2. 安全问题（注入、越权、密钥硬编码）
3. 性能问题（N+1 查询、无索引扫描）
4. 可读性建议
只输出问题清单，每条给出文件名和行号，不要贴大段代码。
```
tools 里把写、编辑、执行全部关掉，这个子智能体就只能看，不会误改。全局子智能体放在 ~/.config/opencode/agent/ 下，项目级的放在 .opencode/agent/ 下，同名时项目级覆盖全局。
第 7 步：在真实仓库里跑一次改动
先看只读能力：
```bash
opencode run "说明 src/api 目录的请求链路，列出三个可能的错误处理缺口"
```
确认无误后再让它改代码：
```bash
opencode run "给 src/utils/parseDate.ts 补单元测试，覆盖空字符串和非法格式两种情况，然后跑 pnpm test"
```
跑完检查边界：
```bash
git status
git diff
```
实测下来的边界大致是这样：单文件重构、补测试、补类型、改配置、按现有模式新增一个路由，这类任务通常一次就能跑通；跨多个服务的接口改动、需要访问数据库或线上凭据的操作、大规模重命名，建议拆成小步并人工逐步确认。大仓库里它可能只读到部分文件，改动前用 git diff 复核仍然必要。
验证部署是否成功
逐条执行，对照预期：
```bash
opencode --version
```
预期：打印版本号，无报错。
```bash
opencode models
```
预期：列表里能看到已登录提供方的模型，以及自定义 provider 下的模型 ID。
```bash
opencode run "当前仓库根目录下 package.json 的 name 字段是什么？只回答字段值"
```
预期：直接输出字段值，不带多余解释。这条命令同时验证了鉴权、模型连通性和文件读取三件事。
```bash
git status --short
```
预期：如果没有让它改动文件，这里应为空。若不为空，说明有意外写入，先看 diff 再决定是否保留。
常见报错与解决
报错信息：command not found: opencode
原因：安装目录没有加入 PATH，或安装到了当前 shell 未加载的位置。
解决：
```bash
ls ~/.opencode/bin ~/.local/bin 2>/dev/null
echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
报错信息：401 Unauthorized 或 invalid api key
原因：密钥错误、已过期，或自定义 provider 没有读取到环境变量。
解决：
```bash
opencode auth list
echo $INTERNAL_API_KEY
export INTERNAL_API_KEY="新的密钥"
opencode auth login
```
如果是 {env:...} 引用失效，确认环境变量是在启动 opencode 的同一个 shell 里导出的。
报错信息：404 Not Found 或 model not found
原因：baseURL 少了 /v1 后缀，或者 models 下的键名与网关实际模型名不一致。
解决：直接探测端点确认可用模型名：
```bash
curl -s https://your-gateway.example.com/v1/models \
-H "Authorization: Bearer $INTERNAL_API_KEY" | head -40
```
把返回的 id 原样填进 opencode.json 的 models 键名。
报错信息：fetch failed / ETIMEDOUT
原因：公司网络需要走代理，或证书链不被信任。
解决：
```bash
export HTTPS_PROXY="http://proxy.example.com:8080"
export HTTP_PROXY="$HTTPS_PROXY"
export NODE_EXTRA_CA_CERTS="/path/to/corp-ca.pem"
```
报错信息：TUI 启动后花屏、按键错乱
原因：终端类型或 locale 不被支持。
解决：
```bash
export TERM=xterm-256color
export LANG=en_US.UTF-8
```
换用 iTerm2、Windows Terminal、Ghostty 等现代终端通常也能解决。
后续维护
备份配置。 需要备份的是 ~/.config/opencode/（全局配置与全局智能体）、~/.local/share/opencode/（凭据，注意加密保存或干脆不入备份）、以及各仓库里的 opencode.json、AGENTS.md 和 .opencode/ 目录。项目级文件直接进 Git 就好。
升级。 用 npm 安装的跟着包管理器升级，用安装脚本的重新执行一次脚本即可；升级前先记录当前版本，出问题可以回退。版本发布节奏以官方文档与仓库 release 页为准。升级后重跑一遍上面的验证命令。
日志。 界面异常时把日志级别调高并直接打到终端：
```bash
opencode --log-level DEBUG --print-logs
```
日志文件通常落在 ~/.local/share/opencode/log/ 下，具体路径以实际输出为准。日志里会包含请求元信息，分享前记得检查是否带上了密钥或内部 URL。
成本与配额。 长会话会不断累积上下文，TUI 里用 /compact 压缩历史，或直接开新会话；把 AGENTS.md 写清楚能显著减少来回追问的次数。
权限收口。 跑顺之后不要急着把 bash 全设成 allow，保留 rm -rf*、curl*、git push* 这类规则的 deny 或 ask。智能体改完代码后，人工过一遍 git diff 再提交，这条习惯比任何配置都管用。
规则文件迭代。 每次发现智能体犯了重复的错，就把对应的约束补进 AGENTS.md。这份文件是长期资产，写得越具体，后续每次任务的返工就越少。