OpenCode 使用教程

一、OpenCode 是什么

OpenCode 是由 SST 团队（现名 Anomaly）开发的开源 AI 编码 Agent。它运行在你的终端里，能读取和编辑仓库文件、执行 shell 命令、跑测试并迭代，直到任务完成。

1.1 核心特性

1.2 与 Claude Code / Cursor 的对比

选它的核心理由：不想被单一厂商绑定、想在远程服务器/SSH 环境里用、想自己控制成本与模型。

1.3 适用与不适用

1.4 一个重要背景（2026 年初）

Anthropic 曾通过服务端检查，阻止第三方工具（含 OpenCode）以 OAuth 方式使用 Claude Pro/Max 订阅额度。因此当前推荐路径是：

1. 自带 API Key（直接向厂商付费，按 token 计费）
2. GitHub Copilot 登录（用现有 Copilot 订阅驱动，最省事）
3. ChatGPT Plus/Pro 登录
4. 官方精选的 OpenCode Zen 模型列表

二、安装

2.1 各平台安装方式

macOS / Linux（推荐脚本）

curl -fsSL https://opencode.ai/install | bash# 官网首页给出的 v2 安装脚本（新版）curl -fsSL https://opencode.ai/v2/install | bash

npm / Bun / pnpm / Yarn（跨平台）

npm install -g opencode-ai

Homebrew（macOS / Linux）

brew install anomalyco/tap/opencode

推荐用 Anomaly 的 tap，比 Homebrew 官方 formula 更新更及时。

Windows

# 方式一：Scoop（推荐，最简单）scoop install opencode# 没装 Scoop？先在 PowerShell 执行：irm get.scoop.sh | iex# 方式二：Chocolateychoco install opencode# 方式三：npmnpm install -g opencode-ai

Windows 建议：官方推荐优先使用 WSL，性能和功能兼容性更好。若用 Git Bash，npm 方式也可正常工作。

Arch Linux

sudo pacman -S opencode      # 稳定版paru -S opencode-bin         # AUR 最新版

Docker

docker run -it --rm ghcr.io/anomalyco/opencode

其它方式：mise use -g github:anomalyco/opencode，或从 GitHub Releases 下载二进制。

2.2 验证安装

opencode --version

2.3 升级

# 脚本安装的curl -fsSL https://opencode.ai/install | bash# npm 安装的npm i -g opencode-ai@latest# Homebrewbrew upgrade anomalyco/tap/opencode

三、模型配置

OpenCode 本身免费，费用来自你选用的模型提供商。

3.1 方式 A：OpenCode Zen（官方精选）

适合刚开始、不想纠结选哪家模型的场景。

1. 在 TUI 里运行 /connect
2. 选择 opencode
3. 浏览器打开 https://opencode.ai/auth ，登录、绑定支付方式、复制 API Key
4. 把 Key 粘贴回终端

# 命令行方式opencode auth login

3.2 方式 B：GitHub Copilot（零额外成本，推荐）

已有 Copilot 订阅的话最省事，不用再单独买 API Key。

opencode auth login --provider github

用 GitHub 登录即可用 Copilot 订阅驱动。

3.3 方式 C：ChatGPT Plus / Pro

官网明确支持用 OpenAI 账号登录，复用 ChatGPT 订阅。

3.4 方式 D：自带 API Key（最灵活）

通过环境变量注入：

export ANTHROPIC_API_KEY="sk-ant-xxx"export OPENAI_API_KEY="sk-xxx"export GEMINI_API_KEY="xxx"export GROQ_API_KEY="xxx"

Windows（PowerShell 临时生效）：

$env:ANTHROPIC_API_KEY="sk-ant-xxx"

持久化写入系统环境变量（Windows）：

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-xxx", "User")

3.5 选择与切换模型

• TUI 内：/models 查看可用模型，/model 切换
• CLI：opencode models --refresh 刷新模型列表（含 provider/model 格式）
• 启动时指定：opencode --model provider/model

模型 ID 一律是 provider/model 格式（如 anthropic/claude-...、openai/gpt-...）。

3.6 模型选择建议

小模型容易在「函数参数」上产生幻觉，若用本地模型，建议 70B 级别以上。

四、TUI 基础操作

4.1 启动

cd /path/to/your-projectopencode

4.2 界面上的关键操作

4.3 常用斜杠命令速查

不同版本命令集合可能有差异，用 / 唤起列表即可看到当前版本支持的全部命令。

五、三种 Agent 模式

TUI 内按 Tab 在 plan / build 之间切换。

推荐工作流：先 Plan 再 Build

1. Tab 切到 plan 模式2. 描述需求，让 Agent 给出实现方案与涉及文件3. 对方案提反馈（补充细节、贴参考图）4. Tab 切回 build 模式5. 让它动手改6. 审查 diff，跑测试

这样做的好处：大改动前先对齐方案，避免 Agent 一次性乱改多个文件。

六、核心工作流

6.1 第一步：初始化项目（/init）

opencode> /init

它会让 Agent 分析项目结构，在仓库根目录生成 AGENTS.md。

强烈建议把 AGENTS.md 提交到 Git —— 它是 Agent 理解项目结构与编码规范的依据，团队共享后每个人的会话都能受益。

6.2 给上下文：问问题

@packages/functions/src/api/index.ts 里的鉴权是怎么处理的？

用 @ 精准引用文件，比把整个仓库贴进提示词有效得多。

6.3 描述需求：像对一个新人说话

好的提示词示例：

/build当用户删除一条笔记时，在数据库里标记为已删除（不要物理删除）。然后新增一个页面展示所有最近删除的笔记，从这个页面可以恢复或彻底删除。

要诀：

• 给足上下文和示例，把它当团队里的新人开发者
• 说清楚要保持不变的行为（重构场景）或复现步骤（bug 场景）
• 一次一个任务，控制在「能逐文件审查 diff」的规模内

6.4 让它自己验证

找出搜索功能的实现和现有测试，复现空查询的行为，只改这一处行为，保持非空查询不变，并运行相关检查。把结果 diff 和剩余不确定的地方展示出来。

要求它展示实际执行结果——没跑过的测试、被跳过的构建，都不算通过。

七、会话管理

7.1 多会话并行

同一项目可开多个终端，各自独立会话，互不干扰：

# 终端 1：修 bugopencode --session bugfix# 终端 2：写新功能opencode --session feature# 终端 3：补测试opencode --session tests

7.2 继续上一个会话

opencode --continue           # 继续最近的会话opencode -c                   # 同上（简写）opencode --session <id>       # 继续指定会话opencode --continue --fork    # 从上一个会话分叉

7.3 分享会话

opencode --share              # 生成分享链接

TUI 内用 /share 同样可以。

7.4 撤销改动

/undo 基于 Git 快照，可回滚 Agent 造成的改动。

八、无头模式与自动化

不启动完整 TUI，直接执行一次性提示词——适合脚本、CI、自动化：

opencode run "解释这个项目的架构"opencode run --file src/app.js "给这个文件补单元测试"opencode run --format json "列出所有 TODO 注释"

8.1 避免 MCP 冷启动

MCP 服务器启动有开销，可先起一个无头服务，让后续命令附着上去：

# 终端 1：启动服务opencode serve# 终端 2：附着执行opencode run --attach http://localhost:4096 "解释 JavaScript 里的 async/await"

8.2 CLI 参数速查

九、配置与权限

9.1 配置文件

项目根目录或全局目录下的 opencode.json（也支持 opencode.jsonc）：

{  "$schema": "https://opencode.ai/config.json",  "permission": {    "bash": "ask"  }}

9.2 权限配置（重要）

在新接触的代码库里，建议先把 shell 命令设为「每次询问」：

{  "$schema": "https://opencode.ai/config.json",  "permission": {    "bash": "ask",    "edit": "ask"  }}

等确认它的行为符合预期后，再放宽为自动允许。

⚠️ 注意：这个设置只约束 shell 工具，不等于完整的沙箱。真实的隔离要靠容器 / 虚拟机 / 独立开发机。

9.3 AGENTS.md 编写要点

AGENTS.md 是给 Agent 的项目指令，/init 会生成初始版本，之后应人工维护：

## 项目指令- 使用仓库现有的构建与测试命令- 修改共享接口前，先查看附近的调用方- 本次改动仅限报告中的行为，不扩大范围- 不新增依赖，除非说明必要性- 未能执行的检查要如实报告

要点：

• 写你核实过的事实（真实的测试命令、目录含义、不能改的文件）
• 不要凭猜测写「本项目使用了 XX 框架」
• 指令是引导，不能保证每次输出都遵守 —— 仍需人工审查

十、MCP 与扩展

10.1 接入 MCP 服务器

MCP（Model Context Protocol）让 Agent 能访问外部工具与数据源（数据库、API、浏览器等）：

opencode mcp add      # 添加 MCP 服务器opencode mcp list     # 查看已配置的 MCP 及状态

10.2 自定义 Agent

针对重复性任务，可创建带专属系统提示词与工具集的 Agent：

opencode agent create   # 创建自定义 agentopencode agent list     # 列出所有可用 agent

使用时通过 --agent 指定。

10.3 GitHub 集成

opencode github install

以上命令的具体参数请以 opencode <command> --help 和官方文档为准（命令集随版本演进）。

十一、实战案例

以改造一个 Node/Koa 项目为例，完整走一遍：

11.1 准备

cd /path/to/koa-projectopencode

11.2 第一步：初始化

> /init

生成 AGENTS.md，人工检查并补充真实的测试命令后提交 Git。

11.3 第二步：Plan 模式摸清现状

按 Tab 切到 plan 模式：

@routes/commits.js 和 lib/git.js 里，提交记录接口是怎么处理 git 输出的？如果 git 输出里含非法 UTF-8 字节，会发生什么？

Agent 只读分析，给出结论与风险点，不改任何文件。

11.4 第三步：让它出方案

给出修复方案：要求所有对外输出的 git 文本都经过编码净化，二进制接口（文件预览）不受影响。列出需要改的文件和改动要点。

11.5 第四步：切到 Build 模式落地

按 Tab 切回 build 模式：

按上面的方案实现，改完后展示 diff。

11.6 第五步：验证

用 node --check 检查改动文件的语法，并说明如何验证修复有效。

11.7 第六步：提交

审查 diff → 确认无夹带改动 → 自行 commit。

核心原则：Plan 定方案，Build 落地，每一步都自己审查 diff。不要因为用了 Agent 就跳过 review。

十二、常见问题与成本控制

12.1 安装与认证

12.2 使用体验

12.3 成本控制

OpenCode 客户端免费，费用来自模型调用：

1. 先小任务试水：用一个小型、可评测的任务确认模型可用，再上大任务。
2. 选对档位：简单改动用轻量模型，复杂重构才用高能力模型。
3. 监控首周用量：一次大型重构可能消耗数美元，第一周盯一下厂商后台账单。
4. 善用订阅：有 GitHub Copilot 订阅，优先走 Copilot 登录，省 API 费用。
5. 本地模型：数据敏感场景用 Ollama，代价是需要 70B 级别以上模型才有可靠的工具调用能力。

12.4 安全提醒

• 不要把不允许上传给模型厂商的仓库代码交给云端模型（改用本地模型）。
• 新项目先用 permission: ask，确认行为后再放宽。
• 权限配置不是沙箱，需要强隔离请用容器 / 独立开发机。
• Agent 的改动必须人工审查后再提交，尤其是安全相关代码。

十三、9Router 项目教程

一个自托管的 AI 网关：把 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenCode 这些工具的请求统一收口到 http://localhost:20128/v1，再按「订阅额度 → 便宜模型 → 免费模型」三层自动降级。

仓库：https://github.com/decolua/9router ，npm 包名 9router，MIT 许可。当前版本 0.5.104 左右。

13.1 它解决什么问题

日常用 AI 编码，痛点基本就这几个：订阅额度每月清零用不完、跑一半被限流、每个工具各配一套 Key、工具输出（git diff、grep、ls）疯狂烧 token。

9Router 的做法是在你和厂商之间插一层代理：

OpenCode / Claude Code / Cursor / Cline                ↓  统一走一个 OpenAI 兼容端点           9Router (localhost:20128)                ↓  按额度、成本、可用性路由Tier 1 订阅：Claude Code → Codex → GeminiTier 2 便宜：GLM → MiniMax → KimiTier 3 免费：Kiro → OpenCode Free → iFlow / Qwen

它的四个核心能力：

和同类项目的差别（个人理解）：LiteLLM 更像「给后端用的 Python 代理 + YAML 配置」，One API / New API 偏多租户分发与计费，9Router 的重心是榨干你已有的订阅额度、并且在断供时无感兜底。

13.2 安装

三种方式，挑一种：

# 方式一：全局装（桌面/本机推荐）npm install -g 9router# 方式二：不装，直接跑npx 9router# 方式三：Docker（服务器/VPS 推荐）docker run -d --name 9router -p 20128:20128 \  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data \  decolua/9router:latest

镜像同时发在 Docker Hub 和 GHCR，amd64 / arm64 都有。

启动参数：

9router                    # 默认启动，自动打开浏览器9router --port 8080        # 换端口（20128 被占用时用）9router --no-browser       # 服务器上跑，不弹浏览器9router --skip-update      # 跳过自动更新检查

13.3 首次启动

启动后 Dashboard 在：

http://localhost:20128/dashboard

进入 Providers 页面接第一个 provider。想零成本先跑通，直接接这两个（不需要注册付费账号）：

• Kiro AI —— 免费 Claude
• OpenCode Free —— 免认证

接完回到 Dashboard 复制 API Key，就可以给工具用了。

13.4 接到 OpenCode 里

最省事的方式是让 9Router 自己改配置：

# 本机 9router，把 opencode 指过去npx 9router connect http://localhost:20128 --tools opencode# 或者服务器上跑 9router，本机只做客户端npx 9router connect http://<server-host>:20128 --tools opencode

它会用 Dashboard 密码登录，复用或新建一个名为 cli-<hostname> 的 API Key，然后把配置写进 OpenCode 的配置文件；原配置只备份一次，后缀 .bak-9router。

支持的 --tools 值：claude、codex、opencode、droid、crush、kilo、cline、pi、omp、all。

手动配置也行，本质就是三个值：

Endpoint / base_url : http://localhost:20128/v1API Key             : Dashboard 里复制的那个Model               : cc/claude-opus-4-5-20251101   ← 前缀代表来源 provider

查这台 9Router 到底提供哪些模型 ID：

curl http://localhost:20128/v1/models -H "Authorization: Bearer <your-key>"

模型 ID 不是硬编码的，来自服务端 Dashboard 上已接通的 provider，所以别背前缀，直接查 /v1/models。--print-env 也能顺手把 OPENAI_BASE_URL / OPENAI_API_KEY 打出来，给其他认环境变量的 CLI 用。

13.5 常用运维命令

# 看本机各工具当前指向哪个网关、用的什么模型（只读本地文件，不联网）npx 9router shownpx 9router show opencode --json# 撤销，把工具配置还原npx 9router connect --reset --tools opencode# 保存密码，下次不再输（明文存 ~/.9router/connect.env，权限 600）npx 9router connect http://<server-host>:20128 --tools opencode --save

show 对 Codex、OpenCode、Cline 还会额外提醒：配置里存在 9router 条目，但当前激活的是别的 provider —— 这类「配了却没生效」的问题一眼就能看出来。

13.6 数据和坑

数据位置：

几个容易踩的点：

1. Docker 忘了挂卷 —— 容器重启后 provider、Key、额度记录全丢。-v "$HOME/.9router:/app/data" 必须写。
2. 明文 HTTP 会裸奔 —— 9router connect 在 http:// 下会明文发送 Dashboard 密码和 API Key。跨机器用请走可信内网 / VPN，或者前面套一层 HTTPS 反代。
3. 端口冲突 —— 20128 被占时用 --port 换一个，记得客户端 base_url 同步改。
4. 只改了一半 —— 客户端显示"已配置"但请求没走 9Router，用 9router show 核对 base_url 和模型前缀。

13.7 和 OpenCode 的配合方式

两者不是替代关系，是「客户端 + 网关」：

• OpenCode 负责干活：读代码、改文件、跑命令
• 9Router 负责供模型：决定这次请求该打给订阅、便宜模型还是免费模型

一个典型组合：OpenCode 日常用 cc/ 前缀的 Claude 系模型，额度见底时 9Router 自动切到便宜档，你再也不用中途停下来手动换 Key。

而且 9Router 的 connect 支持 opencode，等于一条命令就能把 OpenCode 接到网关上；不想用了 --reset 还原，配置文件有备份，进退都干净。

附：一页速查

# 安装curl -fsSL https://opencode.ai/install | bashcurl -fsSL https://opencode.ai/v2/install | bash   # v2npm install -g opencode-aibrew install anomalyco/tap/opencode                 # macOS/Linuxscoop install opencode                              # Windows# 认证opencode auth loginopencode auth login --provider github               # 用 Copilot 订阅# 常用opencode                                            # 启动 TUIopencode run "..."                                  # 一次性执行opencode serve                                      # 无头服务# TUI 内/init          生成 AGENTS.md/connect       连接模型提供商/models        查看模型/model         切换模型/share         分享会话/undo          撤销Tab            切换 Plan / Build 模式@              引用项目文件

完