Skip to content
Published on

Oh My OpenCode 使用指南 — 把 OpenCode 变成多代理团队

🇰🇷KO🇺🇸EN🇯🇵JA🇨🇳ZH
필사 모드
分享
Authors

概述

随着终端里运行的 AI 编码代理越来越多，如今要驾驭的已经不是"一个代理"，而是"一支代理团队"了。Oh My OpenCode 正是用来组建这支团队的工具。它的官网是 ohmyopencode.com，GitHub 仓库是 opensoft/oh-my-opencode，npm 包名是 oh-my-opencode。

Oh My OpenCode 不是一个独立的代理，而是叠加在 OpenCode 之上的、带有明确主张(opinionated)的插件与编排层。OpenCode 是 opencode.ai 发布的开源终端 AI 编码代理，是本文一切内容的前提条件。在它之上，Oh My OpenCode 添加了：

  • 行为方式类似 Claude Code 的异步子代理(async subagents)
  • 一份经过筛选、各自映射到合适模型的专业代理名册
  • 一组精选的 MCP 服务器
  • 内置的 LSP/AST 工具
  • "兼容 Claude Code" 层

一句话概括：这是一支活在终端里的虚拟 AI 开发团队。协调者制定计划，工作者(worker)编写代码，专家(specialist)审查架构、翻找文档。本文将从 OpenCode 的基础用法讲起，依次覆盖 Oh My OpenCode 的安装与配置、多代理团队的组建、实际任务的执行，以及必须掌握的成本安全知识。

顺带一提，还存在一个由另一位作者开发的姊妹项目 oh-my-openagent(别名 lazycodex)。名字相近容易混淆，这里只提一句它的存在，本文则严格聚焦于 oh-my-opencode。

异步子代理为什么重要

以往的编码代理大多在单一对话流程中顺序移动：读一个文件，改一个文件，再切到下一个文件。这种方式应付小改动没问题，但在需要同时审视数十个文件的大任务上会成为瓶颈。异步子代理打破了这个瓶颈——主代理同时拉起多个子代理，让它们并行处理不同的文件或不同的视角。

Claude Code 让这种模式流行起来，Oh My OpenCode 则在 OpenCode 之上重现了它。协调者把握全局，把代码库搜索交给 Explore，把文档调研交给 Librarian，把架构判断交给 Oracle。每个子代理只完成自己的那一份工作，再把结果交回协调者，于是原本需要人在多个终端标签页之间手动协调的事情，就由工具代劳了。本文接下来的内容，就是关于如何真正驱动这支团队。

1. 前提条件 — 安装并使用 OpenCode

在接触 Oh My OpenCode 之前，得先安装 OpenCode 并熟悉它的基本用法。没有 OpenCode，Oh My OpenCode 也无法运作。

1.1 安装

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

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

如果更习惯 npm 或 Homebrew，以下方式也可以。

npm i -g opencode-ai

brew install anomalyco/tap/opencode

1.2 在项目中运行

安装完成后，进入想要工作的项目目录并执行。

cd my-project
opencode

这样会打开终端 UI(TUI)。如果是第一次运行，建议先熟悉以下命令。

  • /init — 扫描仓库并生成 AGENTS.md 文件。它会成为代理理解项目结构与约定的基准文档。
  • /connect — 添加模型提供方(provider)。OpenRouter、OpenAI、Anthropic、本地模型等任选其一，出现提示时粘贴 API key 即可。
  • Tab — 在 Plan 模式与 Build 模式之间切换。适合先制定计划、再转入执行的流程。
  • @ — 对文件做模糊搜索(fuzzy-find)。可以快速把文件拉进上下文。
  • /share、/undo、/redo — 分享会话、撤销、重做。出错时非常好用。

1.3 以连接 OpenRouter 为例

运行 /connect 会列出提供方列表。选择 OpenRouter 后会要求输入 API key，把在 openrouter.ai 上生成的 key 粘贴进去即可。OpenRouter 让你用一个 key 就能访问多个模型，在实验后面会讲到的按代理分配模型时尤其方便。连接完成后，就可以直接在 TUI 里选择模型使用。

1.4 区分 Plan 模式与 Build 模式的习惯

用 Tab 切换的这两种模式，不只是一个 UI 开关，而是一种工作态度上的差异。Plan 模式让代理先提出要做什么、怎么做，而不立即改动代码。Build 模式则会真正修改文件并执行。在还不熟练之前，建议先在 Plan 模式下确认方案，觉得方向没问题了，再转入 Build 模式。仅仅这一个习惯，就能大幅减少"代理动错了文件"之类的事故。后面会讲到的 Oh My OpenCode 的计划优先流程，说到底也是这两种模式的延伸版本。

2. 安装 Oh My OpenCode

熟悉了 OpenCode 之后，就该组建团队了。Oh My OpenCode 的安装要在项目根目录执行，需要 Bun 或 npx。

2.1 交互式安装

最标准的方式是用 bunx 运行安装程序。

bunx oh-my-opencode install

这个命令会启动一个交互式 TUI。在这里逐步选择要使用哪些代理、要接入哪些工具和 MCP，剩下的接线(wiring)工作会自动完成。如果是第一次使用，建议走这条交互式路径。

2.2 非交互式安装(用于 CI / 代理)

如果需要在 CI 流水线或另一个代理里自动运行，可以不使用交互式 UI，直接用参数指定。

bunx oh-my-opencode install --no-tui \
  --claude=<yes|no|max20> --openai=<yes|no> \
  --gemini=<yes|no> --copilot=<yes|no>

每个参数决定接入哪个提供方。例如 --claude=max20 表示以更高等级接入 Claude 系列，不需要的提供方用 no 关闭即可。

2.3 验证安装

安装完成后，确认项目里是否已生成 .opencode/ 目录及相关配置。此后再次运行 OpenCode 时，TUI 会带着 Oh My OpenCode 接好的代理、工具与 MCP 一并加载起来。如果看不到代理，首先该检查的是有没有误用了全局安装、以及是不是在项目根目录下运行的。大多数初期问题，都出在运行位置或包名弄错了。

2.4 必须知道的注意事项

安装环节有几个常见的错误，需要明确说清楚。

  • 不支持全局安装。npm i -g 或 bun add -g 都不是支持的方式，必须在项目根目录用 bunx 运行。
  • npm 上的 omo 是完全不相关的包。运行 bunx omo 会执行一个无关的包，绝对不要这样做。
  • 也不要与前面提到的姊妹项目 oh-my-openagent(lazycodex)混淆。名字虽然相近，但它不是本文的对象。

3. 配置 — 按代理、按分类的模型覆盖

Oh My OpenCode 真正的威力在于配置——因为可以细粒度地控制哪个代理使用哪个模型。

3.1 配置文件位置

配置文件可以放在两个位置之一。

  • 按项目：.opencode/oh-my-opencode.jsonc
  • 按用户：~/.config/opencode/oh-my-opencode.json

按项目的配置只作用于该仓库，按用户的配置则作用于所有项目。对于团队仓库，把按项目的配置文件提交进版本库，更有利于可复现性。

3.2 模型覆盖示例

可以按代理、也可以按分类来更换模型。JSONC 允许写注释，因此可以把配置意图直接留在文件里。

{
  "agents": {
    "explore": { "model": "ollama/qwen2.5-coder:7b" },
    "oracle": { "model": "openai/gpt-5.4" }
  },
  "categories": {
    "quick": { "model": "ollama/qwen2.5-coder:7b" },
    "deep": { "model": "openai/gpt-5.3-codex" }
  }
}

上面的例子同时展示了两个维度。agents 块把便宜的本地模型分配给某个特定代理(比如负责快速翻找代码库的 Explore)，而给负责架构咨询的 Oracle 配上更强的模型。categories 块则按任务性质分组，把轻量、频繁的 quick 任务路由到本地模型，把繁重的 deep 任务路由到 codex 系列模型。后面的分类小节会更详细地展开这个概念。

3.3 代理级覆盖与分类级覆盖的优先级

一个常被问到的问题是："当代理上指定的模型与分类上指定的模型冲突时，谁说了算？"从概念上理清楚是这样的。分类是一条宽规则，决定动态生成的代理(例如 Sisyphus-Junior)应该继承哪个模型，依据的是任务的类型。而代理级设置是一条窄规则，直接绑定在某个名字固定的具体代理上(例如 Oracle、Explore)。因此在实践中，把名字明确、常驻的代理放在 agents 里管理，把按任务类型动态分岔的执行者放在 categories 里管理，这样划分角色能让配置更清晰。

3.4 在团队仓库中共享配置

把按项目的 .opencode/oh-my-opencode.jsonc 提交进仓库，能让团队所有成员使用同一套代理-模型映射工作。这能减少"我本地用便宜模型跑得好好的，同事那边却跳到贵模型上了"这类可复现性问题。不过，API key 之类的机密信息不应该放进这个文件。key 应该通过前面提到的 /connect 流程或按提供方设置的环境变量来管理，配置文件里只留下模型选择、并发限制这类策略性内容，这是原则。

4. 多代理团队 — 代理名册

Oh My OpenCode 提供了一份角色明确的代理名册。每个代理都有名字、职责，以及推荐模型。下表按角色组做了整理。

角色组代理职责推荐模型 / 特点
编排者Sisyphus主协调者。制定计划并委派任务，以激进的并行执行方式推进工作默认 Claude Opus
编排者Atlas待办事项(todo-list)编排者Claude Sonnet
规划Prometheus战略规划者。通过 Tab 或 /start-work 启动，用访谈方式锁定范围专注规划
规划Metis差距分析器(gap analyser)。找出被遗漏的部分较高 temperature
规划Momus严苛的计划评审者。承担 OK/拒绝的门禁角色审批门禁
工作者Hephaestus自主的深度编码者。需要强力的 codex 级模型codex 级模型
工作者Sisyphus-Junior动态生成的执行者。继承启动它的那个分类所对应的模型继承自分类
专家Oracle架构/调试顾问(偏向只读)强推理模型
专家Librarian文档调研者。便宜快速的模型就够用低成本模型
专家Explore通过 grep/模式匹配快速并行检索代码库快速模型
专家Multimodal Looker视觉。读取图表/PDF/图像多模态模型

理解这份名册的关键，是"谁做什么，以及花多少成本"。编排者与规划者掌控整体流程，工作者真正产出代码，而专家是只读或工具受限的子代理，只负责某一项特定任务。比如，翻找文档的 Librarian、搜索代码库的 Explore，没有理由配上昂贵的模型，而自主深入写代码的 Hephaestus 则确实需要强力模型。

把这份名册映射到实际的模型预算时，大致可以按以下原则思考。

  • 编排者(Sisyphus、Atlas)：负责统筹全局，判断力强的高阶模型更划算。尊重默认配置，如果预算紧张，先从 Atlas 那一侧往下调。
  • 规划者(Prometheus、Metis、Momus)：计划质量直接左右结果，因此要避免用过于便宜的模型。记住 Metis 是靠较高的 temperature 去找漏洞的角色。
  • 工作者(Hephaestus、Sisyphus-Junior)：与实际实现质量直接挂钩。给 Hephaestus 配 codex 级模型，让 Sisyphus-Junior 通过分类继承合适的模型。
  • 专家(Oracle、Librarian、Explore、Multimodal Looker)：角色差异很大。给 Oracle 和 Multimodal Looker 配强模型、给 Librarian 和 Explore 配便宜快速的模型，是更划算的做法。

4.1 只读专家带来的安全性

专家组是只读或工具受限的，这不只是一种限制，而是一种设计层面的安全机制。当 Oracle 诊断架构、或 Explore 翻查代码时，把它们绑定成无法直接修改文件，就能从根源上杜绝咨询过程中意外改动代码的事故。真正的改动只交给 Hephaestus、Sisyphus-Junior 这类工作者，专家则被限定为只提供建议与信息。正因为有这层结构，即便并行跑着多个代理，真正能写文件的角色也被收窄到少数几个工作者，整体因此更容易控制。

5. 用 ultrawork 执行任务

有了代理团队，不代表随便输入一个提示词团队就会自动动起来。多代理委派必须显式触发。

5.1 触发关键词

多代理委派要在提示词里包含关键词 ultrawork(前缀 ulw)才会发动。这不是自动的。也就是说，普通提示词由单一代理处理，要动员整个团队，就必须刻意加上 ultrawork(或 ulw)。

5.2 计划优先的流程

任务越重，越应该先制定计划，而不是直接执行。用 Tab 或 /start-work 拉起 Prometheus，这个规划者会通过访谈把任务范围明确锁定下来。范围还模糊不清就跑并行执行，子代理们可能会各自朝不同方向冲，因此大任务遵循"先计划、后执行"的顺序更安全。

5.3 分类路由

被委派的任务会通过分类(category)来路由。每个分类都映射到一个推荐模型和一条回退链(fallback chain)。分类如下：

  • visual-engineering
  • artistry
  • ultrabrain
  • deep
  • unspecified-high
  • unspecified-low
  • quick
  • writing

任务被归到哪个分类，决定了会配上哪个模型。正如第 3 章所见，按分类覆盖模型，就能把成本与性能调整到与任务性质相匹配。

5.4 启动开销

有一点现实的注意事项。多代理编排存在实实在在的启动开销。在正式任务开始之前，大约会消耗 15,000~25,000 个 token。把这份开销加在小任务上是亏本的，因此何时动员团队的判断很重要。这个判断会在最后一章总结。

5.5 典型的工作流程

把前面这些要素串起来，大任务的标准流程大致如下。

  1. 用 Tab 或 /start-work 拉起 Prometheus 制定计划，认真回答访谈以缩小范围。
  2. 如有需要，Metis 找出计划的漏洞，Momus 批准或驳回计划。
  3. 计划通过后，在提示词里加上 ultrawork(或 ulw)来触发多代理执行。
  4. Sisyphus 按分类拆分任务并委派：搜索交给 Explore，文档交给 Librarian，深度实现交给 Hephaestus，架构判断交给 Oracle。
  5. 各个子代理的结果汇总回协调者后，检查最终改动，需要时用 /undo 回滚。

把这套流程内化后，就能避开"不做计划直接 ultrawork"这种危险习惯。即便计划阶段很短，先把范围锁定下来，也是防止并行执行失控冲向错误方向的最便宜的保险。

6. 成本安全 — 必须留意

这一部分需要坦诚地说清楚。多代理工具带来便利的同时，也带来了成本失控的风险。

6.1 一次真实发生过的事故

早期确认过一个 bug，导致出现意料之外的大额支出。有用户报告说，仅仅一个下午就被收取了约 438 美元。原因是悄无声息发生的模型路由(silent model routing)和失控循环(runaway loop)。也就是说，任务在用户没有预期的情况下被路由到了昂贵的模型上，而这个过程没有停下来，反复循环，导致成本像滚雪球一样越滚越大。

6.2 用并发限制来防御

最实用的防御手段，是在配置里限制提供方的并发数(concurrency)。可以像下面这样，把某个提供方的并发执行数锁住。

{ "background_task": { "providerConcurrency": { "google": 1 } } }

这个配置把后台任务中 google 提供方的并发执行数限制为 1。即便发生失控循环，并行调用也会被压制，从而减少损失。

6.3 其他安全守则

除了并发限制之外，把以下几点养成习惯也有帮助。

  • 审计(audit)分类与模型配置，明确掌握哪个任务会流向哪个模型。
  • 给会被大量调用的子代理优先配置更便宜的模型。Librarian、Explore 这类高频角色就是典型例子。
  • 定期查看提供方的支出仪表盘。尽早发现异常，是最好的防御。

6.4 大任务开始前的预检

成本事故大多爆发在"不假思索就跑起来的大任务"上。所以在用 ultrawork 发动规模较大的任务之前，养成用肉眼确认三件事的习惯会很有帮助。第一，重新看一遍配置文件里每个分类映射到的是哪个模型。第二，确认是否设置了并发限制。第三，如果当前接入的提供方是付费等级，在脑子里大致估算一下预期成本。这个 30 秒左右的检查，就是防止前面那种一个下午约 438 美元事故的最现实的一道防线。

7. 什么时候该用它、什么时候用原版 OpenCode

最后是最实用的问题。所有任务都用 Oh My OpenCode，并不是正确答案。

Oh My OpenCode 大放异彩的场景，是规模大、跨越多个文件、并且分为多个阶段的任务。像调研 → 计划 → 实现这样能发挥并行子代理优势的流程，正合适。在这类场景里，团队会是一个明显的力量倍增器(power multiplier)。

反过来，对于能装进单一上下文窗口的小任务，或者跑预算型(budget)模型的场景，原版 OpenCode 更合适。预算型模型在一段干净利落的提示词里往往表现更好。给这类任务动用多代理，只会白白付出前面提到的启动开销，纯属浪费。

归纳一下：Oh My OpenCode 对合适的任务是强力的力量倍增器，对不合适的任务则只是开销。选择的依据应该是任务的规模、阶段数，以及能从并行化中获得多少收益。

7.1 选择清单

如果拿不定主意，不妨回答以下问题。"是"越多，就越偏向选择 Oh My OpenCode。

  • 这个任务是否会涉及三个以上文件？
  • 是否分为调研、计划、实现这类性质不同的阶段？
  • 是否存在彼此独立、可以并行推进的子任务？
  • 是否有预算余地去配置强模型？

反过来，如果符合"这一个提示词就能搞定"、"只跑预算型本地模型"、"一两个文件的上下文就够了"，那么原版 OpenCode 才是正确的选择。挑选工具的依据，不是喜好，而是任务本身的形态。

7.2 一览式总结

把本文的核心按顺序重新整理一遍：

  • 先安装 OpenCode，熟悉 /init、/connect、Tab。
  • 在项目根目录用 bunx oh-my-opencode install 把团队接线组装起来。切记不要全局安装，也不要用 bunx omo。
  • 在 .opencode/oh-my-opencode.jsonc 里按代理、按分类调整模型。
  • 大任务先用 Tab 或 /start-work 制定计划，再用 ultrawork 执行。
  • 设置并发限制，审计分类-模型映射，定期查看支出仪表盘。
  • 小任务或预算型模型，用原版 OpenCode。

只要守住这六条，就能拿到 Oh My OpenCode 的大部分好处，同时避开它大部分的风险。

参考资料

Discuss on Twitter • View on GitHub