實戰手冊 · Field Manual 2026 春季號 · Vol.03
github.com/Yeachan-Heo/oh-my-claudecode · 35.0k ★
O
第 03 期 · 多代理編排 / Claude Code

Claude Code
多代理編排
框架 OMC。

oh-my-claudecode（OMC）是韓國工程師 Yeachan Heo 開源的 Claude Code 多代理編排框架，在五個月內累積 35,069 顆星、3,213 個 fork。它在 Claude Code 之上加入一個專案管理層，可自動拆分任務、開分支、跨 codex／gemini CLI 多開 tmux 工作池，並寫入驗證證據。本手冊說明安裝步驟、Team 模式管線、Autopilot／Ralph／Ultrawork 的差異，以及 v4.4 拆除 MCP 後的設定調整。

35.0k
GitHub Stars
19
專家代理
27
內建斜線指令
MIT
開源授權
01
框架定位

Claude Code 的專案管理層，
非 IDE 替代品。

OMC 於 2026 年 1 月 9 日發布首版，五個月內累積 35,069 顆星、3,213 個 fork。作者 Yeachan Heo 將其定位為 Teams-first Multi-agent orchestration for Claude Code。它不直接生成程式碼，而是在 Claude Code 之上建立一套可自動拆分任務、派工、執行測試並驗證結果的多代理框架。

OMC 以 npm 套件（oh-my-claude-sisyphus）與 Claude Code Plugin 兩種形態發布。安裝後新增 19 個專家代理（architect、executor、qa-tester、security-reviewer、debugger 等）、27 個斜線指令，以及 Team 階段管線。輸入一句 /autopilot "build a REST API for managing tasks"，後續的規劃、執行、驗證、修正均由 OMC 自動完成。

v4.4.0 移除了 codex 與 gemini 的 MCP servers，改以 tmux 直接開啟真實的 CLI 工作池（omc team 2:codex "..." 會在 tmux 開兩個 codex pane）。codex、gemini 作為外部工具按需啟動、執行完畢即關閉。這是 OMC 稱為 "team-first" 的具體實作方式。

Team Mode · 階段管線
team-plan→ team-prd→ team-exec→ team-verify→ team-fix↺
Don't learn Claude Code.
Just use OMC.
— oh-my-claudecode README 開場宣言
02
三步驟安裝

安裝 Plugin，執行 setup，
再以 autopilot 起始第一個任務。

OMC 提供兩種安裝路徑。多數人建議使用 Claude Code Plugin marketplace，在 session 中依序輸入以下兩條指令（README 強調：一次貼兩條會失敗，須逐條送出）。

# 第一條:加入 marketplace 來源 /plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode # 第二條:安裝外掛(等上一條完成才送這條) /plugin install oh-my-claudecode

或者走 npm 路線(終端機愛好者)

npm 版本的套件名稱是 oh-my-claude-sisyphus(repo 是 oh-my-claudecode,但 npm 名留著舊名)。裝完會多一個 omc 終端機指令,可以從 shell 直接跑 team / ask / wait 等子命令。

npm i -g oh-my-claude-sisyphus@latest

跑 setup,並啟用 Claude Code 原生 Teams

安裝完成後，在 Claude Code session 內輸入 /setup 或 /omc-setup（也可從終端機執行 omc setup）。若要讓 Team 模式正常運作，還需開啟 Claude Code 的實驗性 Teams 開關。請編輯 ~/.claude/settings.json，加入以下設定。

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
以 autopilot 起始第一個任務。安裝完成後直接輸入 /autopilot "build a REST API for managing tasks"，OMC 會自動拆分任務、開分支、執行測試、驗證、修正錯誤。若需求尚不明確，先以 /deep-interview "我想做 XX" 透過提問將需求量化成規格後，再進入下游模式。
03
10 個編排模式 + 10 個核心指令

OMC 的 20 個編排模式
與常用指令總覽。

OMC 將編排能力分為兩層：上層是編排模式（決定如何將任務分配給多代理），下層是斜線指令（執行具體操作）。下表整理 README 列出的核心 20 項，前 10 個是模式、後 10 個是常用指令。日常使用以 /team、/autopilot、/ralph 為主要入口。

Mode · 01
/team
canonical orchestration
v4.1.7 之後的官方推薦模式。階段管線:plan → prd → exec → verify → fix 迴圈。需開啟 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS。
Mode · 02
omc team
tmux CLI workers
從終端機開 tmux pane,真實的 claude / codex / gemini 多個 CLI 行程並行。用完即關,不佔資源。
Mode · 03
/ccg
tri-model advisor
在一條指令裡同時呼叫 codex 與 gemini,Claude 自己負責綜合兩邊意見輸出最終結論。
Mode · 04
/autopilot
end-to-end autonomy
單一主代理自主執行。輸入一句「做出 X」，OMC 自行規劃、撰寫、執行、驗證。操作步驟最少的入門模式。
Mode · 05
/ralph
persistent verify loop
持續驗證模式。verify／fix 迴圈執行至所有證據通過為止，不提前停止。內建 ultrawork 平行能力。
Mode · 06
/ultrawork
maximum parallelism
非 team 場景的高並行修正模式。同時修改多個檔案，不走 PRD，不自動執行 verify。簡寫 ulw。
Mode · 07
UltraQA
repeated quality gates
tests / build / lint / typecheck 全綠之前不停。專門對付那種「修 A 又壞 B」的長尾錯誤。
Mode · 08
/ralplan
iterative plan consensus
規劃階段的 ralph。同一份 plan 反覆迭代,直到多方代理意見收斂,再進 exec。
Mode · 09
Pipeline
sequential stages
嚴格依序執行的多階段轉換。適合 ETL、遷移、轉檔等不能亂序的場景。
Mode · 10
Ultragoal
artifact-only goals
不啟動 loop,但會落地一份「目標 + checkpoint + 證據」檔案。交接、稽核、被迫不能跑 loop 時的選擇。
Skill · 11
/deep-interview
socratic clarification
蘇格拉底式逼問。把模糊想法用加權維度量化清晰度,逼出隱藏假設,再交給下游 mode。
Skill · 12
/ask
provider advisor
把當前情境丟給其他 provider CLI(claude / codex / gemini)諮詢,自動存成 .omc/artifacts/ask/ markdown。
Skill · 13
/skill
skill library
列 / 加 / 刪 / 改 / 搜你自己累積的 .omc/skills/*.md。專案層覆蓋使用者層,trigger 命中自動注入。
Skill · 14
/skillify
pattern extractor
將當前 session 的解題過程，經嚴格品質 gate 後提取為可重用的 skill 檔，供後續任務自動注入。
Skill · 15
/oh-my-claudecode:autoresearch
bounded research loop
v4.4 之後的正規研究流程。配合 /deep-interview --autoresearch 起 mission,跑有上限的 stateful 迴圈。
Skill · 16
/oh-my-claudecode:hud
live statusline
即時觀測列。focused preset 把目前的 agent、token 用量、階段、子任務數攤在 Claude Code 狀態列上。
Skill · 17
/omc-doctor
health check
出錯時的第一站。檢查 plugin 路徑、cache、CLI 工具、tmux、env 變數，並清掉舊的 plugin cache。
Skill · 18
omc wait
rate-limit resume
Claude rate-limit 期間的 session 恢復工具。omc wait --start 啟動背景 daemon，額度恢復後自動重啟原本的 session。
Skill · 19
ultrathink
deep reasoning
關鍵字觸發模式：在 prompt 中加入 "ultrathink about ..." 時，OMC 切換至最深的思考路徑與較高權重的模型推理。
Skill · 20
cancelomc / stopomc
emergency stop
所有 OMC 模式的緊急停止指令。迴圈異常、autopilot 偏離、token 用量過高時，輸入 stopomc 立即終止所有執行中的模式。

場景與建議模式對照

你的場景 建議模式 為什麼
跨多檔、有 PRD、需要分階段協作 /team plan→prd→exec→verify→fix 階段管線,Claude 原生 Teams 撐住協作。
一句話功能、不想顧任何儀式 /autopilot 單一主代理跑完整流程,最低門檻入門。
「修不好不准停」、要證據導向完成 /ralph verify/fix loop + 內建 ultrawork,直到證據全綠。
需要 codex / gemini 真實 CLI 並行 omc team N:codex "..." v4.4 起的 tmux 工作池,跨模型多 CLI 真實並行。
需求還模糊不清 /deep-interview 蘇格拉底逼問把規格量化,再選下游模式。
04
README 與 CHANGELOG 關鍵要點

10 條出自官方文件的
常見設定錯誤與修正。

OMC 主版本迭代頻繁，README 與 docs 篇幅較長，容易遺漏關鍵設定。以下 10 條均出自 README、docs、CHANGELOG 及 plugin 結構，是首次安裝最常觸發、但通常在第一週才被發現的問題。

TIP 01

兩條安裝指令要分開貼

README 明寫:「pasting both lines at once will fail」。/plugin marketplace add 跟 /plugin install 要等第一條跑完才送第二條,別把兩條黏在一起貼。

來源 · README · Quick Start
TIP 02

npm 套件名不是 oh-my-claudecode

repo / plugin / 指令都叫 oh-my-claudecode,但 npm 上發布的套件名留著舊名 oh-my-claude-sisyphus。npm i -g oh-my-claudecode 會裝錯包,要打成 npm i -g oh-my-claude-sisyphus@latest。

來源 · README · Package naming note
TIP 03

沒開 EXPERIMENTAL_AGENT_TEAMS,/team 會降級

Team 模式仰賴 Claude Code 的實驗性原生 Teams API。若未在 ~/.claude/settings.json 設定 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，OMC 會警告並退回非 team 執行模式，看似運作正常，但實際上已失去管線功能。

來源 · README · Team Mode 章節
TIP 04

v4.4 拆掉了 codex / gemini MCP server

v4.4.0 起，x、g provider 的 MCP server 已全數移除。要求安裝 MCP 的舊教學已過時。現在改用 omc team 2:codex "..." 直接在 tmux 開啟真實的 codex CLI pane。

來源 · README · v4.4.0 release note
TIP 05

swarm 別再用了,/team 才是 canonical

v4.1.7 起,legacy 的 swarm 關鍵字與 skill 整個移除。舊文章如果叫你 /swarm ...,直接改成 /team ...。/omc-teams 也只是 compat alias,內部還是路由到 omc team。

來源 · README · Team Mode 章節
TIP 06

autopilot 沒有 CLI 對應指令

終端機不支援 omc autopilot，README 明確說明沒有此子命令。autopilot、ralph、ultrawork、deep-interview 均為 session-only，只在 Claude Code 對話框內生效。

來源 · README · CLI vs In-session 對照表
TIP 07

把 skill 提交到 git 才能跨 worktree 共用

專案層 skill 存在 .omc/skills/,如果你在 worktree 裡新增但沒 commit,worktree 一砍 skill 就消失。要長期保留要 git add + commit。使用者層 (~/.omc/skills/) 則是跨專案共用。

來源 · README · Custom Skills 章節
TIP 08

autoresearch 是 hard-deprecated shim

舊版的 omc autoresearch 已被硬性下架。新流程是 /deep-interview --autoresearch 生 mission,再用 /oh-my-claudecode:autoresearch 跑 stateful loop。舊教學寫 omc autoresearch 直接跳過。

來源 · README · Utilities · Autoresearch
TIP 09

omc wait 自動接住 rate-limit

長跑 ralph / team 最怕中途 Claude rate-limit。先 omc wait --start 開背景 daemon,額度一恢復就自動把暫停的 session 拉起來。需要 tmux 才能偵測 session。

來源 · README · Rate Limit Wait 章節
TIP 10

--plugin-dir 模式要設 OMC_PLUGIN_ROOT

如果你用 claude --plugin-dir <path> 啟動,HUD 跟 setup 會找不到對應 plugin。要在 shell 裡 export OMC_PLUGIN_ROOT=<path> 或跑 setup 時加 --plugin-dir-mode,否則 plugin 安裝跟 runtime 路徑會分裂。

來源 · docs/REFERENCE.md · Plugin directory flags
05
實戰情境

/autopilot 執行完整任務的
階段流程示範：REST API。

以下示範 README 範例指令 /autopilot "build a REST API for managing tasks" 的實際執行過程，展示 OMC 的階段切換、HUD 狀態觀測，以及 ralph 在 verify 失敗時自動進入修正迴圈的行為。

~/projects/task-api · claude code · omc v4.4.x
You › /autopilot "build a REST API for managing tasks"
[omc-hud · focused preset] mode: autopilot · stage: planning · model: sonnet-4.6 active agents: planner → architect
planner › 先拆出 milestone: M1 · schema + 模型(Task, User, Tag) M2 · CRUD endpoints + 驗證 M3 · 認證 + rate limit M4 · 測試 + OpenAPI 文件
[handoff: planner → architect] architect › 技術棧建議 Fastify + Prisma + Postgres,理由: · TS 原生支援、async 模型乾淨 · Prisma 對 task 這種關聯式資料表更直觀
You › ok 用這個棧。繼續。
[stage: planning → execution] [delegates to executor + test-engineer]
[hud] active: executor (M1 schema) | test-engineer (vitest setup) [hud] tokens used: 18.4k / cost: $0.12
executor › 寫好 prisma/schema.prisma 與 src/models/task.ts · 14 files created · 412 lines
[stage: execution → verify] verifier › 跑 tests / build / typecheck / lint: ✓ build · ✓ typecheck · ✓ lint ✗ tests · 3/27 failing (task.search 邊界條件)
[autopilot detects verify gap → suggests /ralph] autopilot › 3 個測試失敗,要不要切到 ralph 模式由我修到全綠?
You › /ralph "fix the failing task.search tests"
[stage: ralph · verify/fix loop · iteration 1] [debugger reading test outputs · isolating root cause]
debugger › 根因:空字串 query 沒被 reject,進到 Prisma where 條件後 觸發 case-insensitive LIKE,索引失效又超時。 [executor patches src/services/search.ts] [verifier re-runs · iteration 2 · ✓ 27/27 passing]
[ralph exited · evidence ledger updated] · build ✓ · typecheck ✓ · lint ✓ · tests 27/27 ✓
You › /ccg "review the auth flow"
[stage: tri-model advisor] [/ask codex · 25.8s · returns architecture risks] [/ask gemini · 19.3s · returns UI/UX concerns on token refresh]
claude (synth) › 兩邊共通標的:refresh token rotation 沒做, session 過期時 client 沒有 graceful fallback。 codex 額外提:rate limiter 用 in-memory,scale-out 時會破。 gemini 額外提:錯誤訊息洩漏 user enumeration 風險。
You › /skillify
[extracting reusable pattern from this session] [quality gates: triggers ✓ · steps ✓ · scope ✓] [saved .omc/skills/fastify-prisma-task-api.md]
autopilot 偵測到 verify 缺口，主動建議切換至 ralph 模式，直到所有測試通過。
— OMC 模式間的協作機制：autopilot 可主動召喚 ralph

這段流程的三個關鍵設計

第一，autopilot 採用編排層架構，內部依序呼叫 planner → architect → executor → verifier。每個代理持有獨立 SKILL prompt，handoff 時攜帶完整上下文，verifier 不需重新讀取檔案。第二，ralph 是 autopilot 的持續驗證補充：autopilot 偵測到驗證缺口時會主動建議切換，不需要手動判斷是否進入修正迴圈。

第三，/skillify 將整段成功流程提取為 .omc/skills/*.md，下次執行類似任務時自動注入。這使得專案層的解題模式可以被保存並重複使用，更新速度快於模型訓練週期。

06
使用前須知

OMC 的功能邊界
與已知限制。

  • Token 用量會明顯放大。autopilot / team / ralph 都是多代理並行,每個 agent handoff 都會帶完整上下文,跑一輪 verify/fix loop 可能燒掉幾十萬 token。配合 omc wait 與 HUD 觀測,別讓 rate-limit 才驚醒。
  • tmux 是 omc team 的硬需求。omc team N:codex "..." 需要 tmux 環境才能開 worker pane,Windows 原生終端跑不起來。Windows 用戶請用 WSL2 + tmux。omc wait 偵測 session 也需要 tmux。
  • v4.4 拆 MCP 的相容性破口。升級到 v4.4.0 後,舊的 x / g MCP provider 直接失效。如果你在團隊裡有共用設定 / 自動化腳本依賴這兩個 provider,升版前先全文搜尋替換。
  • 實驗性 Teams API 可能變動。OMC team 模式依賴 Anthropic 標記為 EXPERIMENTAL 的功能。Claude Code 更新 API 時，OMC 可能退化或失靈。更新 Claude Code 前建議同步升級 OMC 至對應版本。
  • better-sqlite3 安裝警告不是錯誤。npm 安裝會看到 deprecated prebuild-install@7.1.3 警告,源自 better-sqlite3 的 native addon 依賴。README 在 issue #2913 追蹤,目前無法移除,但不影響 CLI 運作。
  • autopilot 等模式只能在 session 內使用。shell 腳本無法呼叫 omc autopilot ...，README 明確說明無對應 CLI 子命令。session-only 的模式還包括 ralph、ultrawork、deep-interview。CI 場景須改用 omc team 或 omc ask。
  • swarm / 舊 plan 觸發詞已移除。v4.1.7 拔掉 swarm,後續又拔掉 plan this / plan the 關鍵字 trigger。舊指令會直接無回應、不會自動轉址,請手動改成 /team 或 /ralplan。
  • evidence ledger 為 LLM 自評，需人工複核。autopilot／team 會執行多輪 review，但 evidence ledger 的結果仍由 LLM 判斷。API 設計、資料庫 schema、安全邊界等步驟務必人工複核，不可完全依賴 verifier 的 ✓ 標記。
07
進階路徑

將 OMC 設定為
團隊的標準工具。

OMC 的長期價值來自累積：將 skill、設定與 HUD 調整至符合自家 codebase 後，新任務的 verify 通過率會高於裸用 Claude Code 的情況。以下五條路徑說明如何將 OMC 從個人工具轉化為團隊共用資產。

進階設定路徑

1. 將專案層 skill 提交至 git。將 .omc/skills/*.md commit 到專案 repo，新工程師 clone 後即可取得專案的歷史解題記錄。trigger 命中時自動注入，使過去的解法在後續任務中持續可用。

2. 設定 HUD focused preset。執行 /oh-my-claudecode:hud setup 後，在 ~/.claude/settings.json 加入 "omcHud": { "preset": "focused" }。狀態列即時顯示目前 agent、階段、token 用量，長時間執行時可隨時掌握進度。

3. 跨 CLI 並行以 /ccg 取代手動切換。需要 codex 架構審查與 gemini UX 視角時，使用 /ccg "review this PR"，OMC 自動向兩端查詢後由 Claude 統合結果，比手動切換視窗更為可靠。

4. 搭配 oh-my-codex 使用。同作者另有姊妹專案 oh-my-codex，將相同編排體驗移植至 OpenAI Codex CLI，供偏好 codex 的團隊成員使用。

5. 加入官方 Discord 追蹤更新。OMC v4.x 系列已多次重大改版，官方 Discord 通常比 issue tracker 早 1–2 個 patch 提供 workaround。

建議參考的三份延伸文件

① 官方文件站：CLI Reference、Workflows、Execution Modes 的完整目錄。
② docs/REFERENCE.md：所有 flag 與 plugin-dir 模式的決策矩陣。
③ CHANGELOG.md：v4.4 移除 MCP、v4.1 棄用 swarm 等破壞性變更的完整記錄。

Your Claude Just Have been Steroided.
你的 Claude,被打了類固醇。
— oh-my-claudecode README 主視覺標語