Oh-My-ClaudeCode (OMC) 学习与使用手册

---

1. 项目简介

1.1 什么是 Oh-My-ClaudeCode？

Oh-My-ClaudeCode (OMC) 是一个为 Claude Code 设计的多智能体编排系统。它的核心理念是：

零学习曲线，最大化能力。
无需学习 Claude Code，直接使用 OMC。

1.2 为什么选择 OMC？

特性	说明
零配置	开箱即用，智能默认设置
Team 优先编排	Team 是标准的多智能体界面
自然语言交互	无需记忆命令，只需描述你的需求
自动并行化	复杂任务自动分配给专业智能体
持久执行	不会半途而废，直到任务验证完成
成本优化	智能模型路由节省 30-50% 的 token
从经验中学习	自动提取并复用问题解决模式
实时可见性	HUD 状态栏显示底层运行状态

1.3 灵感来源

OMC 的设计灵感来自以下优秀项目：

• oh-my-opencode
• claude-hud
• Superpowers
• everything-claude-code
• Ouroboros

---

2. 核心概念

2.1 多智能体编排

OMC 将复杂任务分解并分配给专门的智能体（Agent）处理。每个智能体都有特定的专长领域，如：

• 架构设计 - architect
• 代码执行 - executor
• 安全审查 - security-reviewer
• 测试工程 - test-engineer
• 文档编写 - document-specialist

2.2 智能模型路由

OMC 会根据任务复杂度自动选择最合适的模型：

模型	适用场景	特点
Haiku	快速查找、简单任务	成本低，速度快
Sonnet	标准开发任务	平衡性能与成本
Opus	架构决策、深度分析	最强推理能力

2.3 Team 流水线

Team 模式按阶段化流水线运行：

team-plan → team-prd → team-exec → team-verify → team-fix (loop)

• team-plan: 规划阶段
• team-prd: 需求文档生成
• team-exec: 执行阶段
• team-verify: 验证阶段
• team-fix: 修复循环

---

3. 环境准备与安装

3.1 系统要求

必需条件

组件	要求
Claude Code CLI	必须安装
订阅	Claude Max/Pro 或 Anthropic API 密钥

平台与 tmux

OMC 的部分功能（如 omc team 和速率限制检测）需要 tmux：

平台	安装命令
macOS	brew install tmux
Ubuntu/Debian	sudo apt install tmux
Fedora	sudo dnf install tmux
Arch Linux	sudo pacman -S tmux
Windows	winget install psmux (使用 psmux)
Windows (WSL2)	sudo apt install tmux (在 WSL 内)

Windows 用户注意: psmux 提供了 Windows 原生的 tmux 二进制文件，支持 76 个 tmux 兼容命令，无需 WSL。

3.2 安装方式

方式一：Marketplace/Plugin 安装（推荐）

# 添加 marketplace
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# 安装插件
/plugin install oh-my-claudecode

方式二：NPM CLI 安装

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

注意: 项目品牌名为 oh-my-claudecode，但 npm 包以 oh-my-claude-sisyphus 发布。

3.3 初始配置

# 运行基础设置
/setup
/omc-setup

3.4 启用 Claude Code 原生团队

在 ~/.claude/settings.json 中添加：

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

3.5 更新与维护

更新 OMC

# 更新 marketplace 克隆
/plugin marketplace update omc

# 重新运行设置
/omc-setup

故障排查

如果更新后遇到问题：

/omc-doctor

---

4. 快速入门

4.1 三步开始

第一步：安装 (见 3.2 安装方式)

第二步：配置 (见 3.3 初始配置)

第三步：开始构建

autopilot: build a REST API for managing tasks

就这么简单！其余都是自动的。

4.2 不确定从哪里开始？

如果你对需求不明确、有模糊的想法，或者想要精细控制设计：

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

深度访谈使用苏格拉底式提问在编写任何代码之前帮你理清思路。它揭示隐藏假设并通过加权维度衡量清晰度，确保你在执行前明确知道要构建什么。

---

5. 执行模式详解

OMC 提供多种执行策略，针对不同场景优化：

5.1 模式对比表

模式	特点	适用场景
Team（推荐）	阶段化流水线	在共享任务列表上协作的 Claude 智能体
omc team (CLI)	tmux CLI 工作者	Codex/Gemini CLI 任务；按需生成，完成后退出
ccg	三模型并行	Codex（分析）+ Gemini（设计），Claude 合成
Autopilot	自主执行	最小化繁琐配置的端到端功能开发
Ultrawork	最大并行	不需要 Team 的并行修复/重构
Ralph	持久模式	必须完整完成的任务
Pipeline	顺序处理	需要严格顺序的多阶段转换

5.2 各模式详解

Team 模式（推荐）

标准的 Claude 智能体协作模式，通过阶段化流水线完成复杂任务。

/team 3:executor "fix all TypeScript errors"

Autopilot 模式

全自主执行，适合端到端功能开发。

autopilot: build a todo app with authentication

Ralph 模式

持久执行模式，确保任务完整完成。

ralph: refactor auth module

注意: ralph 自动包含 ultrawork 的并行执行能力。

Ultrawork 模式

最大化并行执行，适合批量修复或重构。

ulw fix all lint errors

Pipeline 模式

顺序阶段处理，适合需要严格顺序的任务。

pipeline: migrate database schema step by step

---

6. 魔法关键词

魔法关键词是为高级用户提供的可选快捷方式。不用它们，自然语言也能很好地工作。

6.1 关键词列表

关键词	效果	示例
team	标准 Team 编排	/team 3:executor "fix all TypeScript errors"
omc team	tmux CLI 工作者	omc team 2:codex "security review"
ccg	三模型 Codex+Gemini 编排	/ccg review this PR
autopilot	全自动执行	autopilot: build a todo app
ralph	持久模式	ralph: refactor auth
ulw	最大并行化	ulw fix all errors
ralplan	迭代规划共识	ralplan this feature
deep-interview	苏格拉底式需求澄清	deep-interview "vague idea"
deepsearch	代码库搜索路由	deepsearch for auth middleware
ultrathink	深度推理模式	ultrathink about this architecture
cancelomc / stopomc	停止活动的 OMC 模式	stopomc

6.2 使用注意事项

• ralph 包含 ultrawork: 激活 ralph 模式时，会自动包含 ultrawork 的并行执行
• swarm 已弃用: 请使用 team 替代
• plan 触发已移除: 使用 ralplan 或显式的 /oh-my-claudecode:omc-plan

---

7. Team 模式深度指南

7.1 tmux CLI 工作者

从 v4.4.0 开始，OMC 移除了 Codex/Gemini MCP 服务器，改用 CLI-first 的 Team 运行时：

omc team 2:codex "review auth module for security issues"
omc team 2:gemini "redesign UI components for accessibility"
omc team 1:claude "implement the payment flow"
omc team status auth-review
omc team shutdown auth-review

7.2 工作者类型对比

技能	工作者	最适合
omc team N:codex	N 个 Codex CLI 窗格	代码审查、安全分析、架构
omc team N:gemini	N 个 Gemini CLI 窗格	UI/UX 设计、文档、大上下文任务
omc team N:claude	N 个 Claude CLI 窗格	通过 tmux 中的 Claude CLI 处理通用任务
/ccg	/ask codex + /ask gemini	三模型顾问合成

7.3 混合多模型工作

如需在一个命令中混合使用 Codex + Gemini：

/ccg Review this PR — architecture (Codex) and UI components (Gemini)

7.4 资源管理

工作者按需生成，任务完成后自动退出 — 无空闲资源浪费。

要求:

• 安装 codex / gemini CLI
• 有活跃的 tmux 会话

---

8. 智能体系统

8.1 智能体目录

OMC 提供 32 个专业智能体，覆盖各种开发场景：

智能体	模型	用途
explore	haiku	快速代码库探索
analyst	opus	深度分析
planner	opus	实现规划
architect	opus	架构设计
debugger	sonnet	调试问题
executor	sonnet	代码执行
verifier	sonnet	结果验证
tracer	sonnet	问题追踪
security-reviewer	sonnet	安全审查
code-reviewer	opus	代码审查
test-engineer	sonnet	测试工程
designer	sonnet	UI/UX 设计
writer	haiku	文档编写
qa-tester	sonnet	质量测试
scientist	sonnet	数据科学
document-specialist	sonnet	文档专家
git-master	sonnet	Git 操作
code-simplifier	opus	代码简化
critic	opus	批判性评审

8.2 智能体调用

通过前缀 oh-my-claudecode: 调用智能体：

# 调用架构师智能体
/oh-my-claudecode:architect "design the authentication system"

# 调用安全审查智能体
/oh-my-claudecode:security-reviewer "review this auth module"

8.3 委派规则

• 需要委派: 多文件更改、重构、调试、审查、规划、研究、验证
• 直接处理: 简单操作、小澄清、单条命令
• 代码路由: 代码执行 → executor（复杂工作用 model=opus）
• SDK 不确定时: → document-specialist

---

9. 技能系统

9.1 概念

一次学习，永久复用。 OMC 将调试过程中获得的实战知识提取为可移植的技能文件，并在相关场景中自动注入。

9.2 技能作用域

	项目作用域	用户作用域
路径	.omc/skills/	~/.omc/skills/
共享范围	团队（受版本控制）	所有项目通用
优先级	高（覆盖用户作用域）	低（回退）

9.3 技能文件格式

# .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...

9.4 技能管理

# 列出所有技能
/skill list

# 添加新技能
/skill add

# 移除技能
/skill remove <name>

# 编辑技能
/skill edit <name>

# 搜索技能
/skill search <keyword>

9.5 自动学习

/learner

以严格的质量标准从当前会话中提取可复用模式。

9.6 自动注入

匹配的技能自动加载到上下文中 — 无需手动调用。

9.7 内置技能清单

OMC v4.9.3 提供了 31 个内置技能，无需配置即可使用：

执行模式类

技能名称	描述
autopilot	全自主执行，从创意到可运行代码
ralph	自引用循环直到任务完成，带有可配置的验证审查者
ultrawork	并行执行引擎，用于高通量任务完成
ultraqa	QA 循环工作流 - 测试、验证、修复、重复直到达成目标
team	使用 Claude Code 原生团队模式在共享任务列表上协调 N 个代理

规划与分析类

技能名称	描述
omc-plan	带有可选访谈流程的战略规划
ralplan	共识规划入口，在执行前自动对模糊请求进行门控
deep-interview	带有数学歧义门控的苏格拉底式深度访谈
deep-dive	两阶段流水线：追踪（因果调查）→ 深度访谈（需求明确化）
deepinit	带有分层 AGENTS.md 文档的深度代码库初始化

多模型编排类

技能名称	描述
ask	通过 omc ask 为 Claude、Codex 或 Gemini 提供流程优先的顾问路由
ccg	Claude-Codex-Gemini 三模型编排
omc-teams	在 tmux 窗格中运行 claude、codex 或 gemini 工作进程的 CLI 团队运行时
external-context	调用并行的文档专家代理进行外部网络搜索和文档查询
sciomc	编排并行的科学家代理进行全面分析（自动模式）

调试与追踪类

技能名称	描述
trace	证据驱动的追踪，编排竞争的追踪者假设
visual-verdict	截图与参考对比的结构化视觉 QA 判定
ai-slop-cleaner	使用回归安全的删除优先工作流清理 AI 生成的代码垃圾

配置与管理类

技能名称	描述
setup	统一设置路由 — 将 setup、doctor 或 MCP 请求发送到正确的流程
omc-setup	为插件、npm、本地开发安装或刷新 oh-my-claudecode
omc-doctor	诊断并修复 oh-my-claudecode 安装问题
mcp-setup	配置流行的 MCP 服务器以增强代理能力
hud	配置 HUD 显示选项（布局、预设、显示元素）
configure-notifications	通过自然语言配置通知集成（Telegram、Discord、Slack）
cancel	取消任何活动的 OMC 模式（autopilot、ralph、ultrawork、team 等）

技能与记忆管理类

技能名称	描述
skill	管理本地技能 - 列表、添加、删除、搜索、编辑、设置向导
learner	从当前对话中提取学习到的技能
writer-memory	作家的代理记忆系统 - 追踪角色、关系、场景和主题

工作流管理类

技能名称	描述
project-session-manager	针对议题、PR 和功能的工作树优先开发环境管理器
release	oh-my-claudecode 的自动化发布工作流

参考文档类

技能名称	描述
omc-reference	OMC 代理目录、工具、团队流水线路由、技能注册表（自动加载）

---

10. 实用工具

10.1 Provider Advisor (omc ask)

运行本地提供商 CLI 并保存 markdown 结果到 .omc/artifacts/ask/：

omc ask claude "review this migration plan"
omc ask codex --prompt "identify architecture risks"
omc ask gemini --prompt "propose UI polish ideas"
omc ask claude --agent-prompt executor --prompt "draft implementation steps"

10.2 速率限制等待

当速率限制重置时自动恢复 Claude Code 会话：

omc wait          # 检查状态，获取指导
omc wait --start  # 启用自动恢复守护进程
omc wait --stop   # 禁用守护进程

需要: tmux（用于会话检测）

10.3 HUD 状态栏详解

HUD（Heads-Up Display）是 OMC 的实时状态显示系统，在 Claude Code 状态栏中显示会话信息。

快捷命令

命令	描述
/oh-my-claudecode:hud	显示当前 HUD 状态（自动设置）
/oh-my-claudecode:hud setup	安装/修复 HUD 状态栏
/oh-my-claudecode:hud minimal	切换到精简显示
/oh-my-claudecode:hud focused	切换到聚焦显示（默认）
/oh-my-claudecode:hud full	切换到完整显示

显示预设

精简模式（minimal）

[OMC] ralph | ultrawork | todos:2/5

聚焦模式（focused，默认）

[OMC#4.9.3] | thinking | session:171m | skill:hud(setup) | ctx:65% | T:54 S:2

完整模式（full）

[OMC] repo:oh-my-claudecode branch:main | ralph:3/10 | ctx:[████░░]67% | agents:3 | todos:2/5
├─ O architect    2m   analyzing architecture patterns...
├─ e explore     45s   searching for test files
└─ s executor     1m   implementing validation logic

显示元素详解

基础显示元素

元素	示例	说明
[OMC]	[OMC] 或 [OMC#4.9.3]	模式标识，可显示版本号
repo:name	repo:oh-my-claudecode	Git 仓库名（青色）
branch:name	branch:main	Git 分支名（青色）
ralph:N/M	ralph:3/10	Ralph 循环当前迭代/最大迭代
autopilot	autopilot	Autopilot 模式徽章
ultrawork	ultrawork	Ultrawork 模式徽章
skill:name	skill:hud	最后激活的技能名称
US-002	US-002	当前 PRD 故事 ID

资源监控元素

元素	示例	说明
ctx:N%	ctx:67%	上下文窗口使用率
ctx:[████░░]N%	ctx:[████░░]67%	上下文使用率可视化条（full 模式）
agents:N	agents:3	运行中的子代理数量
bg:N/M	bg:3/5	后台任务使用/最大槽位
todos:N/M	todos:2/5	Todo 完成/总数

会话信息元素

元素	示例	说明
session:Nm	session:171m	会话运行时长（分钟）
thinking	thinking	扩展思考模式状态
T:N	T:54	工具调用次数
S:N	S:2	子代理数量
prompt:Ns	prompt:2.3s	最后提示响应时间

高级元素

元素	示例	说明
profile:name	profile:sonnet	当前使用的模型配置
api:source	api:max	API 密钥来源（Max/Pro/API）

多行代理显示

当代理运行时，HUD 会在单独行显示详情：

├─ O architect    2m   analyzing architecture patterns...
├─ e explore     45s   searching for test files
└─ s executor     1m   implementing validation logic

字段	说明
O/e/s	代理类型代码（大写=Opus，小写=Sonnet/Haiku）
architect	代理名称
2m	运行时长
analyzing...	当前任务描述（最长 45 字符）

颜色编码

颜色	含义	触发条件
🟢 绿色	正常/健康	上下文 <70%，ralph <7
🟡 黄色	警告	上下文 >70%，ralph >7
🔴 红色	临界	上下文 >85%，ralph 达到最大值
青色	信息	分支名、仓库名、技能名

配置示例

在 ~/.claude/settings.json 的 omcHud 键下配置：

{
  "omcHud": {
    "preset": "focused",
    "elements": {
      "omcLabel": true,
      "repo": true,
      "branch": true,
      "ralph": true,
      "autopilot": true,
      "activeSkills": true,
      "lastSkill": true,
      "contextBar": true,
      "agents": true,
      "agentsFormat": "multiline",
      "backgroundTasks": true,
      "todos": true,
      "thinking": true,
      "profile": true,
      "showCallCounts": true,
      "maxOutputLines": 4
    },
    "thresholds": {
      "contextWarning": 70,
      "contextCompactSuggestion": 80,
      "contextCritical": 85,
      "ralphWarning": 7
    }
  }
}

故障排查

如果 HUD 未显示：

1. 运行 /oh-my-claudecode:hud setup 自动安装配置
2. 重启 Claude Code
3. 如仍有问题，运行 /oh-my-claudecode:omc-doctor 诊断

10.4 会话监控与日志

• 会话摘要: .omc/sessions/*.json
• 重放日志: .omc/state/agent-replay-*.jsonl
• 实时 HUD 渲染: omc hud

---

11. 通知与集成

11.1 通知标签配置

配置 stop 回调发送会话摘要时要 @ 谁：

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

# Discord
omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678,role:987654321098765432"

# Slack
omc config-stop-callback slack --enable --webhook <url> --tag-list "<!here>,<@U1234567890>"

11.2 标签规则

平台	支持格式
Telegram	alice → @alice
Discord	@here, @everyone, 纯数字用户 ID, role:<id>
Slack	<@MEMBER_ID>, <!channel>, <!here>, <!everyone>, <!subteam^GROUP_ID>

11.3 OpenClaw 集成

将 Claude Code 会话事件转发到 OpenClaw 网关：

快速设置:

/oh-my-claudecode:configure-notifications
# → 提示时输入 "openclaw" → 选择 "OpenClaw Gateway"

手动设置: 创建 ~/.claude/omc_config.openclaw.json

11.4 支持的钩子事件

事件	触发时机	主要模板变量
session-start	会话开始时	{{sessionId}}, {{projectName}}, {{projectPath}}
stop	Claude 响应完成时	{{sessionId}}, {{projectName}}
keyword-detector	每次提交提示词时	{{prompt}}, {{sessionId}}
ask-user-question	Claude 请求用户输入时	{{question}}, {{sessionId}}
pre-tool-use	工具调用前	{{toolName}}, {{sessionId}}
post-tool-use	工具调用后	{{toolName}}, {{sessionId}}

---

12. 最佳实践

12.1 任务委派原则

1. 多文件更改 → 委派给专业智能体
2. 简单操作 → 直接处理
3. 复杂推理 → 使用 Opus 模型
4. 快速查找 → 使用 Haiku 模型

12.2 执行模式选择

场景	推荐模式
新功能开发	autopilot 或 team
Bug 修复	ralph
批量修改	ulw
需求不明确	deep-interview
架构决策	ultrathink 或 architect

12.3 技能管理建议

1. 项目级技能 放在 .omc/skills/ 与团队共享
2. 个人通用技能 放在 ~/.omc/skills/
3. 定期运行 /learner 提取新模式
4. 使用 /skill list 检查现有技能

12.4 提交协议

使用 git trailers 保留决策上下文：

fix(auth): prevent silent session drops

Constraint: Auth service does not support token introspection
Rejected: Extend token TTL to 24h | security policy violation
Confidence: high
Scope-risk: narrow
Directive: Error handling is intentionally broad
Not-tested: Auth service cold-start latency >500ms

---

13. 常见问题

Q1: 如何更新 OMC？

/plugin marketplace update omc
/omc-setup

Q2: 更新后出现问题怎么办？

/omc-doctor

Q3: Windows 上如何使用 tmux 功能？

安装 psmux:

winget install psmux

Q4: 如何停止正在运行的 OMC 模式？

stopomc

或

/oh-my-claudecode:cancel

Q5: swarm 关键词还能用吗？

swarm 已弃用，请使用 team 替代。

Q6: 如何查看当前会话状态？

• HUD 状态栏显示实时状态
• 会话摘要: .omc/sessions/*.json
• 运行 omc hud 查看实时渲染

Q7: 多 AI 编排是必需的吗？

不是。Gemini CLI 和 Codex CLI 是可选的，OMC 没有它们也能完整运行。

---

14. 附录

14.1 环境变量

变量	说明
DISABLE_OMC	禁用 OMC
OMC_SKIP_HOOKS	跳过指定钩子（逗号分隔）
OMC_OPENCLAW=1	启用 OpenClaw
OMC_OPENCLAW_DEBUG=1	启用 OpenClaw 调试日志
OMC_OPENCLAW_CONFIG	覆盖 OpenClaw 配置文件路径

14.2 工作树路径

路径	用途
.omc/state/	状态存储
.omc/state/sessions/{sessionId}/	会话数据
.omc/notepad.md	笔记
.omc/project-memory.json	项目记忆
.omc/plans/	计划文档
.omc/research/	研究文档
.omc/logs/	日志文件
.omc/skills/	项目技能
~/.omc/skills/	用户技能

14.3 相关链接

• 官方网站: https://yeachan-heo.github.io/oh-my-claudecode-website
• GitHub 仓库: https://github.com/Yeachan-Heo/oh-my-claudecode
• npm 包: https://www.npmjs.com/package/oh-my-claude-sisyphus
• Discord 社区: https://discord.gg/PUwSMR9XNk
• 赞助支持: https://github.com/sponsors/Yeachan-Heo

14.4 可选 AI 提供商

提供商	安装	功能
Gemini CLI	npm install -g @google/gemini-cli	设计审查、UI 一致性（1M token 上下文）
Codex CLI	npm install -g @openai/codex	架构验证、代码审查交叉检查

费用估算: 3 个 Pro 计划（Claude + Gemini + ChatGPT）约 $60/月。

---

结语

Oh-My-ClaudeCode 的目标是将 Claude Code 的能力最大化，通过多智能体编排、智能模型路由和技能学习系统，让开发者能够更高效地完成复杂任务。

记住：零学习曲线，最大能力。 开始使用 OMC，专注于你想构建什么，而不是如何构建。

---

本手册基于 OMC v4.9.3 版本编写。如有更新，请参考官方文档。