OpenCode 命令行 AI 编程代理使用指南

• 自动帮你：安装 GitHub App、生成 workflow、设置 secrets。

之后，你可以在 Issue / PR 评论里这样用：

• /opencode 帮我看一下这个问题，分析一下可能原因
• /opencode 在修复这个 bug 时，照着 /notes 的模式，同样在 settings 里加上鉴权
• /opencode 帮我写个单元测试覆盖这个边界情况

它在 GitHub Actions runner 中执行，可以：

• 自动创建分支
• 修改代码 / 提交 commit
• 打开 PR，把修改直接推给你

还支持：

• 定时任务：每周一早上自动扫描 TODO、生成总结、必要时开 issue 追踪。
• PR 自动 review：每次 PR 打开/更新时自动跑代码审查，给出改进建议。

这已经把'AI 当 teammate 一起干活'这件事做得非常工程化了，而不是单纯的 IDE 插件。

5. 客户端/服务器架构：远不止终端一个前端

OpenCode 采用了客户端/服务器架构：核心逻辑在 server 端运行，TUI 只是其中一个'前端'。

这意味着：

• 你可以在服务器或云端跑 OpenCode server；
• 从本地终端、手机、未来的 Web UI 等多种客户端驱动它干活；
• 对团队/远程开发场景特别友好。

三、OpenCode 的使用过程（从零到跑起来）

下面是一个典型使用流程的示意，帮助你在脑里先过一遍：

1. 前置准备（Prerequisites）

要在终端中使用 OpenCode，你需要准备两样东西：

• 一款现代终端模拟器，例如：
  • WezTerm（跨平台）
  • Alacritty（跨平台）
  • Ghostty（Linux / macOS）
  • Kitty（Linux / macOS）
• 你想用的 LLM 提供商的 API Key（如果一开始不熟悉，推荐先用官方的 OpenCode Zen）。

2. 安装（Install）

最简单的方式是用官方安装脚本：

curl -fsSL https://opencode.ai/install | bash

也可以用包管理器：

• Node.js 生态：
  • npm install -g opencode-ai
  • bun install -g opencode-ai
  • pnpm install -g opencode-ai
  • yarn global add opencode-ai
• Homebrew（macOS / Linux）：
  • brew install anomalyco/tap/opencode
  • 官方推荐用这个 tap，版本更新更及时。直接 brew install opencode 的 formula 由 Homebrew 团队维护，更新频率相对低一些。
• Arch Linux（Paru）：
  • paru -S opencode-bin
• Windows：
  • Chocolatey：choco install opencode
  • Scoop：scoop install opencode
  • NPM：npm install -g opencode-ai
• Mise：
  • mise use -g github:anomalyco/opencode
• Docker：
  • docker run -it --rm ghcr.io/anomalyco/opencode

Windows 上通过 Bun 安装的支持还在开发中。你也可以直接从 Releases 页面下载二进制使用。

3. 配置模型（Configure）

OpenCode 的特点之一，就是你可以配置任意 LLM 提供商的 API Key，灵活切换模型。

如果你之前没怎么折腾过 LLM 提供商，推荐先用 OpenCode Zen——这是官方经过测试和验证的精选模型列表，更省心。

配置步骤：

1. 在 TUI 中运行命令：/connect
2. 在 provider 列表中选择 opencode，它会让你去 opencode.ai/auth 完成登录和支付设置，然后复制 API Key；
3. 把 API Key 粘贴到终端里的输入框即可完成配置。

如果你想直接用别的 provider（例如 Anthropic / OpenAI / Google），也可以在 /connect 中选择对应选项，按提示填入相应的 Key。

4. 项目初始化（Initialize）

配置好提供商之后，就可以开始在一个项目里使用 OpenCode：

cd /path/to/project opencode

进入 TUI 后，先运行：

/init

这会让 OpenCode 分析你的项目，在项目根目录生成（或更新）一个 AGENTS.md 文件，用来记录项目结构和编码模式等上下文信息。

小建议：

• 把项目的 AGENTS.md 提交到 Git 仓库，这样团队其他成员也可以复用这份'项目记忆'，让后续会话更懂你的项目。

5. 使用示例（Usage）

初始化完成后，就可以让 OpenCode 帮你干活了。下面是一些典型用法。

5.1 问问题（Ask questions）

可以让它解释你不太熟悉的代码库：

• 示例：@packages/functions/src/api/index.ts 里的鉴权是怎么实现的？

小技巧：

• 在提问时用 @ 来触发项目文件的模糊搜索，帮它精准定位文件。

5.2 新增功能（Add features）

建议先让它'规划'而不是直接'开干'。

• 步骤 1：用 Tab 键切换到 Plan 模式（右下角会有模式指示）。
• 步骤 2：描述你的需求，比如：
  • '当用户删除一条笔记时，我们希望在数据库中标记为已删除，而不是真正删掉。然后再创建一个页面，展示所有最近删除的笔记。在这个页面上，用户可以选择恢复或彻底删除。'
• 步骤 3：多给一些上下文和细节，把它当成你团队里的一位初级开发者来沟通。

你还可以在讨论过程中直接把图片拖进终端，比如之前用过的设计稿，让它参照图片来设计页面。

5.3 实施功能（Build the feature）

等 Plan 方案聊得差不多了，再次按 Tab 切回 Build 模式，然后直接说一句：

• '看着不错，就按这个方案来吧。'

它就会开始真刀真枪地修改代码，帮你把这个功能做出来。

5.4 直接修改（Make changes）

对于比较明确的改动，也可以不先 Plan，直接让 Build 模式干活，例如：

• '我们需要给 /settings 路由加上鉴权。可以参考 /notes 路由在 @packages/functions/src/notes.ts 里的做法，把同样的逻辑应用到 @packages/functions/src/settings.ts。'

关键是给足上下文和示例，减少它瞎猜的概率。

5.5 撤销/重做（Undo / Redo）

如果发现它改的不是你要的东西，可以用：

/undo

它会把改动回滚，并恢复你最初的 prompt，你可以微调之后让它再试一次。也可以用 /redo 把刚刚撤销的改动再应用回来。/undo 可以执行多次，用来连续撤销多步操作。

5.6 分享会话（Share）

你和 OpenCode 的会话是可以分享给团队的：

• 运行 /share
• 它会生成一个链接并复制到你的剪贴板
• 注意：默认会话并不会公开，需要你主动通过 /share 才会生成可访问的链接。

5.7 个性化（Customize）

熟悉基本用法后，你还可以把 OpenCode 打造成自己称手的工具：

• 选择自己喜欢的主题
• 自定义快捷键
• 配置代码格式化工具
• 创建自定义命令
• 调整 OpenCode 的配置文件（config）

四、OpenCode 的优点（总结版）

• 完全开源：可自托管、可控、可审计。
• 供应商无关：自由切换不同 LLM，不怕被单一厂商绑定。
• 终端优先、TUI 体验好：主题化、快捷键、支持 LSP，对重度终端用户很友好。
• 项目级 Agent：通过 AGENTS.md 记忆项目结构和技术栈，逐步变成'懂你项目的 AI 同事'。
• Plan/Build 双模式：大改动前先规划，减少盲目修改带来的风险。
• GitHub/GitLab 深度集成：在 PR/issue 中通过命令触发自动修复/实现/分析，真正融入协同开发流。
• 客户端/服务器架构：核心逻辑与 UI 解耦，支持多客户端，远程开发友好。

五、OpenCode 的不足与权衡

1. 学习曲线：对不熟悉终端/命令行的人有门槛

• 如果你更习惯图形界面，第一次面对 TUI 需要一点时间适应（命令、模式切换、快捷键）。
• 不像 VS Code / TRAE 那样'所见即所得'，它更像是'命令行 + 聊天'的混合体验。

2. 生态和 UI 精致度上，暂时不如成熟 IDE

• 扩展生态：VS Code 的插件市场极其庞大，从调试、测试、语言支持到可视化工具应有尽有。OpenCode 虽然也有插件/SDK，但数量与成熟度目前还有明显差距。
• UI/体验：TRAE、Cursor 等 IDE 专门为'编码体验'打磨，集成了很多图形化细节和内置预览。OpenCode 的 TUI 已经很精致，但终究不是传统意义上的 GUI IDE。

3. 需要自己选模型、管配额和成本

• OpenCode 不像'订阅制 IDE'那样一口价，你要自己关心：
  • 用哪些模型更快更省钱；
  • Token 配额如何控制；
  • 团队多人协作时的成本分摊和监控。
• 对有 DevOps / 平台团队的团队问题不大，但对小团队或个人会增加一些心智负担。

4. Agent 的执行结果仍需要你'把关'

• 它可以执行命令、修改文件、跑测试，但'写对'并不保证'业务语义正确'；
• 你仍然需要：
  • 读懂它的改动；
  • 做 Code Review；
  • 必要时用 /undo 回滚。
• 从这个角度说，它更像一个'很勤快的初级工程师 + 工具人'，而不是'丢给它就不管'。

六、与 VS Code、TRAE 等工具的对比

1. 与 VS Code 的对比

• 定位：
  • VS Code：通用图形 IDE，扩展生态极其庞大，是'操作系统级开发环境'。
  • OpenCode：项目级 AI 编程代理，终端优先、强调自动执行和工作流集成。
• AI 能力：
  • VS Code：官方 Copilot 提供补全、简单 refactor、问答；第三方 AI 插件也很多，但大多是'聊天 + 补全'，缺乏真正'项目级 Agent 能力'。
  • OpenCode：有 AGENTS.md 项目记忆、Plan/Build 模式、可以在 GitHub Actions 里自动干活，而不是只在编辑器里提建议。
• 集成：
  • VS Code：集成度高，但更多是'编辑器内部集成'；
  • OpenCode：深度集成 GitHub/GitLab workflow，可以在 PR/issue 层面被调用，作为 CI/CD 的一部分。
• 使用门槛：
  • VS Code：GUI 友好，对新手更友好；
  • OpenCode：偏终端/命令行，对愿意折腾的工程师更有吸引力。

一句话：

• 想要'稳当好用、生态丰富'的 GUI IDE → VS Code + Copilot；
• 想要'一个能主动跑任务、参与协同的 AI 同事' → OpenCode（两者完全也可以结合用）。

2. 与 TRAE 的对比

• 定位：
  • TRAE：一个'开发者友好的 IDE'，提供 AI Q&A、内联补全和 Agent 工作流，使用 GLM 系列模型，偏向'开箱即用'的一体化体验。
  • OpenCode：更通用、更底层的'开源编码代理'，支持任意模型、可自托管，更偏'工程化 / DevOps 化'的场景。
• 模型与供应商：
  • TRAE：深度绑定 Z.AI/GLM 生态，强调用量和价格优势；
  • OpenCode：供应商无关，你可以选择 Claude / OpenAI / Google / 本地 / OpenCode Zen 等任一组合。
• 使用体验：
  • TRAE：偏 IDE 体验，图形界面、内置预览和 Builder 模式等，对'前端/全栈'非常友好；
  • OpenCode：终端优先，TUI + 桌面版，更适配'后端 / DevOps / 运维 / 云原生'工作流。
• 集成：
  • TRAE：重心在 IDE 内的 AI 能力（coding、debug、重构等），在 Git 协同上相对传统；
  • OpenCode：在 GitHub/GitLab 层面直接集成，可自动开分支、提 PR、做 review 和定时任务，更适合将 AI 纳入团队流程。

一句话：

• 你更看重'图形化 IDE 的开箱即用体验、尤其是与 GLM 的结合' → TRAE；
• 你更看重'开源、可自托管、深度融入 GitHub 工作流的 Agent' → OpenCode。

3. 和 Cursor 等其他 AI IDE 的关系（简略）

• Cursor：
  • 优点：UI 类似 VS Code，开箱即用的强 AI 能力，补全/重构/搜索体验很成熟；
  • 不足：闭源、供应商绑定较深、目前与 CI/CD/PR 工作流的集成不如 OpenCode'工程化'。
• OpenCode：
  • 更像一个'可以在任何环境（包括 CI）里运行的 Agent'，而不是单独的 IDE。
  • 你完全可以 Cursor/VS Code 写代码，让 OpenCode 在 GitHub Actions 里帮忙做 review、自动修小 bug、跑定时检查等。

七、什么样的团队 / 个人最适合用 OpenCode？

特别适合：

• 频繁使用终端 / tmux / Neovim 的工程师；
• 对'开源 + 自托管 + 可审计'有强诉求的团队（例如金融、安全、政务）；
• 已经重度使用 GitHub/GitLab，希望把 AI 纳入 PR review、issue triage、定时检查流程；
• 对模型成本敏感，想在 Claude / OpenAI / 本地模型之间灵活切换的场景；
• 有 DevOps / 平台团队的团队，可以基于 OpenCode 的 SDK/插件做二次开发，深度定制工作流。

暂时不太适合：

• 完全不习惯命令行的开发者；
• 更看重'开箱即用 GUI IDE 体验'，而对开源、自托管、工作流集成要求不高的用户；
• 想要'一键安装就不用管'的产品，对模型配额 / 工作流 / 安全细节不太想操心的人。

八、写在最后

如果你是一个愿意折腾一点、想认真把'AI 当队友'而不是'当补全器'的开发者，OpenCode 是一个非常值得投入精力的工具。它把开源、Agent、终端体验和 GitHub/GitLab 工作流绑在一起，形成了一条真正'工程化'的 AI 编码路径。

不妨按上面的步骤装一个，先用 Plan 模式让它熟悉你的项目，再慢慢把一些'重复任务'交给它——你会发现，原来'让 AI 真正替你干活'，可以这么自然。

Github 地址：https://github.com/anomalyco/opencode
文档地址：https://opencode.ai/docs