oh-my-claudecode 快速上手指南：从插件安装到首个 Autopilot 会话与深度配置

oh-my-claudecode 快速上手指南：从插件安装到首个 Autopilot 会话与深度配置

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode

Oh My ClaudeCode（简称 OMC）是一套运行在 Claude Code 之上的"团队优先"多智能体编排框架：无需记忆命令语法，只要用自然语言描述目标，它便会调度 19 个各司其职的专项 Agent，按流水线自动完成从需求分析、规划、编码、QA 到最终验证的完整闭环。本篇以官方快速入门文档（docs/GETTING-STARTED.md）为核心骨架，结合仓库源码逐步讲解：如何完成插件与 CLI 双面安装、如何用一条命令启动你的首个 Autopilot 会话、以及如何通过全局/项目两级 JSONC 配置定制 Agent 模型与魔法关键词，让你能真正上手并把 OMC 调教成贴合自己项目的方式运行。

前置条件与整体概览

在开始安装前，请先确认环境满足以下最低要求（源自 README.md）：

项目	要求
Claude Code	必须已安装官方 Claude Code CLI
认证方式	Claude Max/Pro 订阅，或配置ANTHROPIC_API_KEY环境变量

此外，若希望使用omc team（tmux 终端 Worker）与限流自动恢复等功能，还需要 tmux（macOS 用brew install tmux，Debian/Ubuntu 用sudo apt install tmux）。

OMC 提供两条并存、互补的接入面：

接入面	提供能力	推荐安装方式
Claude Code 插件（oh-my-claudecode@omc）	会话内 skills、agents、hooks、statusline（HUD）、MCP server，以及/autopilot、/ralph、/execute、/team等斜杠命令	Marketplace 插件安装（下文 Step 1–2）
终端 CLI（omc二进制，npm 包oh-my-claude-sisyphus）	Shell 命令：omc setup、omc update、omc team、omc ask，以及已硬废弃的omc autoresearchshim	npm i -g oh-my-claude-sisyphus@latest

重要命名提示：项目仓库、插件与命令统一品牌为oh-my-claudecode，但发布到 npm 的包名是oh-my-claude-sisyphus。通过 npm/bun 安装或升级 CLI 时，务必使用oh-my-claude-sisyphus@latest；该包同时安装oh-my-claudecode与简写omc两个命令别名。详见 README.md 中 "Package naming" 说明。

绝大多数用户会同时安装两者：插件负责会话内体验，npm CLI 负责 Shell 侧自动化与升级。二者并行运行完全受支持——omc update与omc setup均幂等，并且能自动检测插件安装，避免在~/.claude/skills/下重复注册 skills（对应 issue #2252）。入门文档特别指出：旧版文档曾声称 OMC "仅插件"，这是不准确的，omcCLI 才是omc setup/omc update的规范入口（两种路径的对照可参见 README.md#quick-start）。

安装：三步从零到可用

安装分三个主要步骤，请严格按顺序执行。第一步与第二步都是在 Claude Code 会话内输入的斜杠命令，README 提示两条命令必须逐条输入，一次性粘贴两行会失败。

Step 1：添加 Marketplace 源

在 Claude Code 内执行：

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

Step 2：安装插件

/plugin install oh-my-claudecode

Step 2b（可选但推荐）：安装终端 CLI

如果你希望在 Shell 中使用omc setup、omc update、omc team、omc ask等命令：

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

已知 npm 警告：安装 CLI 时 npm 可能打印deprecated prebuild-install@7.1.3。该警告来自上游原生依赖better-sqlite3 -> prebuild-install；prebuild-install@7.1.3仍是当前最新发布版本，仓库侧暂无安全的依赖升级或 override 可消除它。该警告正在 issue #2913 中跟踪，它本身不代表 OMC CLI 安装失败。

两条安装路径可以同时进行。CLI 会自动检测插件安装，不会在~/.claude/skills/下重复注册 skills——若你此前曾遇到重复 skill 问题，在 4.11.2+ 上运行一次omc update即可自愈，它会通过prunePluginDuplicateSkills清理插件现已提供的遗留独立 skills。

Step 3：运行初始设置

安装完成后，在 Claude Code 中输入以下任一命令：

# 方式一：自然语言 setup omc # 方式二：skill 命令 /oh-my-claudecode:omc-setup

omc-setupskill 的目标是"一条命令解决全部配置"。从 skills/omc-setup/SKILL.md 可看到其内部实现细节：它会检查~/.claude/.omc-config.json（尊重CLAUDE_CONFIG_DIR）判断是否已配置、支持--help/--local/--global/--force四种旗标、通过scripts/setup-progress.sh保存阶段进度以支持中断后续跑，并依次执行四个阶段（安装 CLAUDE.md → 环境配置 → 集成配置 → 完成引导）。该 skill 的完整 Help 文本还说明：无旗标首次运行会进入交互式向导，若已配置则会询问"更新 CLAUDE.md / 完整重跑 / 取消"三选一，避免每次升级都重跑整个向导。

选择设置作用域

项目级设置（推荐）——只影响当前项目：

/oh-my-claudecode:omc-setup --local

• 设置写入./.claude/CLAUDE.md
• 不影响其他项目
• 已有的全局CLAUDE.md被保留

全局设置——作用于所有 Claude Code 会话：

/oh-my-claudecode:omc-setup

• 设置写入~/.claude/CLAUDE.md
• 应用于所有项目

⚠️警告：全局设置现在会先明确询问是否修改你的基础~/.claude/CLAUDE.md，默认选择仍是覆盖。如果你选择保留（preserve）模式，则普通claude继续使用你的基础配置，而omc会强制加载 OMC companion 配置（即写入CLAUDE-omc.md供omc启动使用）。

验证安装：omc-doctor

用诊断工具确认一切正常：

/oh-my-claudecode:omc-doctor

它会依次检查：

• 依赖安装状态
• 配置文件错误
• Hook 安装状态
• Agent 可用性
• Skill 注册状态

从本地代码库运行

如果你正在开发 OMC 或想测试某个分支上的未发布特性，可以让 Claude Code 直接以本地 checkout 作为插件启动：

omc --plugin-dir /path/to/oh-my-claudecode setup --plugin-dir-mode

这样 agents、skills、commands 会直接从你的 checkout 加载，而不会被拷贝到~/.claude/。详细流程见 docs/LOCAL_PLUGIN_INSTALL.md；plugin-dir 旗标与模式的完整决策矩阵见 docs/REFERENCE.md#plugin-directory-flags。对应的仓库钩子脚本也印证了这一设计——如 scripts/setup-claude-md.sh 是 CLAUDE.md 配置协调器的唯一入口。

平台支持

平台	安装方式	Hook 类型
macOS	Claude Code Plugin	Bash (.sh)
Linux	Claude Code Plugin	Bash (.sh)
Windows	推荐 WSL2	Node.js (.mjs)

ℹ️注意：原生 Windows 支持目前处于实验阶段。对于基于 tmux 的 Team Worker，OMC 会先检测是否存在 tmux 兼容二进制；PowerShell 7+ 用户可使用原生 [psmux]，以便在交互式团队工作流中看到可见的 Claude Code teammate 窗格；当没有兼容 tmux 或原生 Windows 行为不足时，WSL2 仍作为兜底。psmux 不会强制 worktree 代理、非交互/print 模式代理或模型选中的进程内代理进入可见窗格。

更新与卸载

OMC 每 24 小时自动检查更新；手动更新只需重跑插件安装命令。

⚠️警告：插件更新后，请再次运行/oh-my-claudecode:omc-setup以应用最新配置。

卸载插件：

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

首个会话：一条命令跑完整开发流水线

安装完成后，打开 Claude Code 直接输入：

autopilot build me a hello world app

这一行就足以让 OMC 自动运行完整的开发流水线。

关键词如何被触发

autopilot是一个"魔法关键词"。从源码 src/hooks/keyword-detector/index.ts 可以看到，OMC 通过一组带优先级的正则表达式做意图识别：如autopilot会匹配\b(autopilot|auto[\s-]?pilot|fullsend|full\s+auto)\b，甚至支持build me a ...、i want an ...这类自然语言短语，还覆盖韩文오토파일럿与日文オートパイロット。ultrathink、deepsearch等关键词同样在此注册（对应优先级 11、12）。检测到autopilot后，即会启动下面 5 个阶段的流水线。

五阶段流水线内部发生了什么

Stage 1：Expansion（需求展开）analyst与architect两个 Agent 分析想法、澄清需求并产出技术规格。二者在仓库默认配置中均固定为 opus 档模型，承担高层推理职责。

Stage 2：Planning（规划）plannerAgent 创建执行计划，criticAgent 审查计划并找出缺口。这一"规划 + 批判"的组合保证计划在上手编码前已被推敲过一轮。

Stage 3：Execution（执行）executorAgent 编写代码；需要时多个 Agent 并行工作。

Stage 4：QA（质量验证）验证构建成功且测试通过；自动修复失败并重新验证。

Stage 5：Validation（最终验收）专项 Agent 对功能、安全与代码质量做最终审查；全部通过后任务才算完成——这也呼应了 OMC "不会放弃直到任务被验证完成"的持久执行理念。

用 HUD 观察流水线状态

工作进行中，可以通过 Claude Code 状态栏（HUD）监控当前状态，例如：

[OMC] autopilot:execution | agents:3 | todos:2/5 | ctx:45%

字段	含义
autopilot:execution	当前位于 autopilot 流水线的哪个阶段
agents:3	当前活跃 Agent 数量
todos:2/5	已完成任务数 / 总任务数
ctx:45%	上下文窗口占用百分比

如需配置 HUD 显示，运行：

/oh-my-claudecode:hud setup

从小任务起步

如果 autopilot 显得"太大"，可以先从单任务命令入手。这些关键词会直接唤起单一合适 Agent，而不跑完整流水线：

# 代码分析 analyze why this test is failing # 文件搜索 deepsearch for files that handle authentication # 简单实现 ultrawork add a health check endpoint

其中deepsearch在 src/hooks/keyword-detector/index.ts 中匹配\bsearch\s+the\s+codebase\b、\bfind\s+in\s+(the\s+)?codebase\b等模式，将请求路由到 codebase 搜索方向。

下一步

• 继续阅读下面的[配置章节]掌握模型与特性定制
• docs/ARCHITECTURE.md 理解 agents、skills、hooks 之间的关系

配置：两级文件与合并优先级

OMC 支持两级配置文件：

作用域	文件路径	用途
用户（全局）	~/.config/claude-omc/config.jsonc	应用于所有项目
项目	.claude/omc.jsonc	仅应用于当前项目

⚠️警告：配置文件格式为 JSONC（支持注释的 JSON），不是TypeScript 配置文件（不是omc.config.ts）。

配置合并优先级

当多个来源都存在设置时，按下述顺序合并（越靠后优先级越高）：

Defaults → User config (~/.config/claude-omc/config.jsonc) → Project config (.claude/omc.jsonc) → Environment variables

也就是说：默认值 < 用户全局配置 < 项目配置 < 环境变量。config 加载器位于 src/config/loader.ts，其测试用例见 src/config/tests/loader.test.ts。

基本配置结构

{ // 每个 Agent 的模型分配 "agents": { "explore": { "model": "haiku" }, "executor": { "model": "sonnet" }, "architect": { "model": "opus" } }, // 特性开关 "features": { "parallelExecution": true, "lspTools": true, "astTools": true }, // 魔法关键词定制 "magicKeywords": { "ultrawork": ["ultrawork", "ulw", "uw"], "search": ["search", "find", "locate"], "analyze": ["analyze", "investigate", "examine"], "ultrathink": ["ultrathink", "think", "reason"] }, // 可选的企业级 company context 契约 "companyContext": { "tool": "mcp__vendor__get_company_context", "onError": "warn" } }

通过 MCP 注入公司上下文（companyContext）

如果企业通过自定义 MCP server 暴露内部规范（安全指引、术语表、评审清单等），可在标准配置文件里指定所用工具：

{ "companyContext": { "tool": "mcp__vendor__get_company_context", "onError": "warn" } }

• MCP server 本身仍通过常规 Claude/OMC MCP 配置流程注册
• tool是完整 MCP 工具名（如mcp__vendor__get_company_context）
• onError控制 prompt 级回退策略：warn（默认）、silent或fail

这是一份提示层面的咨询性工作流契约，而非运行时强制。完整契约定义在 docs/company-context-interface.md：该契约要求 vendor 只实现一个工具get_company_context（输入{ query: string }，输出{ context: string }），并且明确context仅具参考性——返回的 markdown 应被当作引用的建议数据，而非可执行指令，不得试图覆盖系统提示或冒充策略执行。

覆盖各 Agent 的默认模型

你可以按需替换每个 Agent 使用的 AI 模型：

{ "agents": { // 把 explore 升级为更强模型 "explore": { "model": "sonnet" }, // 复杂项目把 executor 升到 opus "executor": { "model": "opus" }, // 写文档用 haiku 省钱 "writer": { "model": "haiku" } } }

默认模型映射

入门文档给出了完整的默认映射表，它也与仓库源码高度一致——在 src/agents/definitions.ts 中，每个 Agent 定义都显式声明model与defaultModel（如debugger/verifier/test-engineer/security-reviewer为sonnet，code-reviewer/code-simplifier为opus）：

Agent	默认模型	职责
explore	haiku	代码库探索
writer	haiku	编写文档
executor	sonnet	编码实现
debugger	sonnet	调试排障
designer	sonnet	UI/UX 设计
verifier	sonnet	验证
tracer	sonnet	循证的因果追踪
security-reviewer	sonnet	安全漏洞与信任边界
test-engineer	sonnet	测试策略与覆盖率
qa-tester	sonnet	交互式 CLI/服务运行时验证
scientist	sonnet	数据与统计分析
git-master	sonnet	Git 操作与历史管理
document-specialist	sonnet	外部文档与 API 参考检索
architect	opus	系统设计
planner	opus	战略规划
critic	opus	计划审查
analyst	opus	需求分析
code-reviewer	opus	全面代码评审
code-simplifier	opus	代码清晰化与简化

整体设计思路很清晰：轻量任务（探索、写作）用 haiku 控制成本，标准实现（执行、测试、调试）用 sonnet，需要深度推理的角色（架构、规划、批判、评审）用 opus。

定制魔法关键词

通过config.jsonc的magicKeywords段可定制四类关键词：

{ "magicKeywords": { // 触发并行执行模式 "ultrawork": ["ultrawork", "ulw", "parallel"], // 触发代码库搜索模式 "search": ["search", "find", "locate", "grep"], // 触发分析模式 "analyze": ["analyze", "debug", "investigate"], // 触发深度推理模式 "ultrathink": ["ultrathink", "think", "reason"] } }

ℹ️注意：magicKeywords段只允许定制上述四类：ultrawork、search、analyze、ultrathink。像autopilot、ralph、ccg这类关键词是硬编码在 keyword-detector hook 中的，无法通过配置文件修改（源码参见 src/hooks/keyword-detector/index.ts，其中ralph优先级 2、autopilot优先级 3，并有"team 优先于 autopilot"的互斥逻辑）。

模型路由配置

OMC 会根据任务复杂度自动选择模型档位：

{ "routing": { "enabled": true, "defaultTier": "MEDIUM", // 强制所有 Agent 继承父会话模型 // （使用 CC Switch、Bedrock 或 Vertex AI 时自动激活） "forceInherit": false } }

档位	模型	适用场景
LOW	haiku	快速查询、简单任务
MEDIUM	sonnet	标准实现、一般任务
HIGH	opus	架构设计、深度分析
—	fable	Claude Fable 5（高于 Opus）；凡接受档位别名之处均可使用

会话模型 vs 委派 Agent（Fable 及其他模型）

需要澄清一个重要概念：通过/model选择的模型只作用于主对话循环。委派 Agent（planner、architect、executor 及目录中的其他成员）运行在各自 Agent 定义里固定的档位——opus、sonnet或haiku——与会话模型无关。原因在源码层面很清晰：OMC 的 hooks 无法观察到/model选择，只能看到 provider 环境变量，因此在标准 Anthropic 认证下会话族继承不会自动发生。

要让委派工作运行在别的模型上，OMC 生产环境PreToolUseenforcer 认可三种方式：

• 逐次调用（Per-call）：在Task/Agent调用中显式传model（如model: "fable"）；显式模型始终被保留。
• 单 Agent 覆盖（Per-agent override）："agents": { "planner": { "model": "fable" } }—— 精确作用于单个 Agent；解析后的档位别名会自动注入 Task 调用。
• 全部继承（Everything inherits）："routing": { "forceInherit": true }—— 完全丢弃逐 Agent 路由（"核选项"；在 Bedrock/Vertex/proxy 上为兼容性自动开启）。

ℹ️ 补充：routing.modelAliases/OMC_MODEL_ALIAS_OPUS=fable会把某档位在所有固定位置重映射（例如每个 opus Agent 都解析为 Fable，而 haiku/sonnet 固定不受影响）。SDK 侧enforceModelAPI 支持它，但插件 hook 路径不会将其应用于Task/Agent调用，因此在 Claude Code 插件会话中，优先使用上面的 per-call 或 per-agent 方式。

CLAUDE.md 配置

OMC 的默认行为也通过CLAUDE.md文件配置。运行/oh-my-claudecode:omc-setup会自动生成该文件。

作用域	文件	描述
全局	~/.claude/CLAUDE.md	跨项目共享设置
项目	.claude/CLAUDE.md	项目级上下文与覆盖

从 skills/omc-setup/SKILL.md 的 Help 文本可看到，setup 内部通过scripts/setup-claude-md.sh调用 plugin-local coordinator 来写入 CLAUDE.md：脚本会校验 coordinator 响应及退出码、只为需要变更的文件创建字节级一致的备份，并采用严格的完整 SemVer 缓存版本、编译产物握手校验，fail-closed 处理协议不一致。

何时需要重跑 setup

• 初始安装之后
• OMC 更新之后（以应用最新配置）
• 切换到另一台机器时
• 启动新项目时（使用--local选项）

关键实现依据速查

若要深入验证本文所述行为，仓库中值得研读的入口包括：

• 关键词检测与优先级编排：src/hooks/keyword-detector/index.ts
• 各 Agent 的默认模型声明：src/agents/definitions.ts
• setup skill 的完整旗标与四阶段流程：skills/omc-setup/SKILL.md 及 skills/omc-setup/phases/01-install-claude-md.md
• 配置加载实现：src/config/loader.ts
• 公司上下文契约完整定义：docs/company-context-interface.md
• 插件本地安装与 plugin-dir 决策：docs/LOCAL_PLUGIN_INSTALL.md、docs/REFERENCE.md#plugin-directory-flags
• 整体架构关系：docs/ARCHITECTURE.md

掌握安装、首个 Autopilot 会话与两级 JSONC 配置这三步，你便已具备把 OMC 投入日常开发的基本能力；在此基础上，结合 README 与 REFERENCE 中的/team团队编排、omc ask多模型顾问、持久执行等进阶能力，可以逐步把多智能体工作流打磨成适合自己团队的标准流水线。

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode