OpenCode 使用指南：快速上手、实战技巧，以及何时搭配 Oh My OpenCode

Name

Soren Atelier

更新于 2026/3/17

OpenCode 是一个面向终端工作流的开源 AI coding agent。它不只是“能写代码的聊天窗口”，更像是把理解代码、规划修改、执行命令、审查差异这几个动作串起来的工作台。对大多数人来说，真正的问题不是“能不能用”，而是“什么时候只用 OpenCode，什么时候再加一层 Oh My OpenCode 的 orchestration”。

最稳妥的起点是 先用 OpenCode 本体。先跑通 plan / build，把 AGENTS.md 建起来，理解权限和自定义命令怎么配，再决定要不要上更强的多模型编排。这样学习成本更低，也更容易判断工具到底值不值得引入。

如果你想先看更完整的 AI coding 背景，可以先读 AI Coding 主题页、Codex 使用指南 和 Parallel Code Agents 解析。如果你想先看更高层的 agent 框架对比，OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot 也很适合作为补充阅读。

先说结论：OpenCode 单独用，还是搭配 Oh My OpenCode？

OpenCode 本身就覆盖了大多数开发者需要的核心闭环：理解代码、规划修改、安全编辑、持续验证。Oh My OpenCode 很有价值，但不应该是第一步。

OpenCode 到底是什么

OpenCode 是一个以终端为中心的开源 AI coding agent。官方 README 和文档把它描述成下面这些东西的组合：

• 以 TUI 为主的 coding agent
• 处于 beta 阶段的 desktop app
• 一个 IDE extension
• 一个 provider-agnostic 的系统，可以接入 OpenAI、Anthropic、Google 等不同模型后端
• 一套包含 built-in agent、权限、custom commands、rules、格式化和 LSP support 的工具链

更重要的是，OpenCode 不应该只被理解成“会写代码的对话框”。它更像是一个 agent workflow 的操作界面。你可以用它做这些事：

• 快速看懂陌生仓库
• 先规划，再动手改代码
• 编辑文件并执行 shell 命令
• 用 AGENTS.md 固化仓库规则
• 定义可重复使用的 slash command
• 根据仓库风险收紧或放宽权限

有个细节要注意，旧教程里不少链接已经过时了。截至 2026 年 3 月 17 日，OpenCode 现在的发布仓库是 anomalyco/opencode，最新 release 是 v1.2.27，发布时间是 2026 年 3 月 16 日。如果你碰到旧的 archived repo，那个已经不是当前的安装目标了。

OpenCode 快速上手

1. 先安装 OpenCode

官方最短路径是：

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

你也可以通过 Homebrew、npm、Scoop、Chocolatey、mise 或 nix 安装，不过想先快速试用的话，安装脚本最直接。

2. 连接 provider，然后打开一个真实项目

启动后，官方 docs 建议走这个流程：

/connect

然后在 TUI 里选择 opencode，去 opencode.ai/auth 完成认证，或者配置你已经在用的 provider。

实操里别一上来就挑最大的仓库。先拿一个你自己大概看得懂、也能 review 的项目开始，会更容易判断 OpenCode 到底哪里好用。

3. 在正式提需求前先跑 /init

OpenCode 可以为仓库生成 AGENTS.md。

/init

这会给后续的 agent 留下长期有效的项目规则。建议直接提交到 Git。这样做的价值很高，因为它能减少重复输入，也能让多轮会话里的行为更稳定。

4. 一开始优先用 plan

OpenCode 里有两个可以通过 Tab 切换的 built-in agent：

• build 负责真正干活
• plan 负责分析和探索

第一次任务建议先用 plan，而且范围要窄一点。

请总结这个仓库的 build / test / release 流程。
再指出主要入口文件。
先不要修改任何内容。

等你确认它真的理解了项目结构，再切到 build 就够了。

7 个真正有用的实战技巧

Tip 1：陌生代码库里，把 plan 当默认模式

把 plan 和 build 分开，不只是为了安全，也是在提升质量。

如果你一上来就进 build，模型可能会在理解还没完全确认时就开始改文件。先走 plan，可以更快确认 architecture、命名、测试流和影响面。

比如这样问：

请解释 `@src/auth/index.ts` 里的认证流程。
然后给我两个最小修改方案。
先不要编辑。

@ 这种文件引用在实际使用里非常省事，也是 OpenCode 比较实用的地方。

Tip 2：别把 /init 和 AGENTS.md 当成“文档工作”

这不是可有可无的 setup，而是很强的 leverage 点。

AGENTS.md 里适合放这些内容：

• build / test / lint 命令
• 仓库结构和 package 边界
• 风格规则和 review 预期
• 不要碰的范围
• 什么才算 done

如果不这么做，你就会在每次对话里重复同样的约束，信息噪音会很大。

这个思路和 Claude Agent SDK 搭建 Claude-Code-Like AI Agent 很一致。无论用什么 agent，长期规则都应该有一个稳定落点。

Tip 3：权限先收紧，再慢慢放开

OpenCode 的权限是可配置的，官方文档也明确支持 allow、ask、deny 这类控制方式。

如果是新仓库，建议先用保守一些的配置：

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

这样会稍微慢一点，但能避免很多早期误操作。等你确认行为稳定后，再把低风险命令逐步放宽就行。

Tip 4：先做几个自定义命令，再考虑加更多工具

OpenCode 除了 /init、/undo、/redo、/share、/help 这些 built-in command，还支持通过 .opencode/commands/ 添加自定义命令。

这意味着很多“高级工作流”其实不需要马上上新框架。你可以先做这些命令：

• /test
• /review
• /ship-check
• /seo-page

例如：

---
description: Run tests related to the current change
agent: build
---
 
运行这次 session 里涉及文件的相关测试。
先总结失败，再给出最小可行的修复方案。

这样常用提示词会短很多，也更容易复用。

Tip 5：先把一个 provider 用顺，再去追求全家桶

provider-agnostic 是优点，但也很容易把人带进“先搭五个 provider 再说”的陷阱。

不用一开始就搞 5 个 provider、3 层 fallback chain 和一堆自定义 model matrix。先从你本来就在付费、也最熟悉的那个 provider 开始就够了。

如果你刚进入这个类别，建议配合看一遍 Codex 使用指南。不同产品方向里，其实都在说同一件事：先收敛任务，再扩展工具。

Tip 6：terminal、desktop、IDE 的适用场景不一样

OpenCode 现在已经不只是一个 terminal binary 了。

如果你要的是最快的 prompt-edit-test 往返，就用 terminal。

如果你更看重 review 可视化、session 管理和界面舒适度，就用 desktop app。

如果你不想离开现有编辑器，就用 IDE extension。

真正的错误不是选错一次，而是拿不适合当前任务的入口硬上。

Tip 7：可以让它负责格式化，但不能把判断力也外包出去

OpenCode 的官方 docs 提到，它在文件编辑后可以自动调用语言对应的 formatter。这个能力很实用，但 formatter 通过并不等于改动正确。

你仍然要看这些东西：

• 实现是否真的满足需求
• 它想执行的 bash 命令是否合理
• 有没有遵守 AGENTS.md
• patch 范围是不是过大

AI coding agent 的价值是减少打字，不是替代工程判断。

什么时候该加 Oh My OpenCode

Oh My OpenCode 不是 OpenCode 本体，而是一个围绕 OpenCode 的更强 orchestration layer。

现在的 docs 和 README 里，它强调的是这些能力：

• 把 specialist agent 组织起来
• 按 category 路由模型
• background agent 和并行工作
• 更偏 MCP 的工作流
• 像 ultrawork / ulw 这样更强的完结导向
• 更像 harness 的使用方式

当你开始觉得 OpenCode 本体“够用，但还不够自动化”时，就到了考虑它的时候。

Oh My OpenCode 的价值不是说 OpenCode 不行，而是它把 delegation、orchestration 和 model specialization 再往前推了一步，适合想把 agent 真的当团队用的人。

OpenCode 怎么和 Oh My OpenCode 搭配

1. 先把 OpenCode 本体跑顺

不要在一个你还没试过的基础工具上直接叠 harness。

在加任何东西之前，至少先确认这些动作你能自己复现：

• 安装 OpenCode
• 完成 provider 认证
• 跑 /init
• 跑一次 plan
• 跑一次 build

如果这一步都不稳，再加 Oh My OpenCode 只会让排错更难。

2. 先把命名关系搞清楚

这里有个容易混淆的点：

• GitHub repo 现在是 code-yeongyu/oh-my-openagent
• 但品牌名和包名仍然是 Oh My OpenCode
• 安装命令还是 oh-my-opencode

截至 2026 年 3 月 17 日，把它们理解成同一条项目线就行。

3. 用官方 installer 安装

最直接的手动方式是：

bunx oh-my-opencode install

项目自己的文档也鼓励让 AI agent 读取安装指南并按步骤执行，这和它的使用理念是一致的。

4. 一开始只试一个高价值命令

最有代表性的就是：

ultrawork

或者短写：

ulw

不过它不是魔法词。第一次最好只用在一个中等规模、完成标准明确的任务上。

比较适合的例子：

• 一个范围明确的 bug 修复，加上相关测试
• 单个 feature 的实现
• 一组噪音很大的文件整理
• 你已经很熟悉的 repo 里的并行调研 + 实现

不适合作为第一枪的例子：

• 需求不清的 greenfield architecture
• 没有 rollback plan 的 production migration
• 权限边界很敏感的仓库

5. 适合多模型编排的工作再用它

Oh My OpenCode 真正有意义的场景，通常是这些：

• planning / reasoning / frontend 想用不同模型
• 需要 background specialist
• 想更积极地使用 MCP
• 想把 subagent 的分工做得更严格

如果你大部分工作只是“改一个文件、跑测试、提交”，OpenCode 本体往往就够了。

OpenCode 单独用 vs OpenCode + Oh My OpenCode

比较稳妥的顺序是：

1. 先把 OpenCode 用熟
2. 准备好真实的 AGENTS.md
3. 做 2 到 3 个自定义命令
4. 收紧权限
5. 还不够，再上 Oh My OpenCode

常见坑

把 OpenCode 和 OpenClaw 搞混

这两个不是一回事。

如果你搜的是 OpenCode，但看到 OpenClaw 的内容，基本说明你真正需要的是 OpenCode。尤其是当你关心 plan、build、/init 和 Oh My OpenCode 的搭配时，更应该先认准这个项目。

直接信旧链接

OpenCode 相关信息里，repo 迁移和旧教程混在一起的概率不低。安装前先看官方 docs，能少走很多弯路。

还没学会基础用法就先叠 harness

如果你连 OpenCode 本体的行为都还没摸清，就很难分辨问题到底来自 base agent、harness、provider，还是 repo 规则。

一开始就把 subscription 配太满

provider flexibility 当然有价值，但第一步更重要的是：先把一个你已经在用的 provider 用顺。

FAQ

OpenCode 和 OpenClaw 是同一个项目吗？

不是。这个页面讲的是 OpenCode，也就是 opencode.ai 文档里介绍的那个开源 AI coding agent。

用 OpenCode 一定要装 Oh My OpenCode 吗？

不需要。OpenCode 单独就已经能很好地工作。Oh My OpenCode 更适合在你需要更强 orchestration、更多模型协作，或者更强的 task completion 压力时再加。

刚安装完先做什么？

先执行 /connect，打开一个真实项目，运行 /init，再用 plan 让它总结仓库结构，然后再进入编辑。

我应该先用 terminal、desktop 还是 IDE？

默认先从 terminal 开始。如果你已经明确自己偏好 review-heavy 的 desktop workflow，或者更想留在 editor 里，那再选别的入口。

什么时候说明我已经可以考虑 Oh My OpenCode？

当你已经能自然地使用 OpenCode，本地的 AGENTS.md 也比较完善，而且你开始反复想把多个专长 agent 串起来做事时，就是信号了。

Related Guides

• AI Coding 主题页
• Codex 使用指南
• Parallel Code Agents 解析
• Claude Agent SDK 搭建 Claude-Code-Like AI Agent
• OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot