oh-my-claudecode 深度指南
一篇面向编程初学者的 oh-my-claudecode 入门与参考文章。本文主要依据官方 README 和
docs/REFERENCE.md整理，凡是版本变化较快的命令和目录，都会明确注明“以官方 README 为准”。
导语
oh-my-claudecode 可以理解成 Claude Code 的多智能体编排层。你不一定要先学会很多复杂命令，只要把它安装进 Claude Code，就能开始使用它提供的代理、技能、钩子和自动化工作流。
它最有代表性的特点是“把复杂的事情藏起来”：新手可以只记住几个高频命令，进阶用户则可以继续挖掘 ask、team、session、deep-interview、autopilot 这类流程化能力。
官方地址
| 类型 | 地址 |
|---|---|
| 官网 | https://ohmyclaudecode.com/ |
| 官方 GitHub | https://github.com/Yeachan-Heo/oh-my-claudecode |
| 参考文档 | https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/docs/REFERENCE.md |
是什么
根据官方文档，oh-my-claudecode 是一个面向 Claude Code 的多 Agent 编排系统。它的核心不是单个功能，而是一整套协作机制：
agents：分工明确的代理skills：可复用的工作流定义hooks：在会话生命周期中自动执行的脚本slash commands：在 Claude Code 里直接调用的命令CLI：在终端里运行的omc ...命令
如果说普通 Claude Code 更像“一个聪明的对话框”，那 OMC 更像“一个带分工的研发系统”。
适用场景
这个项目适合下面几类场景：
- 你想让 Claude Code 自动做任务分派，而不是每一步都手工控制。
- 你想要固定的工作流，比如问答、规划、执行、复盘、清理。
- 你想把多个模型或多个 agent 串成一条流程。
- 你希望会话结束后还能保留上下文、结果和中间产物。
- 你想研究 Claude Code 插件、hooks、skills、agents 的实际组合方式。
安装准备
开始前先确认三件事：
- 你已经安装 Claude Code
- 你准备采用官方推荐的插件方式，还是兼容的 CLI/runtime 方式
- 你知道自己要装到项目级还是全局级
官方 REFERENCE.md 里有一个很重要的前提：当前正式推荐的是 Claude Code Plugin 安装方式。npm/bun/curl 之类的直装方式在文档中被标为 deprecated，不建议新手优先走。
安装方式
方式一：Claude Code 插件安装
这是官方推荐的主路径。注意这两条命令要一条一条输入，不要一次性粘贴两行。
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode安装后，OMC 会通过 Claude Code 的插件系统提供命令、hooks 和相关资源。
方式二：CLI / runtime 路径
官方 README 仍保留了 CLI/runtime 路径，适合已经明确知道自己在做什么的人：
npm i -g oh-my-claude-sisyphus@latest然后在会话里或终端里继续执行设置：
# 在 Claude Code / OMC 会话中
/setup
/omc-setup
# 在终端中
omc setup如果你是从本地 checkout 或带 --plugin-dir 的方式运行，还要按官方说明加上 --plugin-dir-mode，或者设置 OMC_PLUGIN_ROOT。这部分细节变化较快，以官方 README 和 REFERENCE 为准。
插件安装和手动安装差异
| 对比项 | 插件安装 | 手动 / CLI 安装 |
|---|---|---|
| 官方推荐程度 | 高 | 低，更多是兼容或开发路径 |
| 适合人群 | 大多数 Claude Code 用户 | 需要终端控制、开发、调试的人 |
| 命令入口 | /oh-my-claudecode:... | omc ... |
| 安装复杂度 | 低 | 中到高 |
| 目录接管方式 | 插件系统自动处理 | 需要关注 --plugin-dir、--plugin-dir-mode、配置文件位置 |
| 版本风险 | 较低 | 较高，容易受兼容性影响 |
对新手来说，直接走插件安装更稳。CLI/runtime 路径更适合高级用户和本地开发者。
目录结构
官方文档涉及的目录和文件比较多，这里只整理最关键的一层，便于你建立心智模型：
oh-my-claudecode/
├── docs/
│ └── REFERENCE.md
├── .claude/
│ └── CLAUDE.md
├── .omc/
│ ├── artifacts/
│ ├── sessions/
│ ├── state/
│ └── skills/
├── .agents/
│ └── skills/
├── hooks/
├── agents/
├── commands/
├── skills/
└── settings.json需要注意的是，这不是一个“只放命令”的项目。它会同时影响：
- 你的 Claude Code 会话行为
- 项目级和全局级的
CLAUDE.md - skills 和 agents 的加载
- hooks 的自动执行
- 会话产物和状态记录
具体目录是否都存在，取决于你采用的安装方式和版本，以官方 REFERENCE 为准。
命令大全
下面这张表整理了官方 README 和 REFERENCE 中最常见、最适合新手先记住的命令。个别命令在不同版本里可能扩展或变化，遇到不确定情况请回到官方文档确认。
| 命令 | 作用 | 示例 | 注意事项 |
|---|---|---|---|
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode | 添加 OMC 仓库到 Claude Code marketplace | 同左 | 这是一条 Claude Code 命令，要单独输入 |
/plugin install oh-my-claudecode | 安装插件 | 同左 | 要先完成 marketplace 添加 |
/setup | 在会话里执行基础设置 | /setup | 官方 README 提到它和 /omc-setup 都可用，具体行为以版本为准 |
/omc-setup | 初始化 OMC 配置 | /omc-setup | 支持项目级或全局级配置，建议先看 README |
omc setup | 在终端里初始化 | omc setup | CLI/runtime 路径用户常用 |
omc ask claude "review this patch" | 把问题转给 Claude 执行 advisor 流程 | omc ask claude "review this patch" | 也支持 codex、gemini，以官方 README 为准 |
omc ask codex "review this patch from a security perspective" | 使用 Codex 作为 advisor | 同左 | 适合多模型对照 |
omc team 2:codex "review auth flow" | 启动团队式编排 | 同左 | team 的行为和运行环境有关，参考 REFERENCE |
omc team status review-auth-flow | 查看 team 任务状态 | 同左 | 适合追踪运行中的任务 |
omc session search "team leader stale" | 搜索历史会话 | 同左 | 默认是当前项目/工作区范围 |
/oh-my-claudecode:autopilot <task> | 自动执行完整任务 | /oh-my-claudecode:autopilot "build a REST API" | 适合从想法到实现的一条龙流程 |
/oh-my-claudecode:deep-dive <problem> | 先追踪再深度访谈 | /oh-my-claudecode:deep-dive "why tests are failing" | 适合问题分析和需求澄清 |
/oh-my-claudecode:deep-interview <idea> | 苏格拉底式需求访谈 | /oh-my-claudecode:deep-interview "I want to build a task app" | 很适合还没想清楚需求的新手 |
/oh-my-claudecode:ai-slop-cleaner <target> | 清理低质量输出 | /oh-my-claudecode:ai-slop-cleaner src/app.ts | 可加 --review 做只读审查流程 |
/oh-my-claudecode:omc-doctor | 排查安装和配置问题 | /oh-my-claudecode:omc-doctor | 官方 REFERENCE 里的重要排错入口 |
/oh-my-claudecode:hud setup | 配置 HUD 状态栏 | /oh-my-claudecode:hud setup | 适合需要实时状态反馈的人 |
/plugin uninstall oh-my-claudecode@oh-my-claudecode | 卸载插件 | 同左 | 卸载前先确认是否需要保留本地配置 |
/oh-my-claudecode:ultrawork <task> | 高并行工作流 | /oh-my-claudecode:ultrawork "refactor authentication" | 属于高阶工作流，是否可用以官方 README 为准 |
/oh-my-claudecode:trace | 追踪式分析 | /oh-my-claudecode:trace | 版本变化快，先看官方文档 |
推荐工作流
对初学者来说，建议按这个顺序上手：
- 先用
/plugin marketplace add ...和/plugin install ...完成插件安装。 - 再执行
/omc-setup，先做项目级配置，熟悉后再考虑全局配置。 - 用
/oh-my-claudecode:deep-interview或/oh-my-claudecode:ask试一次最小流程。 - 需要自动执行时，再用
/oh-my-claudecode:autopilot。 - 需要多人/多代理协作时，再看
omc team。 - 有疑难问题时，优先跑
/oh-my-claudecode:omc-doctor。
如果你是本地开发者，或者在研究插件源码，可以再加上 omc --plugin-dir <path> 和 --plugin-dir-mode 的流程。
安全建议
OMC 的能力很强，所以更要谨慎：
- 官方已经明确说了，插件方式是主路径，其他安装方式不要默认当成长期方案。
- 不要把两条 Claude Code slash 命令一次性粘贴执行，官方 README 已提醒要一条一条输入。
- 不要随便把
hooks/hooks.json手动塞进settings.json，这类行为在新版 Claude Code 里容易造成重复加载。 - 如果你已经有自己的
CLAUDE.md，优先考虑项目级配置，避免直接覆盖全局配置。 - 不要把真实 API key 写进示例配置里。
- 不要在没有理解
--plugin-dir-mode的情况下同时混用 plugin 安装和本地开发目录。
排错
1. 命令找不到
优先重新跑一次设置：
/oh-my-claudecode:omc-setup如果你走的是终端路径，就运行：
omc setup2. hooks 没有执行
官方 REFERENCE 提到需要检查 hook 权限。常见处理方式是：
chmod +x ~/.claude/hooks/**/*.sh3. 代理没有按预期分派
先确认你的 CLAUDE.md 是否真的被加载了。官方文档建议检查：
./.claude/CLAUDE.md~/.claude/CLAUDE.md
4. LSP 工具不好使
官方 REFERENCE 提到可以安装语言服务器，例如：
npm install -g typescript-language-server如果你用的是其他语言栈，也要按对应语言服务器处理。
5. Token 或上下文压力太大
官方建议优先使用 OMC 的命名空间命令，也就是尽量走：
/oh-my-claudecode:而不是完全手动组织复杂流程。
6. 更新后行为变化很大
先看官方 README 和 REFERENCE.md，再决定是否需要：
/oh-my-claudecode:omc-doctor或者重新执行 marketplace update 和 setup 流程。因为这个项目更新较快，命令和细节经常调整。
总结
oh-my-claudecode 的价值在于把 Claude Code 从“单点对话工具”升级为“多代理协作系统”。如果你希望 AI 不只是回答问题，而是能协助规划、执行、追踪、搜索和复盘，它会非常有用。
对新手来说，记住两个原则就够了：
- 优先走官方推荐的插件安装。
- 遇到不确定的命令，直接回官方 README 和
REFERENCE.md。