面向读者：

• 日常使用 Claude Code 的开发者
• 希望用多 Agent 编排提升研发效率的工程师 / 研究人员
• 对 AI 工具链与自动化感兴趣的技术爱好者

本文围绕 Oh My ClaudeCode（OMC）的安装与使用展开，目标是：

• 帮你厘清 OMC 在工具链中的角色
• 根据不同工作流，选出最适合你的安装方式
• 在理解原理的基础上，给出可复制的实战安装与排错路径

---

Pre

OMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”：oh-my-claudecode 深度解析与实战指南

OMC - 02 五分钟起步，走向多智能体协作：深入解析 oh-my-claudecode 快速开始与架构设计

---

一、OMC 是什么：给 Claude Code 装上一套「多 Agent 引擎」

OMC（Oh My ClaudeCode）是一套围绕 Claude Code 构建的多 Agent 编排系统。
它并不是另一个聊天机器人，而是给 Claude Code 增加了这些能力：

• 多个专用 Agent 的协同处理（编码、审查、调试、研究等）
• 团队流水线式的编排模式（如多模型并行评审）
• 会话内技能（斜杠命令）与 Hook 自动化（如自动跑脚本、同步状态）
• 支持跨供应商（Claude / Gemini / Codex 等）的综合分析与结果交叉验证（可选安装多家 CLI）

更形象一点：

如果说 Claude Code 是 IDE 里的「AI 伙伴」，那 OMC 就是一套给 AI 伙伴装上的 任务分发系统 + 工作流程引擎 + 外挂工具系统。

OMC 通过两种界面形态提供能力：

• Claude Code 插件：面向「编辑器内」的交互体验
• 终端 CLI：面向 Shell、自动化脚本和批处理场景

大多数开发者会选择插件 + CLI 双安装，兼顾日常对话与自动化。

---

二、安装前的准备：环境与依赖一览

在安装 OMC 之前，推荐先做一次「前置条件体检」。

1. 必要条件检查

依赖项	要求 / 说明
Claude Code	必须已安装，详见 Anthropic 的官方文档
身份验证	Claude Max/Pro 订阅 或 配置 ANTHROPIC_API_KEY 环境变量
Node.js	版本 ≥ 20.0.0（用于终端 CLI 和插件 Hook）
tmux	用于 omc team 团队编排及速率限制检测（可选但强烈推荐）

对于使用团队编排、终端自动化的用户，Node.js + tmux 基本属于「必装组合」。

2. 各平台 tmux 安装速查表

OMC 的多 Agent 团队模式与速率限制处理依赖 tmux：它负责在终端中批量拉起和管理多个 CLI 会话。

平台	安装命令
macOS	brew install tmux
Ubuntu / Debian	sudo apt install tmux
Fedora	sudo dnf install tmux
Arch	sudo pacman -S tmux
Windows (WSL2)	sudo apt install tmux（在 WSL 内执行）
Windows 原生	winget install psmux（使用 psmux 替代）

在 Windows 原生环境下，OMC 使用 Node.js Hook（.mjs）并通过 psmux 实现类似 tmux 的能力，因此标记为「实验性支持」。

3. 可选：多 AI 供应商 CLI

OMC 只依赖 Claude 即可工作，但如果你希望做到跨模型交叉验证与综合分析，可以额外安装其他厂商 CLI。

供应商	安装命令	用途示例
Gemini CLI	npm install -g @google/gemini-cli	设计审查、UI 一致性检查，支持超长上下文（百万 token 级）
Codex CLI	npm install -g @openai/codex	架构验证、代码审查结果交叉核对

这类组合在「系统级重构」「复杂评审」场景会非常有价值：不同模型的结果可以互相验证，降低单模型失误的风险。

---

三、理解 OMC 的双界面：插件 vs CLI

OMC 的设计理念之一，是把「对话中的智能」和「Shell 里的自动化」清晰拆开。

1. 两种界面一览

维度	Claude Code 插件	终端 CLI（npm 包）
包名	oh-my-claudecode@omc	oh-my-claude-sisyphus
提供能力	会话内技能、Agent、Hook、HUD、MCP 服务端、斜杠命令	Shell 命令：omc setup / team / ask / doctor / autoresearch 等
安装方式	通过 Claude Code 插件市场	npm i -g oh-my-claude-sisyphus@latest
典型场景	IDE 内编程、讨论、调试、交互式工作流	终端批处理、CI 脚本、自动化团队编排

插件负责把多 Agent 能力嵌入 Claude Code，会话内完成 Agent 调度、Hook 执行、状态展示等。
CLI 则偏向工程化：一条命令就能在 tmux 里拉起一组模型、执行长时间研究任务、或者进行环境诊断。

2. 插件与 CLI 如何协同

• CLI 会自动检测插件是否已安装，避免重复注册技能。
• 插件侧的斜杠命令，如 /autopilot、/ralph、/ultrawork、/team，聚焦交互式场景。
• CLI 提供 omc team / omc autoresearch / omc doctor 等命令，更适合在终端脚本中被调用。

这意味着你可以：

• 在 Claude Code 里用 /team 发起智能协作式代码评审
• 在终端通过 omc team ... 批量跑多模型测试，把结果写入日志和报告文件

---

四、安装方式一：Claude Code 插件（推荐）

这一方式是绝大多数用户的首选，优点是：

• 与 Claude Code 深度集成
• 自动处理 Agent / Hook / 技能注册
• 支持完整的会话内体验（HUD、MCP、斜杠命令等）

1. 标准安装流程

以下步骤均在 Claude Code 内完成：

第 1 步：添加市场源

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

第 2 步：安装插件

/plugin install oh-my-claudecode

第 2b 步（可选 / 推荐）：安装终端 CLI

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

第 3 步：运行初始设置

在 Claude Code 中执行任一命令：

setup omc
# 或
/oh-my-claudecode:omc-setup

完成后，插件会自动完成：

• Agent 定义加载
• Hook 脚本注册
• 技能与命令发现
• 配置文件写入与初始化

2. 设置范围：项目级 vs 全局

安装完毕后，需要决定 OMC 的生效范围：

范围类型	命令	配置文件位置	作用范围
项目本地（推荐）	/oh-my-claudecode:omc-setup --local	./.claude/CLAUDE.md	仅当前项目
全局	/oh-my-claudecode:omc-setup	~/.claude/CLAUDE.md	所有项目的 Claude Code 会话

关键点：

• 项目级配置 优先于 全局配置，如果两者同时存在，将以项目本地的 ./.claude/CLAUDE.md 为准。
• 修改全局配置前，会有明确确认提示；如果选择「保留模式」，普通 claude 继续使用原有基础配置，而通过 omc 入口则加载伴随配置。

推荐实践：

• 单一项目尝试：先用项目本地配置，避免影响其他工程。
• 确认稳定后，再酌情使用全局配置，把常用 Agent / Hook 能力推广到所有项目。

3. 验证安装：用 omc-doctor 做健康检查

安装和设置完成后，建议立刻做一次诊断：

/oh-my-claudecode:omc-doctor

该命令会从五个维度进行检查：

检查项	内容说明
依赖项	必要包是否已安装
配置	配置文件语法与路径是否正确
Hook	Hook 脚本是否注册且可执行
Agent	所有 Agent 定义是否可用
技能	技能注册是否完整

如果你在后续更新或改配置后遇到异常，也可以再次运行此命令作为首选排错手段。

---

五、安装方式二：终端 CLI（npm 全局安装）

这一方式适合有如下需求的开发者：

• 需要在 Shell / CI 中调用 omc 完成自动化工作
• 希望把多 Agent 工作流整合进现有脚本体系
• 偏好命令行驱动而不是纯会话式交互

1. 安装命令

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

安装完成后，会生成三个入口命令：omc、omc-cli、oh-my-claudecode，它们都指向 bridge/cli.cjs 中的统一 CLI 运行时。

2. CLI 与会话内技能的对应关系

功能类型	终端 CLI 调用示例	会话内对应命令
初始设置	omc setup	/setup 或 /omc-setup
指定供应商提问	omc ask codex "review this"	/ask codex "review this"
团队编排	omc team 2:codex "task"	/team 3:executor "task"
Autopilot / Ralph / Ultrawork	——（仅会话内支持）	/autopilot、/ralph、/ultrawork
自动研究	omc autoresearch ...	/deep-interview --autoresearch ...
诊断	omc doctor	/oh-my-claudecode:omc-doctor

两者的关系不是替代，而是互补：

• 当你在编辑器里交互式调试时：更多用会话内斜杠命令
• 当你在终端批量运行任务时：更多用 omc 命令行接口

3. 团队编排的两种运行时

需要特别注意的是：omc team 与 /team 的执行环境差异很大：

• omc team：

  • 在 tmux 中创建多个窗格
  • 每个窗格运行 Codex、Gemini 或 Claude CLI
  • 偏向「一键拉起一组模型并行工作」的终端场景

• /team：

  • 完全基于 Claude Code 内建的团队工作流
  • 更适合在编辑器中进行多 Agent 协作对话

选择时可以按「是否要离开 IDE」来区分：

• 不离开：用 /team
• 想把结果写入日志/文件/CI：用 omc team

---

六、安装方式三：本地开发检出（面向贡献者）

如果你希望参与 OMC 开发、测试未发布功能，或者通过 git worktree 做多版本共存，本地检出安装更合适。

1. 选项 A：本地市场注册

适合希望沿用现有插件市场机制，但指向本地代码目录的场景。

典型流程：

# 1. 将本地检出注册为市场
claude plugin marketplace add /path/to/oh-my-claudecode

# 2. 从本地市场安装
claude plugin install oh-my-claudecode@oh-my-claudecode

# 3. 在 Claude Code 内运行设置
/setup

# 4. 重启 Claude Code

2. 选项 B：使用 --plugin-dir 直接加载

如果你希望完全跳过市场缓存，直接从本地文件系统读取：可以采用 --plugin-dir 模式。

两种常见写法：

# 使用 omc 入口
omc --plugin-dir /path/to/oh-my-claudecode setup --plugin-dir-mode

或手动导出环境变量，然后直接调用 Claude CLI：

export OMC_PLUGIN_ROOT=/path/to/oh-my-claudecode
claude --plugin-dir /path/to/oh-my-claudecode omc setup --plugin-dir-mode

3. 开发者工作流与热重载注意事项

插件市场系统会将插件内容复制并缓存到 ~/.claude/plugins/cache/，不会自动感知源码目录的变更。

如果你通过「本地市场」方式安装，每次修改代码后的常见流程是：

npm run build                               # 1. 构建 TypeScript 变更
claude plugin marketplace update oh-my-claudecode   # 2. 刷新缓存
claude plugin update oh-my-claudecode@oh-my-claudecode  # 3. 更新插件
/setup                                      # 4. 重新运行设置
# 5. 手动重启 Claude Code

而在 --plugin-dir 模式下，可以跳过第 2、3 步，直接：

• 构建（npm run build）
• 重新运行 setup 命令
• 重启 Claude Code

对于频繁调试插件行为的贡献者来说，--plugin-dir + 热重载无疑是更高效的路径。

---

七、三种安装方式的横向对比与选型建议

从工程实践的角度，选择哪一种安装方式，很大程度上取决于你的角色和日常工作流。

1. 安装方式对比表

评估维度	插件（市场安装）	npm CLI	本地检出
上手难度	初级	初级	高级
更新方式	每 24 小时自动检查	手动 npm i -g ...@latest	手动 git pull + 构建
会话内技能	✅ 完整	✅ 完整（需执行 omc setup）	✅ 完整
Shell 命令（omc）	❌（需单独 npm 安装）	✅	✅
热重载能力	❌	❌	✅（配合 --plugin-dir）
配置隔离	插件缓存目录实现隔离	~/.claude/agents/、commands/	直接以文件系统为源
适用人群/场景	绝大多数日常用户	自动化、脚本驱动、CI 集成	贡献者、测试人员、深度自定义

2. 典型场景与推荐组合

• 日常开发者：

  • 安装方式：插件（市场安装）
  • 可选：再加一份 npm CLI，方便有需要时在终端使用 omc
  • 部署建议：项目级配置优先

• 自动化 / 平台工程师：

  • 安装方式：插件 + npm CLI
  • 用插件保证开发体验，用 CLI 把 OMC 串进 CI/CD 和自动化流水线

• OMC / AI 工具链贡献者：

  • 安装方式：本地检出 + --plugin-dir
  • 结合热重载与多分支工作流，高频迭代插件功能

---

八、平台兼容性与实际使用注意事项

不同平台对 OMC 的支持程度略有差异，尤其是在 Hook 类型与 tmux 依赖上。

1. 平台支持矩阵

平台	插件安装支持	Hook 形式	备注说明
macOS	✅ 完全支持	Bash .sh	推荐主力平台之一
Linux	✅ 完全支持	Bash .sh	服务端 / 开发机场景的优先选择
Windows (WSL2)	✅ 支持	Bash .sh	在 WSL 内安装 tmux 即可
Windows 原生	⚠️ 实验性支持	Node.js .mjs	使用 psmux 替代 tmux，适合尝鲜和轻度使用

如果你在企业环境中准备大规模推广：

• 开发机环境建议统一在 macOS / Linux
• Windows 用户优先采用 WSL2 + tmux 方案

2. Hook 与 tmux 的实际影响

• 对于只用简单会话内技能的用户，即便暂时没有 tmux，也可以先跑起来 OMC 的大部分功能。
• 一旦涉及到 omc team 或复杂并行编排，需要确保 tmux 或 psmux 正常可用。

---

九、更新、自动更新与卸载：生命周期管理

工具链一旦深入进项目，更新策略就会直接影响稳定性与安全性。OMC 在更新与卸载方面提供了完整路径。

1. 更新策略

根据不同安装方式，更新命令分别为：

安装方式	更新方式
插件（市场安装）	/plugin marketplace update omc 然后执行 /setup
npm CLI	npm i -g oh-my-claude-sisyphus@latest
本地检出	git pull → npm run build → 再次运行设置

此外，OMC 内置了一个静默自动更新系统：

• 使用并发安全的锁机制，避免多进程抢占更新
• 每 24 小时最多检查一次最新版本

实践建议：

• 在任何插件更新之后，重新执行一次 /oh-my-claudecode:omc-setup，确保最新配置生效。
• 若更新后出现异常，优先运行 /oh-my-claudecode:omc-doctor 做诊断。

2. 卸载与手动清理

如果需要从系统中移除 OMC，可以按以下步骤进行。

插件卸载：

/plugin uninstall oh-my-claudecode@oh-my-claudecode

npm CLI 卸载：

npm uninstall -g oh-my-claude-sisyphus

深度手动清理：

OMC 提供了一个卸载脚本，用于清理 settings.json 中的 Agent、命令、技能、Hook、状态文件及 Hook 配置等信息。

但有几项不会自动删除，如果需要进一步清理，可手动执行：

项目	手动删除命令
全局 CLAUDE.md	rm ~/.claude/CLAUDE.md
settings.json 备份文件	rm ~/.claude/settings.json.bak
项目状态（计划、记事本等）	rm -rf .omc

对于在多项目中广泛使用 OMC 的用户，建议保留至少一个项目的状态目录 .omc 以留存历史上下文，特别是在重构类长期任务中。

---

十、从安装到实践：如何高效开始使用 OMC

完成安装并通过 omc-doctor 验证之后，接下来就是让它真正融入你的开发工作流。

1. 建议的阅读与上手路径

官方提供了明确的进阶路径，可以帮助你快速从「能用」过渡到「用好」：

1. 快速入门

   • 目标：在约 60 秒内跑通第一次 Autopilot 会话
   • 场景示例：
     • 给某个模块编写单元测试
     • 基于需求文档生成接口定义和基础实现

2. 会话内技能参考

   • 完整列出所有可用斜杠命令及参数
   • 这是把 OMC 真正当成「体系」来使用的关键文档

3. 架构概览

   • 讲清楚 Agent、Hook、技能流水线分别负责什么
   • 理解之后，就能自信地做更深度的定制和扩展

2. 实战示例：给现有项目加一层「智能工作流」

假设你有一个已有的微服务项目，希望借助 OMC 做以下事情：

• 自动梳理代码结构并输出架构图草稿
• 对关键模块做跨模型代码审查（Claude + Codex）
• 对每个 PR 给出统一风格的 Review 建议

一个典型的落地流程可以是：

1. 在项目根目录执行项目级 omc-setup：

   • ./.claude/CLAUDE.md 绑定该项目的 Agent 配置与 Hook 逻辑

2. 安装 Gemini CLI 与 Codex CLI（可选，但推荐）：

   • 让 OMC 在关键审查阶段启用多模型交叉分析

3. 在 Claude Code 内配置常用斜杠命令（例如自定义技能）：

   • /team：拉起多 Agent 对当前 Diff 做审查
   • /autopilot：针对单一复杂需求启动长流程分析与实现

4. 在 CI 环境中加入 omc 命令：

   • 为每个 PR 生成 AI Review 报告
   • 对核心路径增加自动化安全检查与风格统一检测

通过这种组合，你可以让「AI 辅助」从临时性、聊天型的使用模式，升级为稳定、可复制、可审计的工程实践。

---

十一、总结：把 OMC 当作「AI 工作流引擎」来用

回顾全文，OMC 的核心价值可以概括为三点：

1. 从单 Agent 到多 Agent 协作

   • 不再是「一个 AI 帮我写代码」，而是「一组专长各异的 Agent 协同完成任务」。

2. 从交互式对话到工程化工作流

   • 在 Claude Code 内，你可以通过斜杠命令完成复杂交互；
   • 在终端与 CI 中，则通过 omc 把这些能力固化为流水线的一部分。

3. 从工具到平台级扩展能力

   • 通过 Hook、技能系统、MCP 工具服务端等机制，你可以把 OMC 和现有基础设施打通：包括日志、监控、知识库，以及各种内部系统。

在安装选择上，如果只需要一个结论，可以是：

• 只想先用用看：
  直接使用「方式一：Claude Code 插件」，项目级配置即可。

• 已经在写大量自动化脚本 / 做平台工程：
  插件 + npm CLI 双栈，并把 omc 纳入你的 CI / 运维流水线。

• 对 OMC 本身也想改造与贡献：
  使用本地检出 + --plugin-dir 的高级模式，以更快地迭代和调试。

一旦将 OMC 稳定集成进开发流程，你会发现：

AI 不再只是临时「帮我写点代码」，而是渗透进了需求分析、设计评审、编码、测试、上线、回溯等整个生命周期——并且在每一环节，都能通过多 Agent 协同和跨模型验证，让工程质量有一个「可度量」的跃迁。

如果你已经完成安装和基本验证，下一步可以直接从快速入门与会话内技能参考开始，将 OMC 真正用在自己的项目里。随着实际场景的积累，你也可以逐步尝试编写自定义技能和 Hook，把它打造成项目团队的专属 AI 工作流中枢。