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启发开发。
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

RAG 召回率达标但回答仍错：归因链条与 DeepSeek 工程对策

avatar DeepSeek技术社区
cover

DeepSeek-V4 长会话稳定性优化：截断补救与权限隔离的工程实践

avatar DeepSeek技术社区
cover

DeepSeek-V4 提示词版本管理：从 YAML 散落到灰度发布的最佳实践

avatar DeepSeek技术社区