oh-my-claudecode 核心参考文档总结

oh-my-claudecode（简称OMC）是Claude Code的专属增强插件，提供多智能体编排、自动化工作流、生命周期钩子、性能监控等核心能力，仅支持Claude Code Plugin安装方式，依赖Claude Max/Pro订阅或Anthropic API Key，适配macOS/Linux（Windows推荐WSL2）。以下是其核心功能、配置与使用的详细整理：

一、安装与核心要求

1. 唯一支持的安装方式

# 步骤1：添加插件市场
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
# 步骤2：安装插件
/plugin install oh-my-claudecode

注意：npm/bun/curl等安装方式已废弃，插件系统自动处理钩子与依赖配置。

2. 运行要求

• 已安装Claude Code；
• 拥有Claude Max/Pro订阅（个人推荐）或配置ANTHROPIC_API_KEY环境变量。

二、配置体系

OMC支持项目级（推荐）和全局级双配置，项目级配置优先级高于全局，更新插件后必须重新执行setup生效。

1. 配置命令

配置类型	命令	生成文件	特点
项目级	/oh-my-claudecode:omc-setup --local	./.claude/CLAUDE.md	仅作用于当前项目，不覆盖全局配置
全局级	/oh-my-claudecode:omc-setup	~/.claude/CLAUDE.md	作用于所有项目，会完全覆盖现有全局配置

2. 配置启用的核心能力

功能	无OMC配置	有OMC配置
智能体委托	仅手动	基于任务自动委托
关键词检测	禁用	支持ultrawork、search等
待办续跑	基础能力	强制完成待办
模型路由	默认模型	智能选择模型层级（Haiku/Sonnet/Opus）
技能组合	无	自动组合多技能

3. 关键环境变量

核心用于自定义运行行为、状态存储、并行执行等，部分关键变量：

变量	默认值	描述
OMC_STATE_DIR	未设置	集中式状态目录，跨工作区保留状态，推荐设为~/.claude/omc
OMC_PARALLEL_EXECUTION	true	启用/禁用智能体并行执行
DISABLE_OMC	未设置	设为任意值可禁用所有OMC钩子
OMC_LSP_TIMEOUT_MS	15000	LSP请求超时时间，大仓库可增大

4. 远程MCP访问

支持通过MCP注册中心连接远程MCP服务器，不支持OMC集群/共享远程文件系统，远程操作仍推荐SSH/工作区挂载。配置示例：

{
  "mcpServers": {
    "remoteOmc": {
      "url": "https://lab.example.com/mcp",
      "timeout": 30
    }
  }
}

三、核心CLI命令

OMC提供ask/team/session三大核心CLI命令，替代已废弃的Legacy MCP Team工具，支持多模型（Claude/Codex/Gemini）、多智能体并行、会话检索。

1. omc ask：多模型提问

向Claude/Codex/Gemini发起请求并生成可复用工件，示例：

omc ask claude "review this patch"
omc ask codex "安全视角评审该补丁"

• 工件存储路径：.omc/artifacts/ask/{provider}-{slug}-{timestamp}.md
• 技能入口：/oh-my-claudecode:ask <claude|codex|gemini> <prompt>

2. omc team：多智能体编排

启动多智能体并行执行任务，支持状态查询、强制关闭，示例：

omc team 2:codex "review auth flow" # 2个codex智能体评审认证流程
omc team status review-auth-flow    # 查看任务状态
omc team shutdown review-auth-flow --force # 强制关闭任务

• 终端适配：tmux复用窗口、非tmux启动独立后台会话。

3. omc session search：会话检索

检索本地Claude项目会话/转录文件，支持多维度过滤，示例：

omc session search "team leader stale" --since 7d # 检索7天内相关会话
omc session search --project all --json # 跨所有项目以JSON格式检索

4. 废弃工具替代

所有Legacy MCP Team工具均由omc team替代，例如omc_run_team_start → omc team [N:agent-type] "<task>"。

四、智能体（Agents）：29个专属分工智能体

OMC按**领域+模型层级（Haiku低/Sonnet中/Opus高）**划分29个智能体，每个智能体对应专属开发任务，调用时需加oh-my-claudecode:前缀。

1. 智能体领域与层级划分

核心领域包含分析、执行、搜索、前端、安全、数据科学等，示例层级对应：

领域	低阶（Haiku）	中阶（Sonnet）	高阶（Opus）
分析	architect-low	architect-medium	architect
执行	executor-low	executor	executor-high
搜索	explore	-	explore-high
安全	security-reviewer-low	-	security-reviewer
数据科学	-	scientist	scientist-high

2. 智能体选择指南（核心场景）

任务类型	推荐智能体	适配模型
快速代码查找/文件搜索	explore	Haiku
功能开发/普通代码修改	executor	Sonnet
复杂重构/架构调试	architect/executor-high	Opus
UI组件开发	designer	Sonnet
安全评审	security-reviewer	Opus
自动化测试（TDD）	test-engineer	Sonnet
代码评审	code-reviewer	Opus

3. 智能体自定义

可编辑~/.claude/agents/下的文件自定义智能体行为，包括描述、工具、模型、系统提示：

---
name: architect
description: 自定义架构分析智能体
tools: Read, Grep, Glob, Bash, Edit
model: opus # 可选haiku/sonnet/opus
---
# 自定义系统提示

五、技能（Skills）：32个自动化工作流

包含31个标准技能+1个废弃别名（psm），每个技能对应一个端到端开发工作流，可通过斜杠命令或CLI调用，核心能力涵盖自动化开发、代码清理、规划、QA等。

1. 核心技能与功能（部分）

技能名	核心描述	调用命令
autopilot	从想法到可运行代码的全自主执行	/oh-my-claudecode:autopilot <task>
ai-slop-cleaner	代码冗余清理，支持评审模式	/oh-my-claudecode:ai-slop-cleaner --review
ultrawork	最大并行吞吐量模式，多智能体并行	/oh-my-claudecode:ultrawork <task>
ralph	持续执行直到任务验证完成	/oh-my-claudecode:ralph <task>
deep-dive	问题追踪→深度调研流水线	/oh-my-claudecode:deep-dive <problem>
omc-doctor	诊断并修复OMC安装/配置问题	/oh-my-claudecode:omc-doctor
release	自动化版本发布工作流	/oh-my-claudecode:release

2. 技能高级特性

• 流水线元数据：技能可声明执行流水线（如deep-interview → omc-plan → autopilot），实现阶段化任务交接；
• 2.0兼容性：支持从.omc/skills/（默认）和.agents/skills/读取技能；
• 资源复用：技能目录中的辅助脚本/模板会被自动加载，避免重复创建。

六、钩子系统（Hooks System）：31个生命周期钩子

OMC通过31个钩子增强Claude Code的原生行为，按功能分为执行模式、核心、上下文恢复、质量验证、协调环境5大类，实现自动化触发、状态管理、代码优化等。

1. 核心钩子分类与功能（部分）

分类	钩子名	核心描述
执行模式	ultrawork/ralph/autopilot	对应技能的自动化触发与状态管理
核心	keyword-detector	检测魔法关键词并激活对应模式
核心	todo-continuation	强制完成待办列表，避免中断
质量验证	code-simplifier	自动简化修改后的代码（需手动启用）
上下文恢复	preemptive-compaction	监控上下文窗口使用，防止超限
协调环境	background-notification	后台任务完成后发送通知（Telegram/Discord）

2. 常用钩子配置：代码简化器（code-simplifier）

默认禁用，需在~/.omc/config.json中启用，自动简化指定后缀的代码文件：

{
  "codeSimplifier": {
    "enabled": true, // 启用开关
    "extensions": [".ts", ".py", ".go", ".rs"], // 目标文件后缀
    "maxFiles": 10 // 每次最多简化10个文件
  }
}

七、魔法关键词（Magic Keywords）

在自然语言提示中加入关键词，无需手动调用命令即可激活OMC增强模式，核心关键词及效果：

关键词/触发词	核心效果	示例
ultrawork/ulw	激活多智能体并行编排	ultrawork 实现OAuth用户认证
autopilot/build me	全自主执行开发任务	autopilot: 构建React待办应用
ralph/must complete	持续执行直到任务完成	ralph: 重构认证模块
deepsearch/search the codebase	代码库精准搜索	deepsearch 查找导入utils的文件
tdd/test first	强制TDD开发流程	tdd: 实现密码验证功能
stopomc/cancelomc	终止当前OMC编排任务	stopomc

八、平台支持与内置工具

1. 操作系统支持

系统	安装方式	钩子类型	注意事项
macOS	Claude Code Plugin	Bash (.sh)	原生支持
Linux	Claude Code Plugin	Bash (.sh)	原生支持
Windows	WSL2 + 上述插件	Node.js (.mjs)	原生Windows实验性支持，依赖tmux

2. 内置工具集

OMC提供三类工具，覆盖文件操作、代码分析、语言服务，均已实现且可直接调用：

（1）基础工具（10个）：文件/终端/网络操作

Read/Write/Edit（文件操作）、Bash（终端）、Glob/Grep（文件检索）、WebSearch/WebFetch（网络）、Task（智能体生成）、TodoWrite（任务追踪）。

（2）LSP工具（12个）：代码智能分析

基于语言服务器实现，支持lsp_hover（类型提示）、lsp_goto_definition（跳转到定义）、lsp_rename（全局重命名）、lsp_diagnostics（代码诊断）等，需提前安装对应语言服务器（如typescript-language-server、rust-analyzer）。

（3）AST工具（2个）：结构化代码操作

基于ast-grep实现，ast_grep_search（AST模式搜索）、ast_grep_replace（AST模式替换），支持元变量（$VAR单节点/$$$多节点）。

九、性能监控与可视化

OMC提供全维度性能监控能力，实时追踪智能体状态、令牌使用、工作流瓶颈，核心功能：

1. 监控核心特性

功能	描述	访问方式
Agent Observatory	实时智能体状态/效率/瓶颈	HUD状态栏/API
Session-End Summaries	会话总结与回调载荷持久化	.omc/sessions/*.json
Session Replay	会话事件时间线，事后分析	.omc/state/agent-replay-*.jsonl
自动干预系统	检测僵死智能体/令牌超限	自动触发

2. HUD状态栏配置

通过/oh-my-claudecode:hud setup配置，支持多预设（minimal/focused/full等），可自定义显示内容（如git分支、令牌使用、智能体数量），配置示例：

{
  "omcHud": {
    "preset": "focused",
    "elements": {
      "gitBranch": true,
      "showTokens": true,
      "agents": true
    }
  }
}

十、故障排除与常用操作

1. 一键诊断

/oh-my-claudecode:omc-doctor # 检查依赖/配置/钩子/智能体/技能

2. 常见问题与解决方案

问题	解决方案
命令未找到	重新执行/oh-my-claudecode:omc-setup
钩子未执行	检查钩子权限：chmod +x ~/.claude/hooks/**/*.sh
智能体未自动委托	验证CLAUDE.md是否加载：检查./.claude/CLAUDE.md或~/.claude/CLAUDE.md
LSP工具失效	安装对应语言服务器：npm install -g typescript-language-server
令牌超限错误	使用/oh-my-claudecode:前缀调用技能，提升令牌使用效率

3. 自动更新与卸载

• 自动更新：后台静默检查（24小时一次），并发安全；
• 手动更新：重新执行插件安装命令或使用Claude Code内置更新；
• 卸载：

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

  或手动删除智能体/命令文件：rm ~/.claude/agents/xxx.md && rm ~/.claude/commands/xxx.md。

十一、其他核心能力

1. 通知配置：通过omc config-stop-callback配置Telegram/Discord通知，支持标签@用户/角色；
2. 项目级自定义：在项目中创建.claude/CLAUDE.md，添加项目上下文（如技术栈、编码规范）；
3. 技能提取：通过learner技能从会话中提取可复用的自定义技能；
4. 开源协议：MIT协议，基于oh-my-opencode启发开发。