oh-my-claudecode 部署与技巧：32 个专业 Agent 替你打工，效率翻倍

难度: 中级 | 时长: 30 分钟 | 收获: 掌握多 Agent 编排、零配置部署、团队流水线搭建

目标读者: 已在使用或计划使用 Claude Code 的开发者，想进一步提升 Agent 协作效率的团队。

核心依赖: Node.js ≥18、tmux（跨平台可选）、Claude Code CLI

1. 项目简介

Claude Code 本身已经很强大了，但单个 Agent 在面对复杂多模块项目时往往力不从心——你不得不反复在多个对话窗口间切换，或者手动协调代码审查、架构设计和测试验证。

oh-my-claudecode（以下简称 OMC）就是来解决这个问题的。它是 Claude Code 的多智能体编排层，核心理念是：

Don't learn Claude Code. Just use OMC.

简单来说，你只需要用自然语言描述你想要什么，OMC 会自动调度 32 个专业 Agent、选择合适的模型（Haiku / Sonnet / Opus）、并行处理任务，直到验证通过才结束。整个过程零配置，不需要记忆任何命令。

项目地址: https://github.com/Yeachan-Heo/oh-my-claudecode

NOTE

npm 包名和仓库名不一致，仓库叫 oh-my-claudecode，但发布的 npm 包叫 oh-my-claude-sisyphus。安装时别找错包名了。

2. 核心特性一览

2.1 零配置开箱即用

不需要写任何 YAML 或者 JSON 配置，安装后直接说人话就能跑。智能默认值覆盖了 90% 的场景。

2.2 32 个专业 Agent

每个 Agent 都有明确的职责范围，OMC 会根据任务类型自动路由到最合适的 Agent：

Agent	定位	推荐模型
`architect`	系统架构设计	Opus
`planner`	任务拆解与规划	Opus
`executor`	代码实现（默认）	Sonnet
`code-reviewer`	代码审查	Opus
`security-reviewer`	安全审计	Sonnet
`test-engineer`	自动化测试	Sonnet
`explorer`	代码库探索	Haiku
`analyst`	深度分析	Opus
`debugger`	Bug 定位修复	Sonnet
`designer`	UI/UX 设计	Sonnet
`writer`	文档撰写	Haiku
`scientist`	数据科学任务	Sonnet
...	...	...

完整列表在 AGENTS.md 中定义。

2.3 智能模型路由

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

Haiku: 简单查找、格式化、轻微文案修改
Sonnet: 标准实现、调试、测试（日常主力）
Opus: 架构设计、安全审查、复杂重构

这样做的好处是成本优化，社区反馈平均节省 30-50% 的 token 消耗。

2.4 自动并行化

独立任务会自动分配到不同 Agent 并行执行，不需要你手动拆解。

2.5 持久化执行（verify/fix 循环）

Ralph 模式下，Agent 完成任务后会自动进入验证循环——如果验证失败，它会自己修复并重跑，直到真正通过为止。

2.6 技能自学习（Learner 系统）

运行过程中遇到过的调试经验会自动提取成可复用的 Skill 文件，放在 .omc/skills/ 下。下次遇到类似问题时自动注入上下文——不用你手动回忆。

2.7 OpenClaw 集成

支持将 Claude Code 会话事件转发到 OpenClaw Gateway，实现 Telegram / Discord 等渠道的自动化通知和远程触发。

3. 完整项目结构

oh-my-claudecode/
├── agents/              # 32 个专业 Agent 定义文件
├── bridge/              # OpenClaw / 第三方桥接
├── docs/                # 架构文档、迁移指南、性能监控
├── examples/            # 示例工作流
├── hooks/               # Claude Code 钩子注入
├── missions/            # 任务定义
├── research/            # 研究模块
├── scripts/             # 工具脚本（OpenClaw Gateway Demo 等）
├── skills/              # OMC 内置 Skill 文件
├── src/                 # 核心源码
├── tests/               # 测试套件
├── CLAUDE.md            # Agent 运行时主配置（OMC 注入给 Claude Code）
├── AGENTS.md            # Agent 目录与描述
└── package.json

对于普通用户来说，日常打交道最多的是：

skills/ — 自定义 Skill 文件
.omc/ — 运行时生成的会话、状态、计划文件

4. 安装与配置

4.1 前置依赖

必须安装：

Claude Code CLI — 需要 Max/Pro 订阅或 Anthropic API Key
Node.js ≥18 — OMC 本身是 TypeScript/npm 项目

可选但强烈推荐：

tmux — omc team 和速率限制自动恢复功能依赖 tmux

各平台安装 tmux：

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Arch
sudo pacman -S tmux

# Windows 原生（推荐）
winget install psmux

# Windows WSL2
sudo apt install tmux

WARNING

Windows 用户推荐安装 psmux，它是 Windows 原生 tmux 实现，不需要 WSL2 也能跑通 OMC 全部功能。

4.2 安装 OMC（两种方式）

方式一：Marketplace 安装（推荐）

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

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

方式二：npm 全局安装

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

安装完成后，OMC 会自动激活，所有 / 命令和魔法关键字即可使用。

4.3 初始化配置

# 在任意目录下运行
/setup
/omc-setup

首次运行会引导你完成：

Claude Code 配置目录确认
OpenClaw Gateway（可选）
tmux 会话检测

如果遇到异常，运行诊断工具：

/omc-doctor

4.4 启用 Team Mode（推荐）

Team Mode 是 OMC v4.1.7 之后的默认编排方式，需要在 Claude Code 配置中启用实验特性：

# 编辑 ~/.claude/settings.json

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

TIP

如果没有开启 Team Mode，OMC 会给出警告并回退到非 Team 执行模式。功能不会完全不可用，但编排能力会降级。

5. 执行模式深度解析

OMC 提供了多种执行模式，适用于不同的任务场景。理解它们的差异是高效使用的关键。

5.1 Team Mode（推荐）⭐

适用场景: 复杂多模块任务，需要架构、编码、审查、测试协同工作。

Team Mode 运行在一条严格流水线上：

team-plan → team-prd → team-exec → team-verify → team-fix（循环）

任务从规划开始，经过产品设计、代码执行、验证，到 fix 阶段如果发现问题会回到执行重新来过。整个过程由 OMC 自动协调，不需要你干预。

基本用法：

/team 3:executor "修复所有 TypeScript 编译错误"

数字 3 表示使用 3 个 executor Agent 并行处理。

CLI 版 tmux Workers（v4.4.0+）：

omc team 2:codex "审查 auth 模块安全性"
omc team 2:gemini "重新设计 UI 组件的可访问性"
omc team 1:claude "实现支付流程"
omc team status auth-review
omc team shutdown auth-review

这些是真正的独立 tmux 进程，执行完成后自动退出，不占用资源。

5.2 Autopilot

适用场景: 明确需求，端到端独立完成一个功能，不需要过多人工介入。

autopilot: build a REST API for managing tasks

Autopilot 模式下，单个 Lead Agent 全程负责从设计到实现，不依赖流水线。

5.3 Ralph（持久化模式）

适用场景: 任务必须完整完成，不能有"部分完成就退出"的情况。

Ralph 模式包含了 Ultrawork 的并行能力，并额外加上 verify/fix 循环：

executor → verify → fix → verify（直到通过）

ralph: 重构 auth 模块，要求所有测试通过

如果你发现 Claude Code 经常在"看起来完成了"但实际没验证的情况下退出，Ralph 是解决方案。

5.4 Ultrawork（最大并行）

适用场景: 大批量修复/重构，需要最快速度。

ulw 修复所有 ESLint 错误
ulw 重命名所有组件为 PascalCase

所有修复并行跑，不等待前一个完成就继续下一个，适合"已知问题清单"的批量处理。

5.5 /ccg 三模型顾问

适用场景: 需要同时获得 Codex 和 Gemini 的视角，再由 Claude 综合。

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

它调用 /ask codex + /ask gemini，Claude 负责最后综合输出。适合后端+前端联审，或者需要多模型交叉验证的场景。

5.6 模式对比速查

模式	并行	验证循环	适用场景
Team	✅ 流水线多 Agent	✅ fix 循环	复杂多模块协作
Autopilot	单 Agent	❌	明确需求快速实现
Ralph	✅ Ultrawork 继承	✅	必须完整交付的任务
Ultrawork	✅ 最大并行	❌	批量修复/重构
/ccg	✅ 三模型同时	❌	架构+UI 联审

6. 实战演示

6.1 场景一：构建 REST API（Team Mode）

假设我们想用 Team Mode 构建一个任务管理 REST API：

/team 2:executor "实现任务管理 REST API，包含 CRUD 四个接口，使用 Express + TypeScript"

OMC 会自动拆解任务：

architect 设计 API 结构和数据模型
executor 并行实现各接口
test-engineer 编写集成测试
code-reviewer 审查代码
verifier 运行测试验证

你只需要等待最终结果。

6.2 场景二：自动修复所有错误（Ultrawork）

ulw 修复所有 TypeScript 类型错误和 ESLint 警告

适合 CI/CD 流水线或者接手老项目时的快速清理。

6.3 场景三：需求不明确时（Deep Interview）

如果你自己也不确定要做什么：

/deep-interview "我想做一个个人博客系统"

Deep Interview 会用苏格拉底式提问帮你澄清需求：目标读者是谁、技术栈偏好、是否需要 CMS、SEO 要求……问清楚再动手，避免做一半返工。

6.4 场景四：多模型交叉审查（/ccg）

/ccg 这个 PR 的后端架构用 Codex 审查，UI 组件用 Gemini 审查

6.5 场景五：速率限制自动恢复

当 Claude API 触发速率限制时：

omc wait          # 查看当前状态和恢复指引
omc wait --start  # 启动自动恢复守护进程
omc wait --stop   # 停止守护进程

TIP

速率限制恢复依赖 tmux 检测会话状态，所以请确保 tmux 已安装并运行正常。

7. 常见问题排查

Q1: `/team` 命令无效，报错 "Team Mode 未启用"

原因: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量未设置。

解决:

# 编辑 ~/.claude/settings.json，加入：
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

重启 Claude Code 会话后生效。

Q2: `omc team` 报 tmux 相关错误

原因: Windows 用户没有安装 tmux，或者 tmux 不在 PATH 中。

解决:

# Windows 原生
winget install psmux

# macOS
brew install tmux

# 验证安装
tmux -V

如果已安装但仍然报错，检查 psmux 的 bin 目录是否加入系统 PATH。

Q3: Marketplace 安装后 OMC 命令不生效

原因: 插件缓存未刷新，或者安装路径不对。

解决:

# 更新 marketplace 克隆
/plugin marketplace update omc

# 重新初始化
/setup

# 运行诊断
/omc-doctor

Q4: Claude Code 提示速率限制但没有自动恢复

原因: omc wait --start 没有执行，或者不在 tmux 会话中运行。

解决:

# 确保在 tmux 会话中执行
tmux new -s omc-watch
omc wait --start

守护进程启动后会在 tmux 后台运行，速率限制恢复后会自动 resume Claude Code 会话。

Q5: 更新 OMC 后出现异常行为

原因: 旧版插件缓存与新版代码不兼容。

解决:

# 如果是 Marketplace 安装：
/plugin marketplace update omc
/setup

# 如果是 npm 安装：
npm i -g oh-my-claude-sisyphus@latest
/omc-doctor

Q6: Skill 文件没有自动注入

原因: Skill 触发词不匹配，或者文件路径放错。

解决:

Skill 文件放在两个位置，优先级不同：

# 项目级别（高优先级）: .omc/skills/
# 用户级别（低优先级）: ~/.omc/skills/

确保 Skill 文件 frontmatter 中的 triggers 数组包含当前对话中的关键词：

---
name: Fix Proxy Crash
description: aiohttp proxy crashes on ClientDisconnectedError
triggers: ["proxy", "aiohttp", "disconnected"]  # 关键词匹配
source: extracted
---

8. 扩展阅读 / 进阶方向

8.1 自定义 Skill 编写

OMC 支持从实际调试经验中提取可复用 Skill：

/learner

提取后生成 .omc/skills/ 下的 YAML 文件。下次遇到类似问题时自动注入，不需要手动 recall。

8.2 OpenClaw 集成

OMC 可以将 Claude Code 会话事件转发到 OpenClaw Gateway，实现远程触发和通知：

# 自动引导配置
/oh-my-claudecode:configure-notifications
# → 选择 "OpenClaw Gateway"

手动配置 ~/.claude/omc_config.openclaw.json：

{
  "enabled": true,
  "gateways": {
    "my-gateway": {
      "url": "https://your-gateway.example.com/wake",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" },
      "method": "POST",
      "timeout": 10000
    }
  },
  "hooks": {
    "session-start": { "gateway": "my-gateway", "instruction": "Session started for {{projectName}}", "enabled": true },
    "stop":          { "gateway": "my-gateway", "instruction": "Session stopping for {{projectName}}", "enabled": true }
  }
}

支持的钩子事件包括：session-start、stop、keyword-detector、ask-user-question、pre-tool-use、post-tool-use。

8.3 通知系统（Telegram / Discord / Slack）

omc config-stop-callback telegram --enable --token <bot_token> --chat <chat_id> --tag-list "@alice,bob"
omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678"

会话结束时自动推送摘要到群组，支持增量更新标签。

8.4 OpenClaw + OMC 协同工作流

结合 OpenClaw 的自动化能力和 OMC 的多 Agent 编排，可以实现：

OpenClaw 监听 Discord/Telegram 消息，触发 Claude Code 会话
OMC 在 Claude Code 中编排 32 个 Agent 完成复杂任务
OpenClaw Gateway 将结果推送回聊天渠道

这样你就有了一个 24 小时在线的多智能体助手，通过日常聊天工具就能指挥。

参考 scripts/openclaw-gateway-demo.mjs 了解如何搭建这套协同架构。

8.5 性能监控与调试

OMC 运行时会在 .omc/ 下生成多类文件：

.omc/sessions/*.json        # 会话摘要
.omc/state/agent-replay-*.jsonl  # 执行回放日志
.omc/plans/                 # 任务计划
.omc/research/              # 研究输出

运行 HUD 查看实时编排状态：

/oh-my-claudecode:hud setup
omc hud

参考链接

项目主页: https://github.com/Yeachan-Heo/oh-my-claudecode
npm 包: https://www.npmjs.com/package/oh-my-claude-sisyphus
完整文档: https://yeachan-heo.github.io/oh-my-claudecode-website
CLI 参考: https://yeachan-heo.github.io/oh-my-claudecode-website/docs.html#cli-reference
Discord 社区: https://discord.gg/PUwSMR9XNk