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

【这是码歌的第 61 篇原创】

大家好，我是程序员码歌。用 OpenCode 已经有一段时间了，这篇文章给大家详细分享下安装、配模型，以及两个真实应用场景——内网知识库问答、PR Review代码。

这篇主要讲什么

• OpenCode 是啥，和 Cursor 有啥不同

• 怎么装、怎么确认装对

• 用 GitHub Copilot 订阅和便宜 API 怎么接 OpenCode

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

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

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

一、OpenCode 是什么

OpenCode 是开源 AI 编程 Agent，装本机跑，不绑单一模型。默认进终端 TUI，也能 opencode run 单条执行、opencode serve 给别人连。

和 Cursor 不冲突：它偏终端、可换模型、能脚本化。我常用两件事：Tab 切 plan/build（plan 只读，build 改代码），对话里 @文件 带上下文。

二、模型怎么选

模型 ID 写成 provider/model，如 deepseek/deepseek-chat。TUI 里 /connect 配 Key、/models 切换；默认写进 opencode.json。

软件免费，模型走你已买的订阅或 API。我主力是 GitHub Copilot。

GitHub Copilot： 公司有 Copilot 订阅就能在 OpenCode 里用，不用另买一份 Claude API。TUI 里 /connect 搜 GitHub Copilot，浏览器打开 github.com/login/device 输入设备码，登完 /models 选 Copilot 里的模型（部分型号要 Pro+ 套餐，见 Copilot 计划）。

cd your-repo
opencode
/connect    # 选 GitHub Copilot，按提示完成设备码登录
/models     # 选例如 Claude / GPT 等 Copilot 提供的模型

凭证落在 ~/.local/share/opencode/auth.json，别提交 Git。默认模型可在 opencode.json 里写，具体 ID 以 /models 列表为准。

便宜 API（可选）： PR Review 的 Actions 里我有时用 DeepSeek（按量低），和本机 Copilot 分开。Groq、OpenRouter 也能 /connect 接上。

我平时的组合：

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

实例一只 @ 相关 md；实例二才装 GitHub workflow，别混仓。

三、安装

先安装旧版的请先卸载。五条路选一条即可，装完验证方式相同。

路	命令
macOS / Linux 脚本	`curl -fsSL https://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 <copilot模型ID> "..."（模型 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 错环境。

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

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

我们想把需求文档、API 规范、发布流程这类文档交给 AI 查。

做法是把文档落成 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. 终端会给设备码，浏览器打开 https://github.com/login/device 登录授权

3. /models 选 Copilot 里顺手的模型（我写文档问答常用偏强的那个）

4. Tab 切 plan，避免 Agent 改仓库文件

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

6.3 怎么问才靠谱

好的问法会把范围说死，并 @ 具体文件：

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

尽量别这样问：

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

• 一上来 @ 整个 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 加 Key，例如 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 里会自动跑一遍，评论出现在 PR 对话里。

7.3 PR 里点名某一行改

在 GitHub Files changed 某行下评论：

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

OpenCode 会带上文件路径、行号、diff 上下文，比你在总评里泛泛说「注意 SQL」准。如果希望它直接推 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 ，内网部署或者想对接业务系统，就值得装。它比直接调用模型api 的区别是，它有编排上下文，能直接指定工作目录，有一套不亚于cursor 、codex的完整agent 机制。

和 OpenSpec、Superpowers 也能配合：前者定任务，后者管流程，OpenCode 负责跑。

如果喜欢这篇文章，请帮忙点赞、转发给需要的朋友。
我是码歌，专注分享 AI 工具与 AI 编程实战，为开发者和 AI 爱好者提供帮助，让你每次阅读都有收获。