OMC 实战：19 个 Agent 打造更智能、更可靠、更高效的 Claude Code 工作流

OMC 实战：19 个 Agent 打造更智能、更可靠、更高效的 Claude Code 工作流

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 118 篇，AI 编程最佳实战「2026」系列第 36 篇

大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。

我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

封面图：oh-my-claudecode 核心架构概览

图 1：oh-my-claudecode 核心架构概览

用 Claude Code 写代码的开发者，大概率都撞上过这几个场景：一个涉及 20 多个文件的重构任务，得手动拆成十几次提示，每次都要重新交代上下文；调试一个跨模块的 Bug，单 Agent 来回翻文件，效率还不如自己开 IDE 搜；想让 Claude Code 自动跑完规划→实现→测试→验证的完整流程，结果每一步都要人工介入。

这些问题的根源不是 Claude Code 能力不行。Anthropic 官方博客有一句话把边界说得很清楚：能用单次调用解决就不要用 Workflow，能用 Workflow 就不要上 Agent。 反过来看，当任务复杂到确实需要多 Agent 协作时，原生的单 Agent 模式就捉襟见肘了。

oh-my-claudecode（简称 OMC）就是在这个边界上做文章的。它通过 Hooks → Skills → Agents → State 四层架构，把 Claude Code 从手动指挥一个 Agent 升级为自动协调 19 个专业 Agent。翻了一圈官方文档和源码后，我把这套系统的核心逻辑整理成了这篇文章——从底层机制到架构设计，再到三个高频场景的实战演示。

说明：本文内容基于 oh-my-claudecode（Yeachan-Heo/oh-my-claudecode）源码（v4.14.1）和 Anthropic 官方文档分析整理而成，源码分析基于笔者本地仓库版本，尚未在生产环境中完成全场景验证。文中的配置模板和参数建议仅供参考，实际效果请以你的业务数据和环境测试结果为准。如果有实际使用经验，欢迎在评论区分享交流。

1. Claude Code 的底层运行机制

Claude Code 四层架构图

图 2：Claude Code 四层架构

要理解 OMC 做了什么，先得搞清楚 Claude Code 本身是怎么跑的。

Agentic 工作流

Claude Code 采用工具增强的 Agent 架构，核心是一个多轮推理循环：思考 → 调用工具 → 处理结果 → 继续思考。每一轮循环里，模型会根据当前上下文决定是继续调用工具还是直接输出结果。

根据 CSDN 上的架构分析文章（整理自 Anthropic 官方博客），整个系统分四层：用户界面层（CLI/IDE）→ Claude Code Core（会话管理、权限控制、上下文管理）→ Agent Loop（多轮推理循环）→ LLM 模型层 + 工具系统。

工具系统又分两部分：本地工具（Read/Write/Bash/Grep 等）和 MCP Servers（Context7、Lark Doc 等外部工具服务器）。模型在每一轮循环中可以选择调用哪个工具，Claude Code Core 负责权限检查和工具调度。

简单任务走单 Agent 模式，一次对话搞定。复杂任务时，主 Agent 可以派生子 Agent 来并行处理——这就是 Anthropic 在 2026 年 2 月推出的实验性功能 Agent Teams，采用星形拓扑结构（Star Topology），Leader Agent 协调多个 Expert Agent。

但这里有个关键限制：派生是手动的。你得自己告诉 Claude Code 用子 Agent 做某个任务，而且每个子 Agent 的模型、职责、上下文都得自己管理。更别说子 Agent 之间的协调、状态追踪、错误恢复——这些全靠人肉。

Hooks：零上下文成本的自动化

Hooks 是 Claude Code 一个被严重低估的能力。腾讯云开发者社区有一篇分析文章说得很到位：Hooks 在 Agent 循环外运行，不占用上下文窗口。

这意味着什么？你可以在不消耗任何 token 的情况下，让系统自动响应生命周期事件。比如文件保存后自动跑 linter、危险命令执行前拦截、任务完成时发 Slack 通知。这些操作完全绕过了 Agent Loop，不挤占本就紧张的上下文空间。

Claude Code 原生支持 11-13 个 Hook 生命周期事件，覆盖从 SessionStart（会话开始）到 PreToolUse/PostToolUse（工具使用前后）再到 Stop（Agent 即将停止）和 SessionEnd（会话结束）的完整链路。每个事件都有对应的 JSON 有效负载，携带上下文信息供 Hook 脚本使用。

OMC 正是基于这套 Hook 机制，搭建了 20 个 Hook 脚本拦截这些生命周期事件，实现了智能路由和自动化编排。后面会详细展开。

配置体系

Claude Code 的配置文件分三层：

• 项目级 CLAUDE.md — 通过 /init 生成，放在项目根目录，推荐加入版本控制
• 个人级 CLAUDE.local.md — 个人定制配置，加入 .gitignore
• 全局级 ~/.claude/CLAUDE.md — 对所有项目生效

叠加顺序：项目级 > 父目录 > 子目录 > 全局。Anthropic 官方还提供了工具许可管理的四种方式：会话中始终允许、/permissions 命令、编辑 settings.json、--allowedTools CLI 标志。

这套多层配置和灵活的权限管理，为 OMC 的双层配置和 Agent 委派系统提供了基础。

2. OMC 的架构设计

OMC 四大系统互联流程图

图 3：OMC 四大系统互联流程

OMC 的核心不是堆功能数量，而是在四个系统之间建立了一条清晰的管线：

用户输入 → Hooks（事件检测）→ Skills（行为注入）→ Agents（任务执行）→ State（进度追踪）

四大系统各司其职

Hooks 层是入口。OMC 的 20 个 Hook 脚本拦截 Claude Code 的 11 个生命周期事件。几个关键 Hook 的职责：

整个过程在 Agent 循环外完成，零上下文消耗。你输入 ultrawork fix the API，keyword-detector 检测到关键词后自动激活 ultrawork Skill，然后 Skills 层接管决定执行策略。

Skills 层决定怎么做。31 个 Skill（28 个用户可调用 + 3 个内部管线）按三层组合：

[执行 Skill] + [0-N 个增强技能] + [可选保证层]

执行层负责主任务（default、orchestrate、planner），增强层叠加能力（ultrawork 并行、git-master 自动提交、frontend-ui-ux 前端增强），保证层确保完成（ralph 不验证完不停止）。这个组合公式的设计很灵活——你可以用 default + git-master 做普通开发带自动提交，也可以用 autopilot + ralph 做强力端到端。

Agents 层决定谁来做。19 个专业 Agent 分四个泳道：

critic 这个角色值得一提——它专门在执行前挑毛病，对计划和设计做差距分析。相当于内置了一套红蓝对抗机制：planner 出方案，critic 找漏洞，反复迭代直到方案足够健壮。

State 层负责记住什么。.omc/ 目录下按模式存放状态文件、执行计划、知识便笺和日志：

.omc/
├── state/                    # 按模式的状态文件
│   ├── autopilot-state.json  # autopilot 进度
│   ├── ralph-state.json      # ralph 循环状态
│   └── team/                 # team 任务状态
├── notepad.md                # 抗压缩的记忆便笺
├── project-memory.json       # 跨会话项目知识
├── plans/                    # 执行计划
└── notepads/                 # 按计划的知识捕获
    └── {plan-name}/
        ├── learnings.md      # 模式和成功方法
        ├── decisions.md      # 架构决策
        └── issues.md         # 问题和阻碍

notepad.md 的设计值得多说一句——它抗上下文压缩。Claude Code 在上下文窗口接近上限时会自动压缩历史对话，普通信息会丢失。但 notepad 的内容会在压缩前被 pre-compact Hook 保存，新会话开始时自动恢复。配合 project-memory.json 实现了跨会话的项目知识持久化。

模型路由：不是所有任务都需要 Opus

OMC 的模型路由策略很实际，分三层：

逻辑很直白：让 explore Agent 用 Haiku 去扫描文件结构，比用 Opus 便宜得多，效果也不差。架构决策这种需要深度推理的任务，才值得花 Opus 的钱。社区文章引用了一个数据：这套路由策略能节省 30-50% 的 token（来源：OMC README 及多篇社区文章，未找到独立基准测试）。

OMC 还提供了委派类别（Delegation Categories），用语义化的任务分类自动确定模型层级、温度和思考预算：

温度参数的区分也很有讲究：ultrabrain 用 0.3 保证推理的确定性，artistry 用 0.9 鼓励创意发散。这些参数在 Agent 委派时自动应用，不需要手动指定。

一个完整的 Agent 协作链路长这样：

explore → analyst → planner → critic → executor → verifier
（发现）  （分析）  （排序）  （审查）  （实现）  （确认）

3. 从安装到配置的完整实战

安装流程

OMC 提供两种安装途径，可以共存。一种作为 Claude Code Plugin 使用（通过 slash 命令交互），另一种作为 Terminal CLI 使用（通过 shell 命令）。

方式一：Marketplace 插件安装（推荐）

# 添加 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。这个命名来自西西弗斯（Sisyphus）——OMC 的 ralph 模式就是推石头上山的循环，任务不完成不停止。安装时出现 deprecated prebuild-install@7.1.3 警告可以忽略，这是上游 better-sqlite3 依赖的已知问题。

平台支持方面，macOS 和 Linux 用 Bash Hook 脚本（.sh），Windows 建议用 WSL2，原生支持仍为实验性（用 Node.js Hook 脚本 .mjs）。

初始化配置

三种方式任选其一：

# 自然语言触发
setup omc

# Skill 命令
/oh-my-claudecode:omc-setup

# CLI 命令
omc setup

作用域选择上，推荐项目级（/omc-setup --local），配置保存在 .claude/CLAUDE.md。全局配置保存在 ~/.claude/CLAUDE.md，对所有项目生效。

/omc-setup 会自动完成几件事：生成 CLAUDE.md 配置文件、安装 Hook 脚本到 .claude/hooks.json、注册 MCP 工具服务器。官方文档说这是零配置——实际上不需要手动编辑任何配置文件就能跑起来。

双层配置详解

当你需要个性化定制时，OMC 的配置文件使用 JSONC 格式（支持注释的 JSON），分两层：

优先级从低到高：默认值 → 用户配置 → 项目配置 → 环境变量。

{
  // 按 Agent 分配模型
  "agents": {
    "explore": { "model": "haiku" },
    "executor": { "model": "sonnet" },
    "architect": { "model": "opus" }
  },

  // 功能开关
  "features": {
    "parallelExecution": true,
    "lspTools": true,
    "astTools": true
  },

  // 模型路由配置
  "routing": {
    "enabled": true,
    "defaultTier": "MEDIUM",
    "forceInherit": false
  }
}

环境变量覆盖：OMC_MODEL_LOW、OMC_MODEL_MEDIUM、OMC_MODEL_HIGH 分别控制三层模型。比如项目预算有限，可以把 OMC_MODEL_HIGH 设成 sonnet 而不是 opus，在成本和质量之间做取舍。

诊断工具

装完跑一下诊断，确认所有组件就绪：

/oh-my-claudecode:omc-doctor

检查项包括：依赖安装状态、配置文件语法、Hook 安装状态、Agent 可用性、Skill 注册状态。哪个环节有问题一目了然。

CLI 还提供了几个分析工具：

• omc stats — token 使用和成本分析
• omc agents — 各 Agent 使用情况细分
• omc tui — 交互式仪表板，实时查看 OMC 运行状态

4. 高频工程场景实战演练

三种执行模式对比图

图 4：三种核心执行模式对比

三个场景，从简到繁，覆盖日常开发中的典型需求。每个场景都给出具体的命令和交互流程。

场景一：遗留代码重构（autopilot / ralph 模式）

场景：接手一个老项目，auth 模块代码混乱，错误处理缺失，需要重构。

用 autopilot 模式：

autopilot: refactor the auth module, improve error handling and add input validation

OMC 收到这条指令后，keyword-detector Hook 检测到 autopilot 关键词，激活 autopilot Skill，自动走五阶段管线：

1. Explore 阶段 — explore Agent（Haiku 模型）扫描 auth 模块相关文件，建立依赖关系图
2. Analysis 阶段 — analyst Agent（Opus 模型）分析现有代码的问题和约束
3. Planning 阶段 — planner Agent（Opus 模型）制定重构计划，critic Agent 审查方案
4. Execution 阶段 — executor Agent（Sonnet 模型）按计划修改代码
5. Verification 阶段 — verifier Agent（Sonnet 模型）验证重构结果

整个过程不需要手动指定用哪个 Agent，OMC 自动编排。autopilot 适合说一句话就开工的端到端需求。

用 ralph 模式（更强力）：

ralph: refactor the auth module, ensure all existing tests still pass

ralph 的核心区别在于：它循环执行直到所有验证通过。测试挂了？自动修复再跑。Lint 报错？自动处理再检查。

背后的原理是 persistent-mode Hook——当 ralph 模式活跃时，这个 Hook 在 Stop 事件触发时注入阻止停止的消息，确保 Claude 不会提前收工。状态追踪通过 ralph-state.json 记录循环次数和每次的结果，即使上下文被压缩也能从状态文件恢复进度。

什么时候用 autopilot，什么时候用 ralph？ 如果任务比较确定（明确知道要做什么），autopilot 就够了。如果任务有严格的完成标准（测试必须全过、build 必须成功），ralph 更合适。

场景二：批量修复（ultrawork 模式）

场景：一个 TypeScript 项目里有 50 多个类型错误，分散在 20 多个文件中。

ultrawork fix all TypeScript errors in the project

ultrawork 的核心能力是最大并行度。keyword-detector Hook 检测到关键词后，OMC 同时启动多个 executor Agent，每个负责一组文件，并行修复。

对比一下效果差异：

• 单 Agent 模式：逐个文件修复，每个文件排队等上一个完成，50 个错误可能需要 50 轮循环
• ultrawork 模式：多个 Agent 同时开工，每个 Agent 独立处理自己负责的文件，互不干扰

subagent-tracker Hook 在后台追踪每个 Agent 的状态。完成后自动汇总结果，报告哪些文件修复成功、哪些还有问题。

触发方式也很灵活——ultrawork、ulw、uw 中任何一个关键词都能激活并行模式。

想加一层深度搜索再修复：

deepsearch find all usages of deprecated API calls, then ultrawork fix them

deepsearch 先用 explore Agent 在代码库中定位所有过时 API 调用，汇总结果后交给 ultrawork 并行修复。

场景三：多模块 Bug 修复（team 模式）

场景：生产环境出了一个支付超时的 Bug，涉及后端支付服务、前端结账流程和数据库事务，需要多模块协作排查修复。

Team 模式是 OMC 推荐的执行方式，走一个五阶段流水线：

team-plan → team-prd → team-exec → team-verify → team-fix

启动命令：

/team 3:executor "fix the payment timeout bug affecting checkout flow"

这条命令启动 3 个 executor Agent，通过共享任务列表和消息系统协作。每个 Agent 有独立的上下文窗口（上下文隔离），Leader Agent 负责协调和选择性共享信息。

tmux CLI 工作者（v4.4.0+）更进一步——可以启动真实的 Codex 或 Gemini CLI 进程：

# Claude 负责调查根因
omc team 1:claude "investigate the payment timeout root cause"

# Codex 负责安全审查
omc team 1:codex "review the fix for security issues"

# Gemini 负责设计 UI 错误状态
omc team 1:gemini "design UI error state for payment failure"

管理任务也很直观：

omc team status payment-fix    # 查看状态
omc team shutdown payment-fix  # 完成后关停

一个提醒：Team 模式需要在 ~/.claude/settings.json 中启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS，这是 Anthropic 的实验性功能，不启用 /team 命令不可用。另外 tmux CLI 工作者需要额外安装 tmux（macOS：brew install tmux，Linux：apt install tmux）。

你在项目中用过类似的多 Agent 协作方案吗？体验怎么样，欢迎在评论区聊聊。

5. 效率对比与使用建议

执行模式选择指南

不知道该用哪种模式？参考这张决策表：

选择建议：日常开发从 autopilot 开始上手，需要并行处理用 ultrawork，复杂多模块任务上 team，有严格完成标准的用 ralph。

常用命令速查

# 自动执行
autopilot: build a REST API with authentication

# 持久执行（不完成不停止）
ralph: refactor the auth module

# 并行执行
ultrawork fix all TypeScript errors

# 多 Agent 协作
/team 3:executor "implement todo app"

# 三模型协作
ccg: review this PR

# 深度搜索
deepsearch find all database queries without indexes

# 深度推理
ultrathink about the best caching strategy for this API

# 取消活跃模式
stopomc

实际使用中的注意事项

1. 魔法关键词硬编码：autopilot、ralph、ccg 等核心关键词在 Hook 脚本中硬编码，不能通过配置文件修改。自定义触发词只支持 ultrawork、search、analyze、ultrathink 这几类，可以在 omc.jsonc 的 magicKeywords 字段中配置
2. 模型降级策略：预算有限时，通过 OMC_MODEL_HIGH=sonnet 把 HIGH 层从 opus 降到 sonnet 是个务实的选择。或者直接在配置文件中给特定 Agent 指定模型："architect": { "model": "sonnet" }
3. Windows 支持：原生 Windows 支持仍为实验性，建议用 WSL2。Hook 脚本在 macOS/Linux 上用 Bash（.sh），在 Windows 上用 Node.js（.mjs）
4. swarm 兼容：如果你之前用的是 swarm 命令，注意这个兼容别名已经移除，需要迁移到 /team 语法

自定义 Skill：一次学习，永久复用

/skillify 命令可以把会话中的解决方案提取成可复用的 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...

Skill 分两个作用域：项目级 .omc/skills/ 提交到版本控制供团队共享；用户级 ~/.omc/skills/ 对所有项目通用。项目级优先级更高，会覆盖用户级同名 Skill。

还有一个 /deep-interview 命令值得一提——它用苏格拉底式问答来帮你澄清需求，适合在动手写代码前把需求想清楚。

总结

oh-my-claudecode 的核心思路很清晰：Claude Code 提供了强大的单 Agent 能力和灵活的 Hooks 机制，OMC 在这个基础上搭建了 Hooks → Skills → Agents → State 四层编排架构，把手动指挥一个 Agent 变成自动协调多个 Agent。

从源码分析来看，这套架构设计是扎实的：19 个 Agent 按泳道分工明确，三层模型路由在成本和质量之间做了合理权衡，State 系统的 notepad 抗压缩机制解决了一个实际痛点，三层 Skill 组合公式提供了灵活的执行策略。

不过说实话，OMC 目前更适合已经在用 Claude Code、对多 Agent 协作有实际需求的开发者。如果你的日常任务比较简单——单文件修改、短对话能搞定——OMC 的 19 个 Agent 和 31 个 Skill 可能有点重了。而且一些关键魔法关键词（autopilot、ralph）是硬编码的，定制灵活性有限。

如果你的项目经常涉及多文件重构、批量修复或需要端到端自动化流程，OMC 值得认真试试。建议从 autopilot 模式开始上手，熟悉后再尝试 team 和 ultrawork。遇到问题跑一下 /omc-doctor 诊断，基本能解决大部分安装和配置问题。

关于 OMC 的多 Agent 协作，你最想了解哪个方面？留言告诉我。

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！