oh-my-claudecode 教學手冊(完整版)

版本:v4.13.5(2026-04-28)
文件更新日期:2026-05-02
適用對象:資深工程師、架構師、技術主管
定位:企業級 Multi-Agent 編排實戰手冊
授權:MIT License
官方網站https://oh-my-claudecode.dev


目錄


1. 概述

1.1 什麼是 oh-my-claudecode

oh-my-claudecode(簡稱 OMC)是一個開源的 Multi-Agent 編排框架,專為 Claude Code CLI 打造。它讓 Claude Code 從「單一 Agent 對話工具」升級為「Teams-first 多智能體協作平台」。

核心理念:Don’t learn Claude Code. Just use OMC.

OMC 由韓國開發者 Yeachan Heo(@Yeachan-Heo)創建,目前在 GitHub 上擁有超過 32,000 顆星,106 位貢獻者,已發佈超過 223 個版本。npm 套件名稱為 oh-my-claude-sisyphus

核心能力一覽

能力說明
Zero Configuration智能預設值,開箱即用
Team-first OrchestrationTeam 是標準的多 Agent 編排表面
自然語言介面無需記憶指令,描述需求即可
自動平行化複雜任務自動分配給專門 Agent
持久執行模式不完成不放棄(Ralph 模式)
成本最佳化智能模型路由,節省 30-50% Token
經驗學習自動提取並重用問題解決模式(Skills)
即時可視化HUD 狀態列顯示運作狀態

1.2 與傳統 Claude Code 的差異

面向傳統 Claude Codeoh-my-claudecode
Agent 委派手動指定根據任務自動委派
關鍵字偵測ultrawork、search、ralph 等魔術關鍵字
Todo 延續基礎強制完成驗證
模型路由預設模型智能分層選擇(Haiku/Sonnet/Opus)
技能組合自動組合多層技能
平行執行單一 Agent多 Agent 同步執行
狀態持久化.omc/ 目錄結構完整保存
成本追蹤內建 Token 分析與成本報告

1.3 與 GitHub Copilot 的整合方式

OMC 與 GitHub Copilot 可以在同一開發環境中共存,各司其職:

  • GitHub Copilot:IDE 層級的即時程式碼補完、inline chat、PR review
  • OMC / Claude Code:CLI 層級的多 Agent 編排、架構設計、大範圍重構、自動化流程

協作模式建議

┌─────────────────────────────────────────────────────────────┐
│  開發者工作流                                                  │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  [VS Code IDE]                    [Terminal / CLI]           │
│   ├── GitHub Copilot              ├── Claude Code + OMC      │
│   │   ├── 程式碼補完              │   ├── 架構規劃(ralplan)  │
│   │   ├── Inline Chat             │   ├── 多檔重構(ultrawork)│
│   │   └── PR Review               │   ├── 自動開發(autopilot)│
│   │                               │   ├── 安全審查            │
│   └── Agent Mode                  │   └── 持久執行(ralph)    │
│       └── 複雜任務 → 也可呼叫 OMC │                           │
└─────────────────────────────────────────────────────────────┘

1.4 適用場景

場景推薦模式說明
企業大型系統開發Team + Ralph多 Agent 協作、持久驗證
個人專案快速開發Autopilot端對端自動完成
舊系統逆向工程Deep Interview + Ultrawork需求釐清 → 平行分析
Framework 升級Ralplan + Team規劃 → 執行 → 驗證迴圈
安全審查Security Review Agent專門的安全檢查
程式碼重構Ultrawork最大平行度

實務建議:企業環境建議以 Team Mode 為主要編排模式,搭配 OMC_SECURITY=strict 確保安全合規。


2. 整體架構設計(Architecture)

2.1 Multi-Agent 架構圖

OMC 建立在四個互鎖系統之上:

graph TB
    subgraph "oh-my-claudecode 架構"
        UI[使用者輸入] --> HK[Hooks 系統
生命週期事件偵測] HK --> SK[Skills 系統
行為注入] SK --> AG[Agent 系統
專門任務執行] AG --> ST[State 系統
進度追蹤與持久化] ST --> UI end subgraph "Hooks 生命週期(11 事件)" H1[UserPromptSubmit] H2[SessionStart] H3[PreToolUse] H3b[PermissionRequest] H4[PostToolUse] H4b[PostToolUseFailure] H5a[SubagentStart] H5b[SubagentStop] H6[PreCompact] H7[Stop] H8[SessionEnd] end subgraph "Agent 分類" A1[Build/Analysis Lane] A2[Review Lane] A3[Domain Lane] A4[Coordination Lane] end HK --> H1 & H2 & H3 & H3b & H4 & H4b & H5a & H5b & H6 & H7 & H8 AG --> A1 & A2 & A3 & A4

四大系統運作流程

User Input --> Hooks (事件偵測) --> Skills (行為注入)
           --> Agents (任務執行) --> State (進度追蹤)

Hooks 系統事件詳細對照

OMC 註冊了 20 個 Hook 腳本,橫跨 11 個 Claude Code 生命週期事件

事件Hook 腳本逾時
UserPromptSubmitkeyword-detector.mjs, skill-injector.mjs5s, 3s
SessionStartsession-start.mjs, project-memory-session.mjs, setup-init.mjs, setup-maintenance.mjs5s, 5s, 30s, 60s
PreToolUsepre-tool-enforcer.mjs3s
PermissionRequestpermission-handler.mjs(僅 Bash)5s
PostToolUsepost-tool-verifier.mjs, project-memory-posttool.mjs3s, 3s
PostToolUseFailurepost-tool-use-failure.mjs3s
SubagentStartsubagent-tracker.mjs(start)3s
SubagentStopsubagent-tracker.mjs(stop), verify-deliverables.mjs5s, 5s
PreCompactpre-compact.mjs, project-memory-precompact.mjs10s, 5s
Stopcontext-guard-stop.mjs, persistent-mode.cjs, code-simplifier.mjs5s, 10s, 5s
SessionEndsession-end.mjs30s

注意:autopilot、ralph、ultrawork、ultraqa 是 Skills(透過 keyword-detector 啟動),不是 Hooks。persistent-mode.cjs Hook 透過阻擋 Stop 事件來強制它們繼續執行。

2.2 Agent 分工(29 個 Agent)

OMC 提供 29 個專門 Agent(含分層變體),分為四大通道:

Build/Analysis Lane(建構與分析通道)

Agent模型層級職責
explore / explore-highhaiku / opus程式碼探索、檔案與符號映射
analystopus需求分析、隱含約束發現
planneropus任務排序、執行計畫制定
architect / architect-low / architect-mediumopus / haiku / sonnet系統設計、介面定義、取捨分析
debuggersonnet根因分析、建構錯誤修復
executor / executor-low / executor-highsonnet / haiku / opus程式碼實作、重構
tracersonnet證據驅動因果追蹤

Review Lane(審查通道)

Agent模型層級職責
security-reviewer / security-reviewer-lowsonnet / haiku安全漏洞、信任邊界、認證授權審查
code-revieweropus完整程式碼審查、API 合約、向後相容性

Domain Lane(領域專家通道)

Agent模型層級職責
test-engineersonnet測試策略、覆蓋率、不穩定測試加固
designer / designer-low / designer-highsonnet / haiku / opusUI/UX 架構、互動設計
writerhaiku文件、遷移備註
qa-testersonnet互動式 CLI/服務運行時驗證
scientist / scientist-highsonnet / opus資料分析、統計研究
git-mastersonnetGit 操作、提交、rebase、歷史管理
document-specialistsonnet外部文件、API/SDK 參考查詢
code-simplifieropus程式碼簡化、可讀性、可維護性提升

Coordination Lane(協調通道)

Agent模型層級職責
criticopus計畫與設計的缺口分析、多角度審查

2.3 任務分解機制(Task Decomposition)

OMC 的任務分解採用分層管線設計

┌────────────────────────────────────────────────────────────────────┐
│                    Team Mode 五階段管線                              │
│                                                                      │
│  team-plan → team-prd → team-exec → team-verify → team-fix (loop) │
│                                                                      │
│  規劃階段     需求文件     執行階段     驗證階段      修復迴圈       │
└────────────────────────────────────────────────────────────────────┘

典型 Agent 工作流

explore --> analyst --> planner --> critic --> executor --> verifier
(探索)     (分析)     (排序)     (審查)     (實作)     (確認)

委派決策原則

  • 委派給 Agent 的情境:多檔案變更、重構需求、除錯或根因分析、程式碼或安全審查、規劃或研究
  • 直接處理的情境:簡單檔案查詢、直接問答、單一指令操作

2.4 Agent 角色邊界

各 Agent 有明確的職責範圍,避免角色混淆:

Agent核心職責不應涉及
architect程式碼分析、除錯、驗證需求收集、規劃
analyst發現需求缺口程式碼分析、規劃
planner建立任務計畫需求分析、計畫審查
critic審查計畫品質需求分析、程式碼分析

2.5 驗證協定(Verification Protocol)

驗證模組確保工作完成並附帶證據:

檢查項目說明
BUILD編譯通過
TEST所有測試通過
LINT無 Linting 錯誤
FUNCTIONALITY功能如預期運作
ARCHITECTOpus 層級審查通過
TODO所有任務已完成
ERROR_FREE無未解決的錯誤

重要:證據必須是新鮮的(5 分鐘內),並包含實際命令輸出。

2.6 Agent 通訊機制

Agent 之間透過 Task Tool 進行委派,並使用模型路由:

// Agent 委派範例
Task(
  subagent_type = "oh-my-claudecode:executor",
  model = "sonnet",
  prompt = "Implement feature..."
)

模型路由策略(三層級):

層級模型特性成本
LOWhaiku快速、低成本
MEDIUMsonnet均衡性能與成本
HIGHopus最高品質推理

預設模型分配

  • Haiku:快速查詢(explore、writer)
  • Sonnet:程式碼實作、除錯、測試(executor、debugger、test-engineer)
  • Opus:架構設計、策略分析、審查(architect、planner、critic、code-reviewer)

2.7 狀態管理架構:Control Plane vs Data Plane

OMC 將編排中繼資料與大型持久 artifacts 分離:

層面內容儲存路徑
Control Plane佇列狀態、worker 指派、session 狀態、跨工具任務/訊息信封.omc/state/**
Data Plane計畫、規格書、prompts、結果、traces 等持久 artifacts.omc/plans/.omc/notepads/.omc/prompts/

Artifact Descriptors(有界交接)

當交接需要參照大型 artifact 時,使用 descriptor/handle 而非內嵌全部 payload:

欄位說明
kindArtifact 類型(plan、prompt、result、trace 等)
path持久 artifact 路徑
contentHash?可選的完整性 hash
createdAt建立時間戳記
producer擁有者(worker/tool/skill)
sizeBytes?可選的大小(用於門檻判斷)
retention保留/所有權提示
expiresAt?可選的過期時間

有界交接原則

  1. 當呼叫端的閾值允許時,保持小 payload inline
  2. 大 payload 時,傳送簡短摘要加 descriptor
  3. 將持久內容保存在 artifact 路徑,而非嵌入佇列或狀態記錄

2.8 與外部系統整合

CI/CD 整合

# GitHub Actions 整合範例
name: OMC Agent Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Claude Code
        run: |
          # 安裝 Claude Code CLI 並透過 plugin 方式安裝 OMC
          claude plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
          claude plugin install oh-my-claudecode
      - name: Run Security Review
        run: |
          omc ask claude --agent-prompt security-reviewer \
            --prompt "review the changes in this PR for security issues"

GitHub Issue / PR Flow

OMC 可透過 /ask 指令搭配不同 Agent 來處理 PR 審查:

# PR 架構審查(透過 Codex)
omc ask codex "review this PR for architecture risks"

# PR 安全審查(透過 Claude)
omc ask claude --agent-prompt security-reviewer --prompt "review auth changes"

# PR UI 審查(透過 Gemini)
omc ask gemini --prompt "review UI component accessibility"

通知整合(Telegram / Discord / Slack)

# 設定 Discord 通知
omc config-stop-callback discord --enable \
  --webhook <webhook_url> \
  --tag-list "@here,123456789012345678"

# 設定 Telegram 通知
omc config-stop-callback telegram --enable \
  --token <bot_token> \
  --chat <chat_id> \
  --tag-list "@alice,bob"

# 設定 Slack 通知
omc config-stop-callback slack --enable \
  --webhook <webhook_url> \
  --tag-list "<!here>,<@U1234567890>"

實務建議:企業部署時,建議整合 Discord 或 Slack 通知,讓團隊成員即時掌握 Agent 執行狀態。


3. 安裝與環境建置(Step-by-step)

3.1 前置需求

項目需求備註
Claude Code CLI必要官方安裝指引
Claude 訂閱必要Max/Pro 訂閱或 Anthropic API Key
Node.js建議 v18+用於 npm 安裝與 Hook 執行
tmux / psmux建議Team 模式與速率限制偵測所需

3.2 安裝 oh-my-claudecode

Claude Code Plugin(唯一支援方式)

⚠️ 重要變更:自最新版起,僅支援 Claude Code Plugin 安裝方式。其他安裝方式(npm、bun、curl)已棄用,可能無法正常運作。

在 Claude Code 會話中依序執行:

# Step 1:新增 marketplace
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# Step 2:安裝 plugin
/plugin install oh-my-claudecode

注意:這是 Claude Code 斜線指令,需在 Claude Code 會話中逐行輸入,不可同時貼上兩行。Plugin 系統會自動處理所有安裝和 Hook 設定。

本地開發 Checkout(進階用途)

若需使用本地 clone 進行開發或除錯,可使用 --plugin-dir 方式:

# 使用 omc shim 啟動(推薦)
omc --plugin-dir /path/to/oh-my-claudecode

# 搭配 setup 啟用 dev 模式
omc setup --plugin-dir-mode

此方式直接從 checkout 路徑載入 agents/skills,無需透過 plugin cache,編輯後下次 session 即生效。

npm 安裝(已棄用)

# ⚠️ 已棄用 — 不建議使用
npm i -g oh-my-claude-sisyphus@latest

套件命名說明:專案品牌名為 oh-my-claudecode,但 npm 套件發佈為 oh-my-claude-sisyphus。此方式已不再被官方支援,請改用 Plugin 方式。

3.3 初始設定(Setup)

# 在 Claude Code 會話中
/setup
# 或
/omc-setup

# 從終端機
omc setup

專案層級設定(推薦)

/oh-my-claudecode:omc-setup --local
  • 在目前專案建立 ./.claude/CLAUDE.md
  • 設定僅影響此專案
  • 不影響其他專案或全域設定

全域設定

/oh-my-claudecode:omc-setup
  • 建立 ~/.claude/CLAUDE.md
  • 設定套用到所有專案

3.4 tmux / psmux 安裝(各平台)

平台套件安裝指令
macOStmuxbrew install tmux
Ubuntu/Debiantmuxsudo apt install tmux
Fedoratmuxsudo dnf install tmux
Archtmuxsudo pacman -S tmux
Windows(原生)psmuxwinget install psmux
Windows(WSL2)tmuxsudo apt install tmux(WSL 內)

Windows 使用者注意:原生 Windows(win32)支援為實驗性。OMC 需要 tmux,但原生 Windows 不提供。強烈建議 Windows 使用者使用 WSL2。參見 WSL2 安裝指南。原生 Windows 問題可能僅獲得有限支援。

psmux 提供原生 Windows 的 tmux 相容指令(76 個指令),但請注意實驗性限制。

進階選項:在 macOS/Linux 上,設定 OMC_USE_NODE_HOOKS=1 可改用 Node.js Hooks(預設為 Bash)。

3.5 可選:多 AI 模型支援

工具安裝指令用途
Gemini CLInpm install -g @google/gemini-cli設計審查、UI 一致性(100 萬 Token 上下文)
Codex CLInpm install -g @openai/codex架構驗證、程式碼審查交叉檢查

成本估算:3 個 Pro 方案(Claude + Gemini + ChatGPT)每月約 $60 美元。

3.6 啟用 Claude Code Native Teams

~/.claude/settings.json 中加入:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

注意:若未啟用 Teams,OMC 會發出警告並在可能時回退到非 Team 執行模式。

3.7 驗證安裝

# 在 Claude Code 會話中執行診斷
/oh-my-claudecode:omc-doctor

# 若使用本地 checkout,可指定 plugin 路徑
omc doctor --plugin-dir /path/to/oh-my-claudecode

# 也支援 conflicts 子命令
omc doctor conflicts --plugin-dir /path/to/oh-my-claudecode

檢查項目包括:

  • 缺少的依賴
  • 設定錯誤
  • Hook 安裝狀態
  • Agent 可用性
  • Skill 註冊

實務建議:首次安裝完成後務必執行 /omc-doctor,確認所有元件正確安裝。


4. 核心設定(Configuration)

4.1 設定檔結構與優先順序

./.claude/CLAUDE.md  (專案)  →  覆蓋  →  ~/.claude/CLAUDE.md  (全域)

專案層級設定檔案

檔案路徑用途
CLAUDE.md./.claude/CLAUDE.md專案特定指令與規則
omc.jsonc.claude/omc.jsoncOMC 專案設定
config.jsonc~/.config/claude-omc/config.jsonc使用者層級設定
config.json${XDG_CONFIG_HOME:-~/.config}/omc/config.json全域 OMC 設定(Code Simplifier 等)
settings.json~/.claude/settings.jsonClaude Code 全域設定

注意:舊版 ~/.omc/config.json 路徑仍作為 fallback 讀取,但建議遷移到 XDG 標準路徑。

4.2 環境變數

變數預設說明
OMC_STATE_DIR(未設定)集中式狀態目錄。設定後 OMC 在 $OMC_STATE_DIR/{project-id}/ 儲存狀態
OMC_PARALLEL_EXECUTIONtrue啟用/停用平行 Agent 執行
OMC_CODEX_DEFAULT_MODEL(provider 預設)Codex CLI worker 預設模型
OMC_GEMINI_DEFAULT_MODEL(provider 預設)Gemini CLI worker 預設模型
OMC_LSP_TIMEOUT_MS15000LSP 請求逾時(毫秒),大型 repo 或慢速語言伺服器建議增加
OMC_PLUGIN_ROOT(自動偵測)Plugin 根目錄路徑,omc --plugin-dir 自動設定
OMC_BRIDGE_SCRIPT(自動偵測)Python bridge 腳本路徑
DISABLE_OMC(未設定)設定任意值以停用所有 Hook
OMC_SKIP_HOOKS(未設定)逗號分隔的 Hook 名稱跳過清單
OMC_SECURITY(未設定)設為 strict 啟用全部安全功能
OMC_USE_NODE_HOOKS(未設定)設為 1 在 macOS/Linux 上使用 Node.js Hooks

4.3 Agent 設定(自訂 / 修改)

Agent 檔案位於 ~/.claude/agents/,格式如下:

---
name: architect
description: Your custom description
tools: Read, Grep, Glob, Bash, Edit
model: opus  # 或 sonnet, haiku
# effort: high(可選,預設繼承父 session)
---
Your custom system prompt here...

注意:內建 OMC Agent 不含 effort: frontmatter 欄位。Agent markdown 中的 effort 語言是 prompt 行為引導,運行時 effort 繼承自父 Claude Code session,除非明確宣告覆蓋。

4.4 模型路由策略(Cost Optimization)

OMC 的智能模型路由根據任務複雜度自動選擇模型:

┌──────────────────────────────────────────────────────────┐
│              模型路由決策樹                                 │
├──────────────────────────────────────────────────────────┤
│                                                            │
│  任務類型判斷                                               │
│  ├── 簡單查詢/文件撰寫 → Haiku(低成本)                    │
│  ├── 程式碼實作/除錯/測試 → Sonnet(平衡)                  │
│  └── 架構設計/策略分析/審查 → Opus(高品質)                │
│                                                            │
│  實際節省:30-50% Token 費用                                │
└──────────────────────────────────────────────────────────┘

4.5 Company Context via MCP

OMC 支援透過 MCP 表面提供企業上下文的契約:

// .claude/omc.jsonc(專案)或 ~/.config/claude-omc/config.jsonc(使用者)
{
  "companyContext": {
    "tool": "mcp__vendor__get_company_context",
    "onError": "warn"
  }
}
欄位說明
tool要呼叫的完整 MCP 工具名稱
onErrorprompt 層級備援行為:warnsilentfail

MCP 伺服器本身仍透過正常的 Claude/OMC MCP 設定路徑註冊。詳見 company-context-interface.md

4.6 Remote OMC / Remote MCP Access

OMC 支援透過統一 MCP 註冊表連接到遠端 MCP 伺服器:

{
  "mcpServers": {
    "remoteOmc": {
      "url": "https://lab.example.com/mcp",
      "timeout": 30
    }
  }
}

支援範圍

  • ✅ 連接遠端 MCP 伺服器(透過統一 MCP registry)
  • ❌ 不支援通用「OMC 叢集」、共享遠端檔案系統、或自動遠端聯邦
  • 💡 完整遠端 shell 工作流仍建議使用 SSH、worktree 或掛載的網路檔案系統

4.7 Plugin 目錄旗標(Decision Matrix)

使用本地開發 checkout 而非 marketplace plugin 時的配置選擇:

場景啟動方式Setup 方式行為
Marketplace plugin(推薦)omcclaude(預設)omc setup正常:agents/skills 複製到 ~/.claude/
本地 checkout + OMC shimomc --plugin-dir /pathomc setup --plugin-dir-modeDev 模式:從 /path 載入
本地 checkout + 無 shimclaude --plugin-dir /path + export OMC_PLUGIN_ROOT=/pathomc setup --plugin-dir-modeDev 模式 + 手動 env
本地 checkout + 需 bundled skillsomc --plugin-dir /pathomc setup --no-plugin強制使用 ~/.claude/skills/
診斷特定路徑N/Aomc doctor --plugin-dir /path對指定路徑執行診斷

4.8 Skills 設定

Skills 分為兩個層級:

層級路徑分享範圍優先級
專案層級.omc/skills/團隊(commit 後跨 worktree 共享)較高(覆蓋使用者層級)
使用者層級~/.omc/skills/所有專案較低(備用)

Skills 2.0 相容性

OMC 的 Skill 目錄除了 .omc/skills/ 外,也讀取 .agents/skills/ 的相容性 Skills。對於內建和斜線載入的 Skills,OMC 還會在 skill 目錄包含 bundled assets(helper scripts、templates 等)時,附加標準化的 Skill Resources 區段。

Skill 檔案格式:

---
name: Fix Proxy Crash
description: aiohttp proxy crashes on ClientDisconnectedError
triggers: ["proxy", "aiohttp", "disconnected"]
source: extracted
---
Wrap handler at server.py:42 in try/except ClientDisconnectedError...

4.9 任務模板設定

OMC 的 Skill Pipeline 支援 frontmatter 宣告管線流程:

pipeline: [deep-interview, omc-plan, autopilot]
next-skill: omc-plan
next-skill-args: --consensus --direct
handoff: .omc/specs/deep-interview-{slug}.md

實務建議:建議團隊統一使用專案層級設定(--local),避免全域設定影響其他專案。將 .claude/CLAUDE.md.omc/skills/ 納入版本控制。

4.10 何時需要重新執行 Setup

場景動作
首次安裝執行 setup(選擇專案或全域)
更新後重新執行以取得最新設定
不同機器在每台使用 Claude Code 的機器上執行
新專案執行 /oh-my-claudecode:omc-setup --local

⚠️ 重要:更新 plugin(透過 npm updategit pull 或 Claude Code 的 plugin update)後,必須重新執行 /oh-my-claudecode:omc-setup 以套用最新的 CLAUDE.md 變更。


5. 使用方式(實戰)

5.1 基本使用

CLI 操作流程

OMC 提供兩種操作表面:

表面說明範例
Terminal CLI 指令在 shell 中執行 omc ...omc team 2:codex "review code"
In-session Skills在 Claude Code 會話中執行 /.../team 3:executor "fix errors"
# 快速開始 — 在 Claude Code 會話中
/autopilot "build a REST API for managing tasks"

# 自然語言方式(無需斜線指令)
autopilot: build a REST API for managing tasks

單 Agent vs 多 Agent

模式指令場景
Autopilot(單 Agent)/autopilot "任務描述"端對端功能開發
Team(多 Agent,推薦)/team 3:executor "任務描述"協調多 Agent 共同工作
Ultrawork(多 Agent)/ultrawork "任務描述"最大平行度的爆發式修復
Ralph(持久模式)/ralph "任務描述"必須完全完成的任務

編排模式總覽

模式管線適用場景
Team(推薦)team-plan → team-prd → team-exec → team-verify → team-fix協調多 Agent 共享任務清單
omc team (CLI)tmux CLI workersCodex/Gemini CLI 任務,按需生成
ccg/ask codex + /ask gemini → Claude 合成混合後端+UI 工作
Autopilot自主執行(單一主 Agent)端對端功能開發
Ultrawork最大平行度(非 Team)爆發式平行修復/重構
Ralph持久模式+驗證/修復迴圈必須完全完成的任務
Pipeline順序分階段處理嚴格排序的多步驟轉換

Ralph 進階參數

Ralph 支援 --critic 旗標指定持久迴圈中使用的批評者 Agent:

# 預設使用 critic agent 做驗證
/ralph "implement user authentication"

# 指定 architect 作為批評者(適合架構級任務)
/ralph --critic=architect "refactor the entire data access layer"
參數說明
--critic=<agent>指定驗證迴圈中的批評者 Agent(預設:critic

提示--critic=architect 適合需要架構層面驗證的大型重構任務,確保修改符合整體架構設計。

Ralplan 進階參數

Ralplan 支援 --deliberate 旗標啟用高風險深思模式:

# 標準共識規劃
/ralplan "design the new microservice architecture"

# 深思模式(高風險決策)
/ralplan --deliberate "plan database migration from Oracle to PostgreSQL"
參數說明
--deliberate啟用高風險深思模式,增加額外的風險評估與替代方案分析階段

適用場景:不可逆的基礎設施變更、跨服務資料遷移、安全架構重新設計。

不確定從何開始?使用 Deep Interview

/deep-interview "I want to build a task management app"

Deep Interview 使用蘇格拉底式提問來釐清需求,在任何程式碼撰寫之前揭露隱含假設。

Deep-Dive(兩階段深度分析)

Deep-Dive 是一個兩階段的追蹤分析管線:trace → deep-interview,帶有上下文交接。適合對複雜問題進行深度調查:

# 啟動 deep-dive 追蹤
/deep-dive "why does the payment service timeout under load?"

第一階段(trace)會廣泛搜尋相關程式碼路徑與依賴關係,第二階段(deep-interview)則基於追蹤結果進行深入的互動式分析。

Autoresearch(狀態性研究迴圈)

/oh-my-claudecode:autoresearch "investigate performance bottleneck in the API"

Autoresearch 是一個狀態性單一任務評估驅動改進迴圈。它持續研究直到評估器認為目標已達成。

注意omc autoresearch CLI 指令已硬棄用為 shim,請改用 in-session skill。

5.2 Web Application 開發(重點)

前端(Vue / React)生成

# 使用 Autopilot 全流程生成 React 前端
/autopilot "build a React dashboard with:
- user authentication (OAuth2)
- role-based access control
- real-time notifications
- responsive design with Tailwind CSS"

# 使用 Designer Agent 處理 UI/UX
/team 2:executor "implement the frontend components"

後端(Spring Boot / FastAPI)

# 使用 Team 模式開發 Spring Boot 後端
/team 3:executor "build a Spring Boot 3.x REST API with:
- Clean Architecture (domain/application/infrastructure layers)
- JPA entities for User, Role, Permission
- JWT authentication filter
- Global exception handler
- OpenAPI documentation"

API 設計

# 使用 Architect Agent 進行 API 設計
/ralplan "design RESTful API for an e-commerce system with:
- product catalog CRUD
- shopping cart management
- order processing workflow
- payment integration interface"

DB Schema 設計

# 使用 Analyst + Architect 協作
/deep-interview "I need a database schema for a multi-tenant SaaS platform"
# 釐清需求後
/autopilot "implement the database schema with Flyway migrations"

5.3 逆向工程(Legacy System)

讀取舊系統程式碼

# Step 1:使用 Deep Interview 理解系統
/deep-interview "I need to reverse engineer a 10-year-old Java monolith
with no documentation. The system handles banking transactions."

# Step 2:使用 Explore Agent 探索程式碼
/ultrawork "analyze the codebase structure:
1. Map all packages and their dependencies
2. Identify entry points and main flows
3. Document all external integrations
4. List all database tables and relationships"

分析 Architecture

# 使用 Architect Agent 分析架構
/team 3:executor "reverse engineer this legacy system:
1. architect: analyze the overall architecture pattern
2. explore: map module dependencies
3. document-specialist: generate architecture documentation"

自動產出文件

# 使用 Deepinit 生成階層式文件
/oh-my-claudecode:deepinit

# 使用 Writer Agent 產生詳細文件
/autopilot "generate comprehensive documentation for this codebase:
- System overview and architecture
- Module-by-module descriptions
- API endpoint documentation
- Database schema documentation
- Deployment guide"

重構建議

# 使用 Architect + Critic 協作規劃重構
/ralplan "plan the modernization of this legacy system:
- Identify technical debt hot spots
- Propose microservice boundaries
- Design migration strategy (strangler fig pattern)
- Estimate effort for each phase"

5.4 Framework 升級

Spring Boot 升級

# Step 1:使用 Analyst 分析影響
/deep-interview "upgrade Spring Boot from 2.7 to 3.2:
- Current dependencies and their compatibility
- Breaking changes analysis
- Migration path"

# Step 2:使用 Team 執行升級
/team 3:executor "execute Spring Boot upgrade:
1. Update pom.xml / build.gradle dependencies
2. Fix javax → jakarta namespace migration
3. Update deprecated APIs
4. Run and fix all tests
5. Verify application startup"

前端框架升級

# Vue 2 → Vue 3 升級
/ralph "upgrade Vue 2 to Vue 3:
1. Analyze all components for breaking changes
2. Update Options API to Composition API where beneficial
3. Migrate Vuex to Pinia
4. Update Vue Router configuration
5. Fix template syntax changes
6. Run all tests"

依賴分析

# 使用 CCG 進行多角度依賴分析
/ccg "analyze all project dependencies:
- Codex: identify security vulnerabilities and outdated packages
- Gemini: suggest alternative libraries for deprecated ones
- Claude: create a prioritized upgrade plan"

實務建議:Framework 升級建議使用 Ralph 模式確保所有步驟完整執行,並搭配 team-verify 階段進行自動驗證。


6. Multi-Agent 協作設計(進階)

6.1 Agent Roles 設計模式

OMC 的 Skills 系統採用三層堆疊設計:

┌──────────────────────────────────────────────────────────┐
│  保證層(Guarantee Layer)— 可選                           │
│  ralph: "在驗證完成前不可停止"                              │
└──────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────┐
│  增強層(Enhancement Layer)— 0~N 個技能                   │
│  ultrawork (平行) | git-master (提交) | frontend-ui-ux    │
└──────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────┐
│  執行層(Execution Layer)— 主要技能                       │
│  default (建構) | orchestrate (協調) | planner (規劃)     │
└──────────────────────────────────────────────────────────┘

組合公式[執行技能] + [0-N 增強] + [可選保證]

# 範例:ultrawork + default + git-master
ultrawork: refactor API with proper commits
# 啟用技能:ultrawork(平行執行)+ default(建構)+ git-master(原子提交)

6.2 Planner → Executor → Reviewer Flow

graph LR
    A[Analyst
需求分析] --> B[Planner
任務規劃] B --> C[Critic
計畫審查] C -->|通過| D[Executor
程式碼實作] C -->|未通過| B D --> E[Verifier
完成驗證] E -->|通過| F[完成] E -->|未通過| D

Team Mode 五階段管線

# 啟動 Team 模式
/team 3:executor "implement fullstack todo app"

# 管線自動執行:
# 1. team-plan:規劃任務
# 2. team-prd:產生需求文件
# 3. team-exec:執行實作
# 4. team-verify:驗證完成
# 5. team-fix:修復問題(迴圈)

6.3 tmux CLI Workers(多模型協作)

自 v4.4.0 起,OMC 使用 CLI-first Team runtime 生成 tmux worker 窗格:

# 生成 Codex workers 進行安全審查
omc team 2:codex "review auth module for security issues"

# 生成 Gemini workers 進行 UI 設計
omc team 2:gemini "redesign UI components for accessibility"

# 生成 Claude workers 實作功能
omc team 1:claude "implement the payment flow"

# 檢查 Team 狀態
omc team status auth-review

# 關閉 Team
omc team shutdown auth-review

# 透過 API 領取任務(進階)
omc team api claim-task --input '{"team_name":"auth-review","task_id":"1","worker":"worker-1"}' --json

Native Team Worktree Mode(opt-in)

原生 Team Worktree 模式是 opt-in/config-gated 的 runtime-v2 功能。詳見 TEAM-WORKTREE-MODE.md

功能包括:

  • Worktree 路徑契約
  • Canonical OMC_TEAM_STATE_ROOT 行為
  • 狀態欄位
  • Dirty-worktree 清理策略

Topology 行為

環境行為
經典 tmux 內($TMUX 已設定)重用目前 tmux 表面(split-pane 或 --new-window
cmux 內(CMUX_SURFACE_ID 且無 $TMUX啟動 detached tmux session
一般 terminal啟動 detached tmux session

三模型顧問模式(CCG)

# 混合 Codex + Gemini + Claude 分析
/ccg Review this PR — architecture (Codex) and UI components (Gemini)
指令用途適用場景
omc team N:codex "..."N 個 Codex CLI 窗格程式碼審查、安全分析、架構
omc team N:gemini "..."N 個 Gemini CLI 窗格UI/UX 設計、文件、大上下文任務
omc team N:claude "..."N 個 Claude CLI 窗格通用任務
/ccg/ask codex + /ask gemini三模型顧問合成

6.4 Code Review Agent

# 全面程式碼審查
/oh-my-claudecode:ask claude --agent-prompt code-reviewer \
  "review the changes in src/auth/ for:
  - code quality and maintainability
  - API contract backward compatibility
  - error handling completeness
  - test coverage adequacy"

6.5 Security Agent(SSDLC)

# 安全審查
/oh-my-claudecode:ask claude --agent-prompt security-reviewer \
  "review this codebase for:
  - OWASP Top 10 vulnerabilities
  - authentication/authorization issues
  - input validation gaps
  - sensitive data exposure
  - dependency vulnerabilities"

# 快速安全掃描(使用 haiku 降低成本)
/oh-my-claudecode:ask claude --agent-prompt security-reviewer-low \
  "quick security scan of the auth module"

實務建議:建議在 PR 審查流程中加入 code-reviewer + security-reviewer 的自動化審查。使用 omc ask 指令將審查結果存為 artifact,方便追蹤。


7. Skills Learning 系統

7.1 Skills 總覽

OMC 提供 35 個 Skills(34 個正式 + 1 個已棄用別名 psm)。Runtime 真實來源來自內建 Skill loader 掃描 skills/*/SKILL.md 並展開 frontmatter 中宣告的別名。

完整 Skills 清單

Skill說明呼叫方式
ai-slop-cleanerAnti-slop 清理工作流(--review 僅審查模式)/oh-my-claudecode:ai-slop-cleaner
ask透過本地 CLI 詢問 Claude/Codex/Gemini 並擷取 artifact/oh-my-claudecode:ask
autoresearch狀態性單一任務評估驅動改進迴圈/oh-my-claudecode:autoresearch
autopilot從構想到可運作程式碼的全自主執行/oh-my-claudecode:autopilot
cancel統一取消活動模式/oh-my-claudecode:cancel
ccg三模型工作流:ask codex + ask gemini → Claude 合成/oh-my-claudecode:ccg
configure-notifications透過自然語言設定通知整合(Telegram/Discord/Slack)/oh-my-claudecode:configure-notifications
deep-dive兩階段 trace → deep-interview 管線(含上下文交接)/oh-my-claudecode:deep-dive
deep-interview蘇格拉底式深度訪談(含模糊度門控)/oh-my-claudecode:deep-interview
deepinit生成階層式 AGENTS.md 文件/oh-my-claudecode:deepinit
external-context平行 document-specialist 研究/oh-my-claudecode:external-context
hud設定 HUD/狀態列/oh-my-claudecode:hud
learner從 session 中提取可重用 skill/oh-my-claudecode:learner
mcp-setup設定 MCP 伺服器/oh-my-claudecode:mcp-setup
omc-doctor診斷並修復安裝問題/oh-my-claudecode:omc-doctor
omc-plan規劃工作流(/plan 安全別名)/oh-my-claudecode:omc-plan
omc-reference詳細 OMC agent/tools/team/commit 參考自動載入(僅參考)
omc-setup一次性設定精靈/oh-my-claudecode:omc-setup
omc-teams生成 claude/codex/gemini tmux workers 進行平行執行/oh-my-claudecode:omc-teams
project-session-manager管理隔離開發環境(git worktrees + tmux)/oh-my-claudecode:project-session-manager
psm已棄用,project-session-manager 的相容性別名/oh-my-claudecode:psm
ralph持久迴圈直到驗證完成/oh-my-claudecode:ralph
ralplan共識規劃(/omc-plan –consensus 的別名)/oh-my-claudecode:ralplan
release自動化發佈工作流/oh-my-claudecode:release
self-improve自主進化程式碼改進引擎(含錦標賽選擇)/oh-my-claudecode:self-improve
setup統一設定入口(install、diagnostics、MCP)/oh-my-claudecode:setup
sciomc平行 scientist 編排/oh-my-claudecode:sciomc
skill管理本地 skills(list/add/remove/search/edit)/oh-my-claudecode:skill
team協調多 Agent 工作流/oh-my-claudecode:team
trace證據驅動追蹤(含平行 tracer 假設)/oh-my-claudecode:trace
ultraqaQA 循環直到目標達成/oh-my-claudecode:ultraqa
ultrawork最大平行吞吐量模式/oh-my-claudecode:ultrawork
visual-verdict結構化視覺 QA 判定(截圖/參考比較)/oh-my-claudecode:visual-verdict
wikiLLM Wiki — 跨 session 累積的持久 Markdown 知識庫/oh-my-claudecode:wiki
writer-memory寫作專案的 Agent 記憶系統/oh-my-claudecode:writer-memory

重點 Skills 詳解

Self-Improve(自主進化引擎)

Self-Improve 使用錦標賽選擇(Tournament Selection)驅動程式碼品質迭代改進。產出的 artifact 按主題分類存放:

.omc/self-improve/topics/
├── performance/         # 效能最佳化主題
│   ├── v1.md           # 第一代改進
│   ├── v2.md           # 第二代改進(錦標賽勝出)
│   └── tournament.json # 評估記錄
├── security/
│   └── ...
└── readability/
    └── ...
# 針對特定主題啟動自主改進
/self-improve "optimize database query performance"
Visual-Verdict(視覺 QA 判定)

Visual-Verdict 透過截圖比較生成結構化的視覺品質判定,適合前端 UI 驗收:

# 比較截圖與設計稿
/visual-verdict "compare current login page with design mockup"

輸出格式化的判定報告,包含:差異區域標記、嚴重度評分、修復建議。

Writer-Memory(寫作記憶系統)

Writer-Memory 為長篇寫作專案維護 Agent 級別的持久記憶(風格指南、術語表、章節大綱等),確保跨會話的寫作一致性。

# 初始化寫作專案記憶
/writer-memory "technical documentation for our API"

7.2 Skills 如何產生

OMC 支援兩種 Skill 產生方式:

手動建立

# 管理技能
/skill list              # 列出所有技能
/skill add               # 新增技能
/skill remove <name>     # 移除技能
/skill edit <name>       # 編輯技能
/skill search <query>    # 搜尋技能

自動學習(Learner)

# 使用 Learner 從會話中提取可重用模式
/learner

Learner 功能:

  • 從對話中自動提取問題解決模式
  • 使用嚴格品質門檻過濾低品質模式
  • 產生結構化的 Skill 檔案

7.3 Skills 儲存與重用

Skill 檔案結構

# .omc/skills/fix-proxy-crash.md
---
name: Fix Proxy Crash
description: aiohttp proxy crashes on ClientDisconnectedError
triggers: ["proxy", "aiohttp", "disconnected"]
source: extracted
---
Wrap handler at server.py:42 in try/except ClientDisconnectedError...

自動注入機制

  • 觸發匹配:當使用者輸入包含 triggers 中的關鍵字時,對應 Skill 自動載入到上下文
  • 無需手動呼叫:匹配的 Skills 自動注入,無需記憶或手動召喚

Skills 2.0 相容性

OMC 的 Skill 目錄除了 .omc/skills/ 外,也讀取 .agents/skills/ 的相容性 Skills。

7.4 建立企業內知識庫

知識庫架構建議

~/.omc/skills/                  # 全域(跨專案)
├── company-coding-standards.md  # 公司程式碼規範
├── security-patterns.md         # 安全模式
├── db-optimization.md           # 資料庫最佳化
└── ci-cd-patterns.md            # CI/CD 模式

.omc/skills/                     # 專案層級
├── project-architecture.md      # 專案架構模式
├── api-conventions.md           # API 設計慣例
├── test-patterns.md             # 測試模式
└── deployment-checklist.md      # 部署清單

知識庫建立步驟

  1. 識別共通模式:從團隊日常開發中提取反覆出現的解決方案
  2. 撰寫 Skill 檔案:使用標準格式記錄,包含觸發條件
  3. 團隊審查:透過 PR 審查 Skill 品質
  4. 版本控制:將專案層級 Skills 納入 Git 管理
  5. 定期更新:隨專案演進更新 Skills 內容

Wiki 系統(持久知識庫)

# 使用 Wiki skill 建立持久的 Markdown 知識庫
/oh-my-claudecode:wiki

Wiki 系統在會話間累積知識,形成專案的長期記憶。

實務建議:建議團隊定期(每月)進行 Skills 盤點,清理過時的 Skills,補充新發現的模式。使用 /learner 自動提取模式,再由資深工程師審查品質。


8. 效能與成本優化

8.1 Token 使用最佳化

模型分層策略

任務複雜度推薦模型Token 成本
快速程式碼查詢explore (haiku)最低
檔案搜尋explore (haiku)最低
文件撰寫writer (haiku)最低
功能實作executor (sonnet)中等
除錯debugger (sonnet)中等
架構設計architect (opus)最高
程式碼審查code-reviewer (opus)最高

Context 管理

  • 50% Context Rule:當上下文使用率達 50% 時執行 /compact
  • Notepad 持久化:重要資訊寫入 .omc/notepad.md,在壓縮後自動恢復
  • Remember Tags:使用 <remember> 標籤保留關鍵資訊
<!-- 保留 7 天 -->
<remember>API endpoint changed to /v2</remember>

<!-- 永久保留 -->
<remember priority>Never access production DB directly</remember>

8.2 模型選擇策略

Provider Advisor 功能

# 使用不同 Provider 進行交叉驗證
omc ask claude "review this migration plan"
omc ask codex --prompt "identify architecture risks"
omc ask gemini --prompt "propose UI polish ideas"

每次 Ask 的結果存為 artifact:.omc/artifacts/ask/{provider}-{slug}-{timestamp}.md

成本控制建議

策略說明預估節省
模型路由讓 OMC 自動選擇模型30-50%
任務拆解小任務用 haiku,大任務用 opus20-30%
Context 壓縮定期 /compact15-25%
Skills 重用避免重複解釋相同問題10-20%

8.3 平行處理設計

Ultrawork 平行模式

# 啟用最大平行度
/ultrawork "fix all TypeScript errors in the project"

Team 平行模式

# 3 個 Executor Agent 同時工作
/team 3:executor "implement all CRUD endpoints"

環境變數控制

# 啟用/停用平行執行
export OMC_PARALLEL_EXECUTION=true

8.4 HUD 監控與分析

# 設定 HUD 預設值
/oh-my-claudecode:hud setup

HUD 設定(~/.claude/settings.json):

{
  "omcHud": {
    "preset": "focused",
    "elements": {
      "cwd": true,
      "gitRepo": true,
      "gitBranch": true,
      "showTokens": true,
      "contextBar": true,
      "agents": true,
      "todos": true,
      "ralph": true,
      "autopilot": true
    }
  }
}

可用預設值:minimalfocusedfulldenseanalyticsopencode

HUD 版面配置選項

選項說明預設
maxWidth最大 HUD 行寬(terminal columns)未設定
wrapModetruncate(省略號)或 wrap(在 `` 邊界換行),需搭配 maxWidth

外部資源

實務建議:企業環境建議使用 analytics 預設值進行成本追蹤,並設定每月 Token 使用預算。定期檢查 .omc/sessions/*.json 分析使用模式。


9. SSDLC 整合(企業級重點)

9.1 安全設定(Security Mode)

快速啟用嚴格模式

export OMC_SECURITY=strict

嚴格模式啟用的安全功能:

功能說明
Tool Path RestrictionAST 工具限制在專案根目錄
Python REPL Sandbox阻擋危險模組和內建函式
Remote MCP Disable不啟動 Exa/Context7 外部 MCP 伺服器
External LLM DisableTeam 模式中阻擋 Codex/Gemini workers
Auto-Update Disable防止未驗證的版本安裝
Hard Max Iterations持久模式上限 200 次迭代

細粒度設定

.claude/omc.jsonc(專案層級)或 ~/.config/claude-omc/config.jsonc(使用者層級):

{
  "security": {
    "restrictToolPaths": true,
    "pythonSandbox": true,
    "disableRemoteMcp": true,
    "disableExternalLLM": true,
    "disableAutoUpdate": true,
    "hardMaxIterations": 200
  }
}

優先順序規則

  • 嚴格模式:設定檔只能加強安全性,不能放寬。布林值使用 ||(true 保持 true),hardMaxIterations 使用 Math.min(只會減少)
  • 非嚴格模式:設定檔可自由覆蓋預設值

安全功能詳解

Tool Path Restriction(restrictToolPaths

ast_grep_searchast_grep_replace 限制在專案根目錄中執行,防止讀取或修改專案外部的檔案。

Python REPL Sandbox(pythonSandbox

阻擋 Python REPL 中的危險模組和內建函式:

  • 阻擋模組ossubprocessshutilsocketctypesmultiprocessingwebbrowserhttp.serverxmlrpc.serverimportlibsysiopathlibsignal
  • 阻擋內建函式execevalcompile__import__openbreakpoint

注意sysiopathlib 被刻意阻擋,雖然會限制部分合法用途。這是縱深防禦的設計取捨。Python 層級的阻擋名單本身並非安全邊界;建議對不信任的程式碼使用 OS 層級程序隔離。

Remote MCP Disable(disableRemoteMcp

阻止 Exa(網路搜尋)和 Context7(外部文件)MCP 伺服器啟動。啟用時不會向外部伺服器發送任何查詢。

External LLM Disable(disableExternalLLM

阻止 Team 模式中生成 Codex(OpenAI)和 Gemini(Google)CLI workers。只允許 Claude workers。在 getContract() 層級的 team worker contract 系統中強制執行。

Hard Max Iterations(hardMaxIterations

限制持久模式(ralph、autopilot、ultrawork)的最大迭代次數。預設值:500(非嚴格模式)、200(嚴格模式)。防止失控迴圈。

9.2 Secure Coding

Security Review Agent 使用

# 全面安全審查
/oh-my-claudecode:ask claude --agent-prompt security-reviewer \
  "perform a comprehensive security review:
  1. OWASP Top 10 analysis
  2. Authentication and authorization review
  3. Input validation and output encoding
  4. Cryptographic implementation review
  5. Session management analysis
  6. Error handling and logging review"

# 快速安全掃描
/oh-my-claudecode:ask claude --agent-prompt security-reviewer-low \
  "quick security scan of recent changes"

9.3 SAST / DAST 整合

整合到開發流程

# 在 Team 模式中加入安全檢查階段
/team 3:executor "implement feature with security gates:
1. executor: implement the feature
2. security-reviewer: scan for vulnerabilities
3. test-engineer: write security test cases"

自動化安全 Hook

OMC 的 Hook 系統可在工具使用前後進行安全檢查:

Hook事件安全用途
pre-tool-enforcer.mjsPreToolUse工具使用前驗證權限
permission-handler.mjsPermissionRequestBash 指令權限處理
post-tool-verifier.mjsPostToolUse工具使用後驗證結果

9.4 威脅建模(Threat Modeling)

# 使用 Architect + Security Reviewer 進行威脅建模
/ralplan "perform threat modeling for the authentication system:
1. Identify trust boundaries
2. Map data flows
3. Identify threats (STRIDE)
4. Assess risks
5. Propose mitigations"

9.5 Compliance(金融業)

企業部署建議

# 環境設定
export OMC_SECURITY=strict
// .claude/omc.jsonc
{
  "security": {
    "restrictToolPaths": true,
    "pythonSandbox": true,
    "disableRemoteMcp": true,
    "disableExternalLLM": true,
    "disableAutoUpdate": true,
    "hardMaxIterations": 200
  }
}

操作指引

  • 只使用經核准的 LLM API 和 AI 閘道器
  • 只使用經核准的 MCP 伺服器
  • 不要在 Claude Code 設定中設定 "permission": {"*": "allow"},使用 "ask" 模式
  • 避免 hook commands(hook.command)— 它們以 shell: true 執行
  • 最小化敏感環境變數(API Key、Token)— MCP 程序會繼承
  • 手動安裝 OMC,不要透過 Agent 安裝
  • 使用 "disableAutoUpdate": true 釘選到已驗證版本
  • 只從可信來源 clone repository — .mcp.json 檔案會被 Claude Code 自動載入

9.6 已知安全限制

限制風險緩解措施
無 OS 層級程序沙箱Python blocklist 提供縱深防禦;建議對不信任程式碼使用 OS 層級隔離
Agent 之間無安全邊界Agent 共享檔案系統和 MCP 存取;worker 程序的環境變數使用 allowlist
背景 Agent 監控盲區Team 模式中使用者無法監看所有平行 Agent

實務建議:金融業環境必須啟用 OMC_SECURITY=strict。建議搭配企業級 SAST 工具(如 SonarQube、Checkmarx)進行額外掃描。所有 Agent 產出的程式碼應經過人工審查後才能合併。


10. 系統維運(Maintenance)

10.1 Log 與監控

監控工具總覽

工具功能來源
Agent Observatory即時 Agent 狀態、效率、瓶頸HUD / API
Session-End Summaries每次 session 摘要和回呼 payload.omc/sessions/*.json
Session Replay事件時間軸(事後分析).omc/state/agent-replay-*.jsonl
Session Search搜尋歷史 session/transcriptomc session search
Intervention System自動偵測停滯 Agent、成本超支自動

CLI 監控指令

# 渲染 HUD 狀態列
omc hud

# 檢查 Team 工作狀態
omc team status <team-name>

# 檢視最近的 replay log
tail -20 .omc/state/agent-replay-*.jsonl

# 列出 session 摘要
ls .omc/sessions/*.json

# 搜尋歷史 session
omc session search "team leader stale"
omc session search notify-hook --since 7d
omc session search provider-routing --project all --json

10.2 Agent Debug

診斷工具

# 執行全面診斷
/oh-my-claudecode:omc-doctor

檢查項目:

  • 缺少的依賴
  • 設定錯誤
  • Hook 安裝狀態
  • Agent 可用性
  • Skill 註冊

停用特定 Hook 進行除錯

# 停用所有 OMC Hook
export DISABLE_OMC=1

# 跳過特定 Hook
export OMC_SKIP_HOOKS="keyword-detector,persistent-mode"

10.3 錯誤排除

常見問題

問題解決方案
指令找不到重新執行 /oh-my-claudecode:omc-setup
Hook 未執行檢查權限:chmod +x ~/.claude/hooks/**/*.sh
Agent 未委派驗證 CLAUDE.md 已載入:檢查 ./.claude/CLAUDE.md~/.claude/CLAUDE.md
LSP 工具無法運作安裝語言伺服器:npm install -g typescript-language-server
Token 限制錯誤使用 /oh-my-claudecode: 進行 Token 高效執行

Rate Limit 處理

# 檢查速率限制狀態
omc wait

# 啟用自動恢復 daemon
omc wait --start

# 停用 daemon
omc wait --stop

Session Search 詳解

Session Search 提供 CLI 和 MCP/Tool 兩個介面搜尋歷史 session:

CLI 介面

# 基本搜尋
omc session search "team leader stale"

# 時間範圍搜尋
omc session search notify-hook --since 7d

# 跨專案搜尋(JSON 輸出)
omc session search provider-routing --project all --json

MCP/Tool 介面session_search):

Agent 可在會話中透過 session_search MCP 工具程式化地搜尋歷史記錄。此工具回傳結構化 JSON,方便 Agent 分析先前的會話模式和決策。

10.4 狀態管理

目錄結構

.omc/
├── state/                    # 每模式狀態檔
│   ├── autopilot-state.json  # autopilot 進度
│   ├── ralph-state.json      # ralph 迴圈狀態
│   ├── team/                 # team 任務狀態
│   ├── interop/              # 跨工具任務/訊息信封
│   └── sessions/             # 每 session 狀態
│       └── {sessionId}/
├── notepad.md                # 壓縮抗性備忘錄
├── project-memory.json       # 專案知識庫
├── plans/                    # 執行計畫
├── notepads/                 # 每計畫知識擷取
│   └── {plan-name}/
│       ├── learnings.md
│       ├── decisions.md
│       ├── issues.md
│       └── problems.md
├── prompts/                  # 持久化 prompt/response artifacts
├── skills/                   # 專案層級 Skills
├── sessions/                 # session 摘要
├── artifacts/                # Ask 等產出的 artifacts
│   └── ask/
├── autopilot/                # autopilot artifacts
│   └── spec.md
├── research/                 # 研究結果
└── logs/                     # 執行日誌

集中式狀態管理

# 在 shell profile 中設定(~/.bashrc, ~/.zshrc)
export OMC_STATE_DIR="$HOME/.claude/omc"

狀態存儲路徑:~/.claude/omc/{project-identifier}/,其中 project identifier 使用 Git remote URL 的 hash(跨 worktree 穩定)。若同時存在舊版 {worktree}/.omc/ 目錄和集中式目錄,OMC 會記錄通知並使用集中式目錄。

10.5 Project Memory 系統

檔案:.omc/project-memory.json

Project Memory 是專案層級的持久知識庫,跨 session 存續。

MCP 工具

工具說明
project_memory_read讀取專案記憶
project_memory_write覆寫整個專案記憶
project_memory_add_note新增備註
project_memory_add_directive新增指示

生命週期整合

事件行為
SessionStart載入 project memory 並注入到上下文
PostToolUse從工具結果中提取專案知識並儲存
PreCompact在上下文壓縮前儲存 project memory

10.6 Notepad 系統(壓縮抗性備忘錄)

檔案:.omc/notepad.md

Notepad 在上下文壓縮後仍然存續。寫入其中的內容即使在 context window 重置後也會持續保留。

MCP 工具

工具說明
notepad_read讀取 notepad 內容
notepad_write_priority寫入高優先備忘(永久保留)
notepad_write_working寫入工作備忘
notepad_write_manual寫入手動備忘
notepad_prune清理舊備忘
notepad_stats檢視 notepad 統計

運作機制

  1. PreCompact 事件時,重要資訊儲存到 notepad
  2. 壓縮完成後,notepad 內容重新注入到上下文
  3. Agent 使用 notepad 恢復先前的上下文

10.7 Plan Notepad(每計畫知識擷取)

路徑:.omc/notepads/{plan-name}/

分別儲存每個執行計畫的學習成果:

檔案內容
learnings.md發現的模式、成功的方法
decisions.md架構決策與理由
issues.md問題與阻礙
problems.md技術債與注意事項

所有條目自動加上時間戳記。

10.8 Session Scope(Session 隔離)

路徑:.omc/state/sessions/{sessionId}/

儲存按 session 隔離的狀態。同一專案上的多個 session 可同時運行而不會產生狀態衝突。

10.9 Code Simplifier Hook

code-simplifier Stop hook 在每次 Claude 回合結束後,自動將最近修改的原始碼檔案委派給 code-simplifier agent。預設停用,需透過全域 OMC 設定檔明確啟用:

{
  "codeSimplifier": {
    "enabled": true,
    "extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
    "maxFiles": 10
  }
}
選項型別預設說明
enabledbooleanfalse啟用自動簡化
extensionsstring[][".ts",".tsx",".js",".jsx",".py",".go",".rs"]要考慮的副檔名
maxFilesnumber10每回合最大簡化檔案數

運作流程:

  1. Claude 停止時,hook 執行 git diff HEAD --name-only 找出修改的檔案
  2. 若發現修改的原始碼檔案,hook 注入訊息要求 Claude 委派給 code-simplifier agent
  3. Agent 在不改變行為的前提下簡化檔案的清晰度和一致性
  4. 回合範圍標記防止 hook 在同一回合週期中重複觸發

實務建議:建議設定 OMC_STATE_DIR 集中管理狀態,避免 worktree 刪除時遺失狀態。定期備份 .omc/project-memory.json.omc/skills/

10.10 OpenClaw 整合(外部事件閘道器)

OpenClaw 是 OMC 的外部事件閘道器整合,讓 Claude Code 實例能夠回應外部世界的事件驅動觸發(GitHub webhook、Slack 指令、排程器 cron 等),而非僅限於終端互動。

核心概念

外部事件 (GitHub/Slack/Cron/API)
        ↓
  OpenClaw Gateway
        ↓
  Event → Task 轉換
        ↓
  OMC Team / Ralph / Autopilot
        ↓
  結果回報(Webhook / Notification)

OpenClaw 解決的是「Claude Code 是互動式工具,但企業需要事件驅動自動化」的缺口。

典型使用場景

場景觸發來源OMC 處理
PR 建立時自動 Code ReviewGitHub Webhookomc team 1:code-reviewer "review PR #123"
Issue 指派時自動實作GitHub Webhookomc team 2:executor "implement issue #456"
排程安全掃描Cron Jobomc ask --agent-prompt security-reviewer
Slack 指令觸發部署分析Slack Botomc team 1:architect "analyze deployment readiness"
CI/CD 失敗時自動 DebugCI Webhookomc ask --agent-prompt debugger "fix CI failure"

設定方式

// .omc/openclaw.jsonc
{
  "enabled": true,
  "gateway": {
    "port": 8090,
    "auth": "bearer-token"   // 或 "webhook-secret"
  },
  "routes": [
    {
      "event": "github.pull_request.opened",
      "action": "team",
      "config": {
        "workers": "1:code-reviewer",
        "taskTemplate": "Review PR #{payload.number}: {payload.title}"
      }
    },
    {
      "event": "github.issues.assigned",
      "action": "ralph",
      "config": {
        "taskTemplate": "Implement issue #{payload.number}: {payload.title}"
      }
    },
    {
      "event": "cron.daily.security",
      "action": "ask",
      "config": {
        "agentPrompt": "security-reviewer",
        "task": "Run daily security audit on recent changes"
      }
    }
  ],
  "notifications": {
    "onComplete": ["github-comment", "slack"],
    "onFailure": ["slack", "email"]
  }
}

安全注意事項

  • 驗證所有 Webhook 簽名:使用 webhook-secret 模式驗證 GitHub 的 X-Hub-Signature-256
  • 限制事件類型:僅允許白名單內的事件觸發 OMC 任務
  • Rate Limiting:設定每分鐘最大觸發次數,防止惡意事件洪流
  • Token 隔離:OpenClaw 使用的 API Key 應與開發者個人 Key 分離
  • 沙箱執行:建議在容器化環境中執行 OpenClaw 閘道器

企業建議:OpenClaw 適合 CI/CD 自動化與 DevOps 流程整合。在生產環境部署前,務必通過安全審查並設定適當的存取控制。


11. 系統升級(Upgrade)

11.1 oh-my-claudecode 升級策略

Plugin 安裝升級(推薦)

# 在 Claude Code 會話中
# Step 1:更新 marketplace clone
/plugin marketplace update omc

# Step 2:重新執行 setup 刷新設定
/setup

⚠️ 重要:更新 plugin 後,必須重新執行 /oh-my-claudecode:omc-setup 以套用最新的 CLAUDE.md 變更。

npm 安裝升級(已棄用)

# ⚠️ 已棄用 — 不建議使用
npm i -g oh-my-claude-sisyphus@latest

本地 Checkout 升級

# 如果是本地 checkout 或 git worktree
cd /path/to/oh-my-claudecode
git pull origin main

# 重新執行 setup
omc setup

11.2 升級後驗證

# 升級後問題排除
/omc-doctor

11.3 Agent 相容性

升級後注意事項:

  • Agent 檔案更新:升級後重新執行 /setup 以更新 ~/.claude/agents/ 中的 Agent 定義
  • Skills 相容性:檢查自訂 Skills 是否與新版 frontmatter 格式相容
  • Hook 變更:確認自訂 Hook 與新的生命週期事件相容

11.4 Config Migration

設定優先順序確認

./.claude/CLAUDE.md  (專案)  →  覆蓋  →  ~/.claude/CLAUDE.md  (全域)

自動更新機制

OMC 內建靜默自動更新系統:

  • 速率限制:每 24 小時最多檢查一次
  • 併發安全:Lock file 防止同時更新
  • 跨平台:macOS 和 Linux 皆支援

注意:企業環境建議設定 "disableAutoUpdate": true 並手動管理升級。

何時需要重新執行 Setup

場景動作
首次安裝執行 setup(選擇專案或全域)
更新後重新執行以取得最新設定
不同機器在每台使用 Claude Code 的機器上執行
新專案在每個需要 OMC 的專案中執行 --local

11.5 解除安裝

# 使用 Claude Code plugin 管理
/plugin uninstall oh-my-claudecode@oh-my-claudecode

# 或手動移除
rm ~/.claude/agents/{architect,document-specialist,explore,designer,writer,vision,critic,analyst,executor,qa-tester}.md
rm ~/.claude/commands/{analyze,autopilot,deepsearch,plan,review,ultrawork}.md

實務建議:建議建立升級 SOP,包含:備份設定 → 更新 OMC → 執行 setup → 執行 doctor → 驗證核心功能。

11.6 版本遷移指南摘要

以下摘要涵蓋各主要版本遷移的關鍵變更。完整遷移指南請參閱 MIGRATION.md

v2.x → v3.0:套件重新命名與自動啟動

項目變更內容
品牌名稱oh-my-claudecode(GitHub、plugin、指令)
npm 套件名oh-my-claude-sisyphus(向後相容,不變)
安裝方式Plugin 系統為唯一方式(npm/bun 已棄用)
行為啟動自然語言自動偵測(無需記憶斜線指令)
Magic Keywordsralphralplanulw/ultraworkplan
取消操作說 “stop”/“cancel”/“abort” 即可
Agent 命名描述性角色名稱(architectexecutorcritic
# 遷移步驟
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode
# 然後說 "setup omc"

v3.x → v3.4.0:平行執行與進階工作流

新增:Pipeline 順序鏈結、Unified Cancel、Explore-High Agent、State 標準化。

v3.5.x:Skill 整合

  • 移除 8 個已棄用 Skills(cancel-*omc-defaultplanner
  • 最終 Skill 數量:37 → 後續調整為 35

Team MCP Runtime 棄用(CLI-Only)

⚠️ 重要omc_run_team_start/status/wait/cleanup MCP 工具已硬棄用。呼叫時回傳 deprecated_cli_only 錯誤。

# ❌ 舊方式(已棄用)
mcp__team__omc_run_team_start(...)

# ✅ 新方式(CLI-first)
omc team 2:codex "review auth flow"
omc team status review-auth-flow
omc team shutdown review-auth-flow --force

omc ask 環境變數別名日落

OMC_ASK_* 為正式環境變數。Phase-1 仍接受 OMX_ASK_ADVISOR_SCRIPTOMX_ASK_ORIGINAL_TASK(附帶棄用警告)。預定硬日落日期:2026-06-30

Native Team Worktree Mode(Opt-In,未釋出)

omc team runtime-v2 正在引入選配的 worker worktree 模式。Worker 在專屬 git worktree 中運作,而任務生命週期、mailbox、狀態和 manifest 保留在 leader workspace 的 team 協調根目錄下。

<repo>/.omc/team/<team-name>/worktrees/<worker-name>   # Worker worktree
<repo>/.omc/state/team/<team-name>                      # 狀態/協調根

12. 最佳實務(Best Practices)

12.1 Agent 設計原則

  1. 專職化:每個 Agent 專注單一領域,避免「全能型 Agent」
  2. 分層選擇:根據任務複雜度選擇適當模型層級
  3. 組合優先:善用 Skills 三層堆疊,靈活組合行為
  4. 驗證閉環:所有重要任務使用 Verifier 確認完成

12.2 Prompt Engineering

有效 Prompt 結構

# 好的 Prompt 範例
/team 3:executor "implement user authentication:
1. JWT token generation and validation
2. Refresh token mechanism
3. Password hashing with bcrypt
4. Rate limiting for login attempts
5. Session management with Redis

Technical constraints:
- Spring Boot 3.2 with Spring Security 6
- PostgreSQL for user storage
- Redis for session cache
- Must pass OWASP authentication checks"

不同場景的 Prompt 模式

場景推薦 Prompt 模式
新功能開發列出具體需求 + 技術約束 + 驗收標準
逆向工程描述系統背景 + 分析目標 + 預期產出
Framework 升級現有版本 + 目標版本 + 已知破壞性變更
Bug 修復問題描述 + 重現步驟 + 預期行為
安全審查審查範圍 + 合規要求 + 風險等級

12.3 開發流程標準化

推薦工作流

graph TB
    A[需求釐清
deep-interview] --> B[架構規劃
ralplan] B --> C[計畫審查
critic] C --> D{通過?} D -->|是| E[功能實作
team / autopilot] D -->|否| B E --> F[程式碼審查
code-reviewer] F --> G[安全審查
security-reviewer] G --> H[測試驗證
test-engineer] H --> I{全部通過?} I -->|是| J[Git 提交
git-master] I -->|否| E J --> K[完成]

魔術關鍵字速查

關鍵字效果
ultrawork / ulw / uw平行 Agent 編排
autopilot / build me / e2e this全自主執行
ralph / don't stop / must complete持久模式直到驗證完成
ccg / claude-codex-gemini三模型編排
ralplan迭代規劃共識
deep interview / ouroboros蘇格拉底式深度訪談
deepsearch程式碼搜尋模式
ultrathink / think hard深度推理模式
tdd / test first / red greenTDD 工作流
code review全面程式碼審查
security review安全審查
cancelomc / stopomc取消/停止活動模式
deslop / anti-slopAI 表達清理
deepanalyze / deep-analyze深度分析模式

實務建議:建議團隊制定統一的 Prompt 模板和工作流程文件,新成員入職時進行培訓。使用 .omc/skills/ 存放團隊共用的 Prompt 模式。


13. 範例(完整案例)

13.1 案例一:Web 系統開發(全流程)

場景:開發一個企業級任務管理系統(前後端分離)

Step 1:需求釐清

/deep-interview "I want to build an enterprise task management system with:
- Multi-tenant support
- Role-based access control (Admin/Manager/Developer)
- Task lifecycle (Created → In Progress → Review → Done)
- Real-time notifications
- REST API + React frontend
- PostgreSQL database"

Step 2:架構規劃

/ralplan "design the system architecture:
- Clean Architecture with domain-driven design
- Spring Boot 3.2 backend
- React 18 + TypeScript frontend
- PostgreSQL + Redis
- JWT authentication
- WebSocket for real-time updates"

Step 3:執行實作

# 使用 Team 模式平行開發
/team 3:executor "implement the task management system:
Agent 1: Backend API (Spring Boot + JPA + Security)
Agent 2: Frontend Components (React + TypeScript + Tailwind)
Agent 3: Database Schema + Migrations (Flyway)"

Step 4:安全與品質驗證

# 安全審查
/oh-my-claudecode:ask claude --agent-prompt security-reviewer \
  "review the entire codebase for security vulnerabilities"

# 程式碼審查
/oh-my-claudecode:ask claude --agent-prompt code-reviewer \
  "comprehensive code review focusing on:
  - API contract quality
  - Error handling
  - Test coverage
  - Performance concerns"

Step 5:持久模式確保完成

/ralph "ensure all components are working:
1. All unit tests pass
2. Integration tests pass
3. API documentation is complete
4. Frontend builds without errors
5. Database migrations run successfully"

13.2 案例二:Legacy 系統重構

場景:一個 10 年歷史的 Java 銀行交易系統,無文件,原開發者已離職

Step 1:系統探索

/ultrawork "analyze this legacy banking system:
1. Map the package structure and dependencies
2. Identify all entry points (servlets, schedulers, message listeners)
3. Document all database tables and their relationships
4. List all external integrations (SWIFT, payment gateways, etc.)
5. Identify design patterns currently in use"

Step 2:架構還原

/team 3:executor "reverse engineer the architecture:
Agent 1 (architect): Draw the system architecture diagram
Agent 2 (explore): Map all inter-module dependencies
Agent 3 (document-specialist): Generate module documentation"

Step 3:風險評估

/ralplan "assess migration risks:
1. Identify tightly coupled modules
2. Find undocumented business rules in code
3. Assess test coverage gaps
4. List deprecated dependencies with CVEs
5. Propose strangler fig migration boundaries"

Step 4:漸進式重構

/ralph "refactor the authentication module:
1. Extract auth logic from monolith
2. Implement as standalone microservice
3. Add comprehensive test coverage
4. Ensure backward compatibility
5. Document API contracts"

13.3 案例三:Framework 升級

場景:Spring Boot 2.7 升級至 3.2,包含 javax → jakarta 命名空間遷移

Step 1:影響分析

/deep-interview "upgrade Spring Boot from 2.7 to 3.2:
Current state:
- 200+ Java files
- 50+ Spring Security configurations
- 30+ JPA entities
- Custom servlet filters
- Third-party library integrations"

Step 2:依賴分析

/ccg "analyze all dependencies for Spring Boot 3.2 compatibility:
- Codex: identify incompatible libraries and suggest alternatives
- Gemini: check for deprecated APIs and migration guides
- Claude: create a prioritized upgrade plan"

Step 3:執行升級

/ralph "execute Spring Boot upgrade step by step:
1. Update parent POM to Spring Boot 3.2
2. Migrate javax.* → jakarta.* imports
3. Update Spring Security configuration to new API
4. Fix deprecated method calls
5. Update third-party libraries
6. Run all tests and fix failures
7. Verify application startup
8. Performance regression test"

Step 4:驗證

/ultrawork "verify the upgrade:
1. All unit tests pass
2. All integration tests pass
3. Application starts successfully
4. API endpoints respond correctly
5. Security configurations work
6. Database operations function properly
7. No compilation warnings"

實務建議:大型升級建議分階段進行,每個階段使用 ralph 確保完整驗證。保留 omc session search 記錄供事後檢討。


14. 團隊導入建議

14.1 如何導入公司

Phase 1:試點(1-2 週)

  • 選擇 2-3 位資深工程師組成先鋒團隊
  • 安裝 OMC 並完成基礎設定
  • 在低風險專案上試用基本功能(autopilot、ultrawork)
  • 記錄使用心得和問題

Phase 2:標準化(2-4 週)

  • 建立團隊 CLAUDE.md 範本
  • 建立共用 Skills 知識庫
  • 制定 OMC 使用規範
  • 進行團隊培訓

Phase 3:全面推廣(4-8 週)

  • 所有開發團隊導入 OMC
  • 整合到 CI/CD 流程
  • 建立定期 Skills 審查機制
  • 成本監控與優化

14.2 Developer Workflow 設計

日常開發流程

┌─────────────────────────────────────────────────────────────┐
│                    OMC 輔助開發流程                           │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  1. 需求理解      → /deep-interview "需求描述"               │
│  2. 架構設計      → /ralplan "設計需求"                       │
│  3. 程式碼實作    → /team N:executor "實作任務"               │
│  4. 程式碼審查    → code-reviewer + security-reviewer         │
│  5. 測試          → test-engineer + qa-tester                  │
│  6. 文件          → writer + document-specialist               │
│  7. Git 操作      → git-master                                │
│                                                               │
└─────────────────────────────────────────────────────────────┘

14.3 Governance(權限 / 審核)

安全治理

項目建議
安全模式生產環境強制 OMC_SECURITY=strict
自動更新企業環境停用,手動管理版本
MCP 伺服器僅允許經核准的 MCP 伺服器
API Key使用企業金鑰管理系統
程式碼審查Agent 產出必須經人工審查
權限模式使用 "ask" 模式,不允許 "allow"

成本治理

項目建議
模型選擇根據任務複雜度選擇適當模型
迭代上限設定 hardMaxIterations 防止失控
Token 追蹤使用 HUD analytics 監控使用量
預算管理設定每月 Token 使用預算

實務建議:建議指定一位「OMC Champion」負責:維護共用 Skills、管理安全設定、追蹤成本、處理團隊問題。


15. 附錄

15.1 CLI 指令清單

Terminal CLI 指令

指令說明
omc setup初始設定
omc setup --plugin-dir-mode開發模式設定
omc ask <provider> "prompt"Provider 顧問
omc team N:agent "task"Team CLI workers
omc team status <name>檢查 Team 狀態
omc team shutdown <name>關閉 Team
omc session search "query"搜尋歷史 session
omc hud渲染 HUD 狀態列
omc wait速率限制管理
omc wait --start啟用自動恢復
omc config-stop-callback設定通知回呼
omc doctor診斷工具
omc doctor --plugin-dir <path>指定 plugin 路徑進行診斷
omc doctor conflicts診斷衝突
omc team api claim-task透過 API 領取 Team 任務

In-Session Skills(斜線指令)

指令說明
/oh-my-claudecode:setup統一設定入口
/oh-my-claudecode:omc-doctor診斷安裝問題
/oh-my-claudecode:autopilot <task>全自主執行
/oh-my-claudecode:ralph <task>持久模式
/oh-my-claudecode:ultrawork <task>最大平行度
/oh-my-claudecode:team N:agent <task>協調多 Agent
/oh-my-claudecode:ccg <task>三模型編排
/oh-my-claudecode:ralplan <desc>迭代規劃共識
/oh-my-claudecode:deep-interview <idea>蘇格拉底式訪談
/oh-my-claudecode:deep-dive <problem>追蹤→深度訪談管線
/oh-my-claudecode:ask <provider> <prompt>Provider 顧問
/oh-my-claudecode:learner提取可重用模式
/oh-my-claudecode:skill list|add|remove管理 Skills
/oh-my-claudecode:trace證據驅動追蹤
/oh-my-claudecode:release自動化發佈
/oh-my-claudecode:hud setupHUD 設定
/oh-my-claudecode:ai-slop-cleanerAI 表達清理
/oh-my-claudecode:deepinit生成 AGENTS.md 文件
/oh-my-claudecode:mcp-setup設定 MCP 伺服器
/oh-my-claudecode:sciomc <topic>平行研究編排
/oh-my-claudecode:ultraqa <goal>自主 QA 循環
/oh-my-claudecode:visual-verdict視覺 QA 判定
/oh-my-claudecode:wiki持久知識庫
/oh-my-claudecode:cancel取消活動模式
/oh-my-claudecode:configure-notifications設定通知
/oh-my-claudecode:self-improve自主進化改進引擎
/oh-my-claudecode:external-context平行文件研究
/oh-my-claudecode:writer-memory寫作專案記憶系統

15.2 常見錯誤

錯誤原因解決方案
Commands not found未完成 setup執行 /oh-my-claudecode:omc-setup
Hooks not executing權限問題chmod +x ~/.claude/hooks/**/*.sh
Agents not delegatingCLAUDE.md 未載入檢查 ./.claude/CLAUDE.md~/.claude/CLAUDE.md
LSP tools not working語言伺服器未安裝npm install -g typescript-language-server
Token limit errors上下文溢出使用 /compact 或切換到更高效模式
Team disabled未啟用 experimental flag在 settings.json 加入 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"
tmux not found未安裝 tmux安裝 tmux 或 psmux(Windows)
Plugin cache issues舊版快取衝突執行 /omc-doctor

15.3 Prompt 範本

新功能開發

/autopilot "implement [FEATURE_NAME]:

Requirements:
1. [具體需求 1]
2. [具體需求 2]
3. [具體需求 3]

Technical constraints:
- [技術框架/版本]
- [資料庫/快取]
- [安全要求]

Acceptance criteria:
- [驗收標準 1]
- [驗收標準 2]
- All tests pass
- No security vulnerabilities"

程式碼審查

/oh-my-claudecode:ask claude --agent-prompt code-reviewer \
  "review [TARGET] for:
  1. Code quality and maintainability
  2. API contract correctness
  3. Error handling completeness
  4. Test coverage adequacy
  5. Performance concerns
  6. Security best practices"

逆向工程

/ultrawork "analyze [LEGACY_SYSTEM]:
1. Map module structure and dependencies
2. Identify all entry points and data flows
3. Document business rules embedded in code
4. List all external integrations
5. Assess technical debt and risk areas
6. Generate architecture documentation"

Framework 升級

/ralph "upgrade [FRAMEWORK] from [OLD_VERSION] to [NEW_VERSION]:
1. Update dependency definitions
2. Fix breaking API changes
3. Migrate deprecated features
4. Update configuration files
5. Run and fix all tests
6. Verify application startup
7. Performance regression check"

安全審查

/oh-my-claudecode:ask claude --agent-prompt security-reviewer \
  "security review for [TARGET]:
  1. OWASP Top 10 analysis
  2. Authentication/authorization review
  3. Input validation and encoding
  4. Cryptographic implementation
  5. Session management
  6. Dependency vulnerabilities
  7. Configuration security"

15.4 可用工具清單

標準工具

工具說明
Read讀取檔案
Write建立檔案
Edit修改檔案
Bash執行 shell 指令
Glob依模式尋找檔案
Grep搜尋檔案內容
WebSearch搜尋網路
WebFetch擷取網頁
Task生成 subagent
TodoWrite追蹤任務

LSP 工具

工具說明
lsp_hover取得型別資訊與文件
lsp_goto_definition跳到定義
lsp_find_references尋找所有用法
lsp_document_symbols檔案大綱(函式、類別等)
lsp_workspace_symbols工作區符號搜尋
lsp_diagnostics錯誤/警告/提示
lsp_diagnostics_directory專案層級型別檢查
lsp_prepare_rename檢查重新命名是否有效
lsp_rename跨專案重新命名
lsp_code_actions可用的重構
lsp_code_action_resolve取得 code action 的詳細資訊
lsp_servers列出可用的語言伺服器

注意:LSP 工具需要安裝對應的語言伺服器(typescript-language-server、ty、rust-analyzer、gopls 等)。使用 lsp_servers 檢查安裝狀態。

AST 工具(ast-grep)

工具說明
ast_grep_searchAST 模式匹配搜尋
ast_grep_replaceAST 模式匹配替換

注意:AST 工具使用 @ast-grep/napi 進行結構化程式碼匹配。支援 meta-variables:$VAR(單一節點)和 $$$(多個節點)。

Notepad MCP 工具

工具說明
notepad_read讀取 notepad 內容
notepad_write_priority寫入高優先備忘(永久保留)
notepad_write_working寫入工作備忘
notepad_write_manual寫入手動備忘
notepad_prune清理舊備忘
notepad_stats檢視 notepad 統計

Project Memory MCP 工具

工具說明
project_memory_read讀取專案記憶
project_memory_write覆寫整個專案記憶
project_memory_add_note新增備註
project_memory_add_directive新增指示

16. 檢查清單(Checklist)

新成員入門清單

  • 安裝 Claude Code CLI
  • 取得 Claude Pro/Max 訂閱或 API Key
  • 安裝 OMC Plugin:/plugin marketplace add + /plugin install
  • 執行初始設定:/setup/omc-setup(選擇 --local 進行專案層級設定)
  • 安裝 tmux(macOS/Linux)或使用 WSL2(Windows,強烈建議
  • 啟用 Claude Code Native Teams(settings.json)
  • 執行診斷確認:/omc-doctor
  • 熟悉基本指令:/autopilot/team/ralph/ultrawork
  • 閱讀團隊 CLAUDE.md 與 Skills 規範
  • 完成第一個測試任務

專案初始化清單

  • 執行專案層級設定:/oh-my-claudecode:omc-setup --local
  • 建立 .claude/CLAUDE.md 專案設定
  • 建立 .omc/skills/ 專案 Skills 目錄
  • 設定安全模式(OMC_SECURITY=strict for enterprise)
  • 設定 HUD 預設值
  • 設定通知整合(Discord/Slack/Telegram)
  • .claude/.omc/skills/ 納入版本控制
  • 團隊成員確認可正常使用

安全合規清單(企業環境)

  • 啟用 OMC_SECURITY=strict
  • 設定 "disableAutoUpdate": true
  • 設定 "disableRemoteMcp": true
  • 設定 "disableExternalLLM": true(視需要)
  • 設定 "restrictToolPaths": true
  • 設定 "pythonSandbox": true
  • 設定 "hardMaxIterations": 200
  • Claude Code 權限設為 "ask" 模式
  • 確認只使用經核准的 MCP 伺服器
  • 設定 API Key 管理策略
  • 所有 Agent 產出須經人工審查

升級前清單

  • 備份 .claude/CLAUDE.md
  • 備份 .omc/skills/ 目錄
  • 備份 .omc/project-memory.json
  • 記錄目前版本號
  • 執行升級指令
  • 重新執行 /setup
  • 執行 /omc-doctor 驗證
  • 測試核心功能(autopilot、team、ralph)
  • 驗證自訂 Skills 相容性
  • 確認 Hook 正常運作

日常開發清單

  • 複雜任務先用 /deep-interview 釐清需求
  • 架構設計使用 /ralplan 取得共識
  • 多檔案修改使用 /team/ultrawork
  • 必須完成的任務使用 /ralph
  • 上下文超過 50% 執行 /compact
  • 重要發現記錄到 <remember priority> 標籤
  • 提交前執行 code-reviewer + security-reviewer
  • 定期檢查 HUD 的 Token 使用量

文件維護:本手冊基於 oh-my-claudecode v4.13.5(2026-04-28)撰寫,最後更新日期 2026-05-02。建議隨 OMC 版本升級同步更新本文件。

專案統計(截至 v4.13.5):32,000+ GitHub Stars、3,000+ Forks、106 Contributors、223 Releases

官方資源