我是怎么部署开源 AI 编程助手 OpenCode，并在两个真实场景使用起来的

用了 OpenCode 一段时间，今天系统梳理一下它的安装、模型配置，以及两个实际落地的场景——内网知识库问答和 PR Review。整个过程下来最直观的感受是：这工具跟 Cursor 不冲突，但玩法确实不一样。

这篇主要讲什么

• OpenCode 是什么、和 Cursor 有什么区别

• 怎么安装、怎么确认装对了

• 如何用 GitHub Copilot 订阅和便宜 API 接入 OpenCode

• 两个场景各起一个 OpenCode 实例

• 场景一：文档仓实例，内网 Markdown + Copilot 问答

• 场景二：代码仓实例，PR 自动 Review

一、OpenCode 是什么

简单说，OpenCode 是一个开源的 AI 编程 Agent，装在本机跑，不绑定某一款模型。默认进入终端 TUI（Terminal User Interface），也能通过 opencode run 单条执行命令，或者用 opencode serve 让其他人连接。

它与 Cursor 并不冲突——OpenCode 更偏向终端环境，支持自由更换模型，并且可以脚本化。实际操作中，Tab 用来切换 plan 和 build 模式：Plan模式只读，适合审查；Build模式写磁盘，适合执行修改。对话时还可以通过 @文件 来携带特定上下文。

二、模型怎么选

模型 ID 的格式是 provider/model，例如 deepseek/deepseek-chat。在 TUI 里，通过 /connect 配置 API Key，通过 /models 切换模型；配置默认会写入 opencode.json 文件。

软件本身免费，模型走的是你已有的订阅或购买的 API。

：公司有 Copilot 订阅，就可以直接在 OpenCode 中使用，无需额外购买 Claude API。TUI 里通过 /connect 选择 GitHub Copilot，浏览器会提示在 github.com/login/device 输入设备码完成登录。之后通过 /models 命令即可切换 Copilot 提供的模型——注意部分模型可能需要 Pro+ 套餐。

凭证保存在 ~/.local/share/opencode/auth.json，切记不要提交到 Git。可以在 opencode.json 里设置默认模型，但具体可用 ID 仍以 /models 列表为准。

：在 PR Review 的 Actions 场景中，有时会使用 DeepSeek（按量付费），与本机 Copilot 区分开。Groq、OpenRouter 这类平台同样可以通过 /connect 接入。

平时的组合是这样的：

场景	模式	模型
实例一：问文档	plan	GitHub Copilot
实例二：本地看 PR	plan	GitHub Copilot
实例二：PR 自动评论	Actions	DeepSeek（或 Copilot）

关键点：实例一只 @ 相关的 Markdown 文件；实例二才配置 GitHub workflow，仓库别混着用。

三、安装

如果之前装过旧版，请先卸载。以下五条安装路径选一条即可，装完后验证方式完全一致。

安装方式	命令
macOS / Linux 脚本	curl -fsSL opencode.ai/install | bash
Homebrew	brew install anomalyco/tap/opencode
npm	npm i -g opencode-ai@latest
Windows	scoop install opencode 或 choco install opencode；也可通过 WSL 走脚本安装
桌面版	opencode.ai/download 或 brew install --cask opencode-desktop

：执行 opencode --version 看版本号 → 运行 opencode 进入 TUI → 执行 /connect → 执行 /models 确认有模型列表 → 在 plan 模式随便问一句，跑通就算完成。

四、日常怎么用

进入仓库后，执行 cd your-repo && opencode 即可开始。

操作	具体做法
带文件	@文件名
连模型	/connect、/models
只读	Tab → plan
改代码	Tab → build
团队规范	/init → AGENTS.md

：使用 opencode run -m "..."（模型 ID 从 /models 里查看）。如果想多人共用，可以 opencode serve 启动服务，其他人通过 opencode attach http://IP:4096 连接——注意，每个人仍需用自己的 Copilot 登录。

五、两个应用场景，各起一个 OpenCode 实例

这两套场景没有用同一个 OpenCode 会话或同一个仓库，而是拆成两套独立的实例：各对应一个 Git 仓库、一份 AGENTS.md、一套用法。混在一起会导致上下文串味——文档问答的 prompt 和 PR Review 的规则互相打架，权限也不好控制（文档实例只读即可，代码实例可能需要写权限）。

	实例一：文档问答	实例二：PR Review
仓库	单独的内网文档仓，如 company-docs	业务代码仓，如 app-backend
进入方式	cd company-docs && opencode	cd app-backend && opencode，或通过 GitHub Actions
默认模式	长期 plan	本地看 PR 用 plan；CI 里自动 Review
AGENTS.md	只答文档、禁止访问外网、必须引用出处	安全、测试、代码规范
长期服务	可选 opencode serve --port 4096 挂载文档仓	一般不开 serve，走 workflow + /oc 评论
模型	本机 Copilot	本机 Copilot；Actions 可用 DeepSeek

实例一只放 Markdown 文档，不要当成业务代码仓使用。实例二才执行 opencode github install、才放 opencode-review.yml。如果在两台机器上各跑一个 serve，端口要分开，比如文档用 4096，代码用 4097，避免同事 attach 错环境。

下面分别说这两个实例怎么落地。

六、场景一：内网知识库问答（实例一）

目标是让 AI 能够方便地查询需求文档、API 规范、发布流程这类内部资料。

做法是把这些文档整理成 Markdown 格式，存放在内网 Git 仓库，OpenCode 接入 GitHub Copilot，通过 @ 只带相关 MD 文件，使用 plan 模式（只读，不改代码）。文档放在内网仓，提问时通过 @ 控制范围；模型侧走 Copilot，前提是公司允许使用 Copilot 并且你有有效订阅。

6.1 文档怎么准备

• 从飞书、Confluence 等平台导出或同步为 .md 文件，按主题分目录存放，例如：

• docs/运维/发布.md

• docs/API/鉴权.md

• 一篇文档只讲一件事，标题清晰——比一个大 PDF 好用得多。

• 可以单独建文档仓库，也可以挂在业务仓库的 docs/ 目录下，但必须保证内网能 clone 下来。

6.2 在文档仓里接上 Copilot

在文档仓（实例一），找一台能访问 GitHub 的开发机操作：

cd /path/to/docs-repo
opencode

进入 TUI：

1.执行 /connect → 选择 GitHub Copilot

2.终端会显示设备码，用浏览器打开 github.com/login/device 并输入设备码完成授权

3.执行 /models 选择 Copilot 里顺手的大模型（文档问答场景建议用能力偏强的）

4.按 Tab 切换到 plan 模式，避免 Agent 意外修改仓库文件

第一次完成后，以后进仓库会自动带上 Copilot。如果需要固定默认模型，把 /models 里看到的模型 ID 写进 opencode.json 的 model 字段即可。

6.3 怎么问才靠谱

好的提问方式会把范围说清楚，并用 @ 指定具体文件：

根据 @docs/运维/发布.md，生产环境回滚要几步？只根据文档回答；文档没写就说没有，不要编。

尽量避免这样问：

• 「帮我看看需求文档」——范围太大，AI 容易瞎编内容。

• 一上来 @ 整个 docs/ 目录——上下文窗口会爆掉，回答质量也会下降。

如果文档特别多、单文件很长，可以用 opencode mcp add 接入公司自己的检索 MCP 服务，先搜索再 @ 命中段落；文档量不大时，直接 @ 两三个相关 MD 文件就够用了。

6.4 用 AGENTS.md 卡住边界

在仓库里执行 /init，或者手动写一个 AGENTS.md，至少包含以下两条：

• 禁止使用 webfetch 访问外网。

• 回答时必须注明依据哪份文档、哪一节；找不到就明确说「文档未记载」。

这比每次口头提醒要稳定得多。

6.5 多人怎么用

文档仓库大家各自 clone 到本地，在各自的实例一里通过 opencode + /connect 连接自己的 Copilot 即可。

如果需要固定一台「文档问答专用机」，让它只跑实例一：

cd /path/to/company-docs
opencode serve --hostname 0.0.0.0 --port 4096

设置环境变量 OPENCODE_SERVER_PASSWORD。其他人通过 opencode attach http://10.x.x.x:4096 连接时，工作目录仍然是文档仓。注意不要和实例二共用 4096 端口。

七、场景二：Git PR 自动 Review（实例二）

在业务代码仓单独起实例二。当 PR 提上来后，让 AI 先扫一遍：明显安全问题、遗漏的测试、和代码规范不一致的地方，先留评论，人再重点审查。OpenCode 官方提供了 GitHub 集成，既可以自动跑在 Actions 里，也可以在 PR 评论里手动触发它。

常见三种用法：

方式	什么时候用
PR 打开/更新自动跑	团队默认流程，每个 PR 都有初评
评论里写 /oc	某一段 diff 想单独修改或检查
本地 opencode pr	合并前自己先跑一遍

7.1 在代码仓里第一次接入

在业务代码仓根目录（实例二，不要和文档仓混用）：

opencode github install

按照向导做完几件事：

1.安装 OpenCode GitHub App 到目标仓库（或整个组织）。

2.生成 .github/workflows/opencode.yml（或专门的 review workflow）。

3.提示去仓库 Settings → Secrets → Actions 中添加环境变量，例如 DEEPSEEK_API_KEY。

DeepSeek 按量付费比较便宜，PR Review 默认用它；如果公司有 Azure/Bedrock，就把 model 和 env 换成对应的配置。

7.2 PR 自动 Review 的 workflow

单独放一个 opencode-review.yml，只在 PR 事件触发时运行：

name: opencode-review
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
steps:
- uses: actions/checkout@v6
with:
persist-credentials: false
- uses: anomalyco/opencode/github@latest
env:
DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
model: deepseek/deepseek-chat
use_github_token: true
prompt: |
按仓库 AGENTS.md 的规范 Review 这个 PR：
- 安全：注入、权限、密钥是否泄露
- 错误处理和边界条件
- 测试是否覆盖主要变更
只评论你确定的问题，不要凑字数，不要建议风格小事。

当 pull_request 触发且不写 prompt 时，OpenCode 也会做默认的 Review；这里加上 prompt 是为了对齐仓库里的 AGENTS.md 规范。

合并进 main 分支后，下次任何人开 PR 或 push 新 commit，Actions 里就会自动跑一遍 Review，评论会出现在 PR 对话中。

7.3 PR 里点名某一行修改

在 GitHub 的 Files changed 页面，某一行下面写评论：

/oc 这里改成参数化查询，别拼 SQL

OpenCode 会带上文件路径、行号、diff 上下文，这比在总评里泛泛说「注意 SQL」要精确得多。如果希望它能直接 push commit 到同一个 PR，workflow 里需要设置 contents: write 权限——但初评阶段建议只用只读权限，改代码仍由人工合并。

7.4 合并前本地先看

在代码仓开 PR 前，用实例二在本地扫一遍 diff：

cd /path/to/app-backend
opencode pr 42

这条命令会 checkout 到 PR 的分支。在同一仓库里再执行 opencode，切换到 plan 模式，例如：

对比当前分支和 main 的 diff，列出 3 个最值得人看的风险点。

这比在网页里逐行翻 patch 要快得多，尤其适合大 PR。

7.5 踩过的点

• Secrets 千万别写进仓库，只放 GitHub Actions Secrets。

• permissions 给够：只做 Review 用 contents: read；需要自动改 PR 再开 write。

• 公共仓库要注意 OpenCode 的 share 默认行为，敏感项目建议关掉或者只用私有仓库。

• 评论太多会吵到人，prompt 里写「只评确定的」，能屏蔽不少废话。

八、一句总结

只要有真实的 CLI 需求、想在内网部署、或者想对接自己的业务系统，OpenCode 就值得装。它和直接调用模型 API 最大的区别在于：它能编排上下文，能指定工作目录，拥有不亚于 Cursor、Codex 的完整 Agent 机制。

另外，它和 OpenSpec、Superpowers 也能配合：OpenSpec 定任务，Superpowers 管流程，OpenCode 负责跑——三者分工非常清晰。