oh-my-claudecode 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

oh-my-claudecode 是面向 Claude Code 的多智能体编排系统（multi-agent orchestration system），项目描述为“Teams-first Multi-agent orchestration for Claude Code”。它使用 TypeScript 编写，默认分支为 main，采用 MIT 许可证。

根据所提供的 GitHub 元信息，仓库拥有 39254 个 Star 和 3512 个 Fork。npm 包的名称并不是仓库品牌名，而是 oh-my-claude-sisyphus；仓库、插件和命令使用 oh-my-claudecode，通过 npm 安装 CLI 时需要区分这两个名称。

“Multi-agent orchestration for Claude Code. Zero learning curve.”
来源：README

定位与目标用户

该项目的核心定位不是单个代码生成命令，而是把 Claude Code 组织成具有阶段、角色和验证环节的多智能体工作流。用户可以从自然语言需求开始，由编排层负责任务拆分、智能体分配、并行执行和结果验证。

目标用户首先是已经使用 Claude Code、希望处理跨文件或多阶段开发任务的开发者。对于需要架构分析、研究、设计、测试和数据科学等不同角色协作的任务，项目提供了 32 个专业智能体以及模型路由能力；具体智能体名称、完整职责和路由规则应以仓库当前文档为准。

README 将 Team 设为标准编排方式。从 v4.1.7 起，swarm 和 ultrapilot 等旧入口仍然存在，但底层会路由到 Team；这意味着已有旧工作流可以继续使用，同时新配置应优先围绕 Team 设计。

核心功能

核心能力集中在任务编排，而不是单一模型调用。用户输入目标后，系统会根据执行模式建立阶段化流程，并将任务交给不同专业智能体；输出通常表现为代码变更、分析结果、验证状态或下一轮修复任务，具体输出格式由所选命令和工作流决定。

Team 阶段化协作

Team 是项目推荐的标准模式，其流水线为 team-plan → team-prd → team-exec → team-verify → team-fix (loop)。触发方式是使用 /team 命令并指定工作者数量和角色，例如 /team 3:executor "fix all TypeScript errors"；任务先进入计划和产品需求阶段，再执行、验证，验证发现问题后进入修复循环。

该模式依赖 Claude Code 原生团队能力。README 要求在 ~/.claude/settings.json 中启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS；如果团队功能被禁用，OMC 会发出警告，并在条件允许时回退到非 Team 执行模式。

Autopilot 自主执行

Autopilot 用于从需求到实现的端到端执行。触发入口包括 Claude Code 会话中的 /autopilot，以及自然语言快捷方式 autopilot:；输入可以是“build a REST API for managing tasks”这样的开发目标。

其工作机制是把用户目标交给编排系统，由系统自行安排专业智能体和执行阶段。资料只说明了自动委派、并行化、持久执行和模型路由等能力，未提供一份固定的输入输出接口定义，也未提供每类任务的完成时间、成功率或资源保证。

深度访谈与需求澄清

当需求不明确时，可使用 /deep-interview，例如 /deep-interview "I want to build a task management app"。README 将它描述为苏格拉底式提问流程，用于在编写代码前识别隐藏假设，并通过加权维度衡量需求清晰度。

该模式的输入是模糊想法或初始需求，输出是经过追问后更明确的构建目标。资料没有给出加权维度的具体名称、评分算法或可配置参数，因此不应把它理解为具有公开稳定接口的需求管理系统。

多种执行模式

项目提供 Team、Autopilot、Ralph、Pipeline 以及旧版 Swarm/Ultrapilot 等执行模式。Team 适用于共享任务列表上的阶段化协作，Ralph 用于需要持续推进直到完成验证的任务，Pipeline 用于必须按严格顺序执行的多阶段转换；Swarm 和 Ultrapilot 在当前资料中被标记为兼容性入口。

模式的选择会影响任务拆分、执行顺序和验证方式。资料没有提供统一的性能基准，因此不能据此断言某种模式一定更快或更省资源；实际选择应依据任务是否需要并行、是否需要严格顺序以及是否需要持续修复来决定。

tmux CLI 工作者

从 v4.4.0 起，Codex 和 Gemini MCP 服务器被移除，项目改用 /omc-teams 在 tmux 分屏中启动真实的 CLI 进程。示例包括 /omc-teams 2:codex "review auth module for security issues"、/omc-teams 2:gemini "redesign UI components for accessibility" 和 /omc-teams 1:claude "implement the payment flow"。

这些工作者按需生成，任务结束后退出；使用前需要相应的 codex 或 gemini CLI，并且需要有活跃的 tmux 会话。若只想获取外部 CLI 的意见而不启动团队窗口，可使用 /ask codex 或 /ask gemini，再由 Claude 汇总结果。

系统架构与关键模块

从 package.json 可以确认，项目以 ESM 方式发布，并同时提供 npm 库入口、Team 入口和多个命令行入口。发布包中还包含 agents、commands、hooks、skills、templates、docs 及多个 bridge 文件，说明运行时由编译后的 TypeScript、插件资源和桥接组件共同构成。

发布入口与命令行层

package.json 的 main 指向 dist/index.js，类型声明指向 dist/index.d.ts；./team 子路径指向 dist/team/index.js。命令行层将 oh-my-claudecode 和 omc 映射到同一个 bin/oh-my-claudecode.js，另有 omc-cli 映射到 bridge/cli.cjs。

插件、技能与代理资源

插件安装路径负责向 Claude Code 提供命令、技能和代理资源。package.json 的发布文件列表包含 agents、commands、hooks、skills 和 templates，这些目录共同承载编排层可以调用的行为定义和运行时资源。

当用户通过 omc --plugin-dir <path> 或 claude --plugin-dir <path> 运行时，setup 需要使用 --plugin-dir-mode，或者预先设置 OMC_PLUGIN_ROOT。这样可以避免安装器重复复制运行时已经由插件提供的技能和代理。

构建与桥接组件

项目的 build 脚本会依次执行 TypeScript 编译、工作流阶段提示词构建、技能桥接、MCP 服务器构建、桥接入口构建、文档组合、提示词投影、Claude MD 协调器、运行时 CLI、Team 服务器和 CLI 构建。由此可知，源码修改后不能只依赖单一步骤，还需要完整构建流程生成发布所需文件。

依赖列表包含 @anthropic-ai/claude-agent-sdk、@modelcontextprotocol/sdk、better-sqlite3、commander、zod、ajv、jsonc-parser、vscode-languageserver-protocol 和 @ast-grep/napi。这些名称来自 package.json；各模块在运行时的完整调用关系，官方仓库未提供该信息，建议以最新源码和文档为准。

依赖与运行环境

运行路径依赖 Claude Code；Team 模式还依赖 Claude Code 的原生团队开关。若使用 /omc-teams，则额外依赖 tmux 会话以及已经安装、可执行的 Codex 或 Gemini CLI，项目资料没有给出这些 CLI 的版本要求。

npm 路径依赖 Node.js 生态和 package.json 中声明的原生模块 better-sqlite3。README 记录了安装时可能出现的 deprecated prebuild-install@7.1.3 警告，该警告来自 better-sqlite3 → prebuild-install 依赖链；README 同时说明该警告本身不代表 OMC CLI 安装失败。

Node.js、npm、Claude Code、tmux、Codex CLI 和 Gemini CLI 的最低版本、操作系统矩阵及硬件要求，在所提供资料中没有列出。部署这些组件时应以最新 README、对应工具的官方文档和实际环境检查结果为准。

快速开始

最小闭环包括安装插件、执行 setup、提交一个本地开发任务，再通过诊断命令检查状态。README 要求 marketplace 的两条 slash 命令逐条输入，不能把两行一次性粘贴到同一输入中。

方式一：Claude Code marketplace 安装

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

上述命令用于将 GitHub marketplace 加入 Claude Code，并安装名为 oh-my-claudecode 的插件。两条命令应分别执行；安装完成后，在 Claude Code 会话中执行 setup。

方式二：npm CLI 安装

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

# 在 Claude Code / OMC 会话中配置
/omc-setup

# 或从终端配置
omc setup

这里使用的是 npm 包名 oh-my-claude-sisyphus，不是仓库名。安装过程中如果出现 README 所记录的 prebuild-install@7.1.3 弃用警告，应先检查命令是否真正退出失败，再决定是否继续排查。

最小运行与验证示例

# 在 Claude Code / OMC 会话中启动一个本地开发任务
/autopilot "build a REST API for managing tasks"

# 更新插件缓存后重新配置
/plugin marketplace update omc
/omc-setup

# 遇到更新后的插件问题时运行诊断
/omc-doctor

第一条命令是运行步骤，后两组命令分别覆盖更新配置和问题诊断。资料没有提供 REST API 的固定代码输出、端口或数据库配置，因此示例只用于验证编排入口，不应被理解为项目内置了某个特定 API 模板。

配置说明

配置主要分为 Team 开关、插件目录运行方式和 marketplace 更新流程。以下表格只列出资料中明确出现的字段、环境变量或命令行选项；没有明确默认值的项目统一标记为“未提供”，不对其行为作额外推断。

对于使用 --plugin-dir 的场景，应在 setup 阶段明确使用 --plugin-dir-mode 或设置 OMC_PLUGIN_ROOT。完整决策矩阵位于仓库的 docs/REFERENCE.md，所提供资料没有展开该文件的全部内容，因此具体组合以仓库当前文档为准。

进阶用法

复杂任务可以先通过 /deep-interview 澄清目标，再交给 /team 或 /autopilot 执行。这个顺序适用于需求边界尚未确定、但又不希望直接让代理修改代码的场景。

需要多角色协作时，可以使用 Team 指定工作者数量和角色，例如 /team 3:executor。需要调用外部 CLI 进行专项审查时，应使用 /omc-teams；若只需要意见汇总而不需要 tmux 工作者窗口，则使用 /ask codex 或 /ask gemini。

更新流程包含两个关键步骤：先执行 /plugin marketplace update omc 同步 marketplace 克隆，再执行 /omc-setup 刷新配置。README 特别说明，若 marketplace 自动更新未启用，需要手动执行第一步。

可观测性与运维

项目提供 HUD 状态栏，用于显示底层运行状态；README 将实时可见性列为开发者体验的一部分。该状态展示属于会话内观测手段，资料没有提供指标名称、日志格式、持久化位置、告警接口或监控后端。

运维操作主要围绕 setup、marketplace 更新和诊断命令展开。更新后遇到插件问题时可以执行 /omc-doctor 清理旧的插件缓存；资料没有给出缓存目录、清理范围、退出码或自动回滚保证。

package.json 提供 test、test:run、test:coverage、lint 和多个构建校验脚本。它们说明仓库具备测试、覆盖率、静态检查和构建验证入口，但资料没有给出测试数量、覆盖率结果、基准数据或持续集成平台。

安全与合规边界

该项目能够编排代码修改、架构分析和安全审查任务，因此运行权限应限定在已授权的本地代码库、测试环境和组织批准的 CLI 账户范围内。项目资料没有声明其可以绕过访问控制、检测机制或平台政策，任何此类用途都不属于本文支持范围。

使用 /omc-teams 调用 Codex、Gemini 或 Claude CLI 时，需要分别遵守这些工具及所在组织的身份认证、数据处理和使用政策。不要把未获授权的源代码、凭据、个人信息、生产数据库内容或其他受限制数据直接交给多智能体流水线；资料没有提供 OMC 的数据脱敏、密钥托管、审计留痕或隔离执行承诺。

对于支付流程、身份认证、权限系统和安全审查等任务，应将输出视为需要人工复核的开发建议或代码变更。本文不提供面向未授权目标的攻击教程、绕过检测技巧或账号自动化方案；具体合规要求应由使用方结合所在地法律、组织政策和第三方服务条款确定。

许可证与商用条款

仓库 LICENSE 文件声明项目采用 MIT License，版权标记为 Copyright (c) 2025 Yeachan Heo。MIT 许可授予获得软件及相关文档的人员使用、复制、修改、合并、发布、分发、再许可和销售软件副本的权限，前提是遵守许可证中的条件。

分发全部或实质性部分软件时，需要保留版权声明和许可声明。许可证同时以“按现状”提供软件，不提供明示或默示担保；作者在许可证规定范围内不承担因软件使用产生的责任。

因此，根据 LICENSE 文本，商业使用路径没有被许可证排除，但集成、再分发、第三方模型服务、CLI 服务及其各自条款仍需单独审查。本文不替代法律意见；对于 NOTICE 文件、依赖项许可证和企业合规审批，资料没有提供完整清单，应以仓库 LICENSE 及相关依赖的许可文本为准。

局限性与已知限制

第一，Team 模式依赖 Claude Code 原生团队能力。若该能力未启用，OMC 会警告并尝试回退，但资料没有说明所有工作流在回退模式下都保持相同的并行能力、输出结构和验证行为。

第二，外部 CLI 工作者依赖 tmux、Codex CLI 或 Gemini CLI。缺少这些前置组件时，/omc-teams 的对应场景无法按 README 所述运行；项目资料没有提供自动安装或自动修复这些外部工具的流程。

第三，npm 安装涉及 better-sqlite3 原生依赖，并可能显示 prebuild-install@7.1.3 弃用警告。README 将问题跟踪在 GitHub issue #2913，但所提供资料没有给出该问题的最终修复版本或跨平台编译矩阵。

第四，项目宣称具备成本优化和 30%—50% token 节省能力，但所提供资料没有配套测试条件、模型组合、任务样本或复现实验。因此该数值不能作为特定项目的成本承诺，也不能替代实际预算评估。

第五，仓库资料未提供 SLA、并发上限、任务规模上限、API 端口、生产部署拓扑、数据保留策略或故障恢复时间。对这些指标有硬性要求的团队，应在引入前自行验证并建立外部运行约束。

适合谁

以下信号同时出现时，项目与使用场景匹配度较高：

• 团队已经采用 Claude Code，并希望把需求澄清、实现、验证和修复组织成连续流程。
• 任务涉及多个角色，例如架构分析、研究、UI 设计、测试或数据科学，需要分别委派给专业智能体。
• 代码库允许在本地或测试环境中由自动化工具执行修改，并且团队能够安排人工审核。
• 团队需要 Team、Autopilot 或 Pipeline 等不同执行策略，而不是只调用一次模型生成文本。
• 开发环境已经具备 Claude Code；需要外部 CLI 协作时，还具备 tmux 以及相应的 Codex 或 Gemini CLI。

不适合谁

以下信号表明需要谨慎评估，或者应暂缓引入：

• 组织禁止自动化工具直接读取或修改代码，或者项目包含未经脱敏的敏感数据。
• 运行环境不能启用 Claude Code 原生团队能力，也不能接受 Team 回退后的行为差异。
• 任务要求明确的并发上限、SLA、端口规范、审计格式或数据保留保证，而仓库资料没有提供这些承诺。
• 团队不能安装或维护 tmux、Codex CLI、Gemini CLI 等外部前置组件，却又依赖 /omc-teams 场景。
• 使用者需要的是固定、可审计、单步骤的脚本流程，而不是会进行任务拆分、代理委派和循环修复的编排系统。

常见问题与排查（FAQ / Troubleshooting）

为什么仓库名和 npm 包名不同

仓库和插件使用 oh-my-claudecode，npm 发布包使用 oh-my-claude-sisyphus。通过 npm 安装 CLI 时使用后者；通过 Claude Code marketplace 安装时使用前者。

两条 marketplace 命令能否一次粘贴

不能。README 明确要求逐条输入 /plugin marketplace add ... 和 /plugin install oh-my-claudecode，一次性粘贴两行会失败。

Team 没有按预期启动怎么办

先检查 ~/.claude/settings.json 中是否设置了 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 为 1，再确认已经执行 /omc-setup。若团队能力被禁用，README 说明 OMC 会警告并在可能的情况下回退到非 Team 模式。

插件目录模式如何避免重复安装技能

如果通过 omc --plugin-dir <path> 或 claude --plugin-dir <path> 启动，应在 setup 中加入 --plugin-dir-mode，或者设置 OMC_PLUGIN_ROOT。完整参数矩阵以仓库 docs/REFERENCE.md 为准。

npm 安装出现 prebuild-install 弃用警告是否等于失败

不等于。README 说明该警告来自 better-sqlite3 的上游依赖链，当前不代表 OMC CLI 安装失败。应先检查 npm 命令的最终退出状态和 CLI 是否可执行；如果仍有问题，可结合项目 issue #2913 和最新 README 排查。

更新后插件状态异常如何处理

先执行 /plugin marketplace update omc 同步 marketplace 克隆，再执行 /omc-setup 刷新配置。若问题仍然存在，README 建议使用 /omc-doctor 清除旧插件缓存；缓存目录和清理细节，官方仓库未提供该信息。

是否有固定端口或 REST API 服务端口

所提供资料没有列出 OMC 的端口配置，也没有声明 Autopilot 示例会自动启动某个固定端口。示例中的 REST API 只是任务描述，实际应用的端口应由生成项目自身的配置决定。

项目地址与资源

下面的链接均来自项目资料、仓库 README 或 package.json 中出现的官方项目入口。版本、命令和文档内容可能随默认分支更新，使用前应核对最新页面。

• oh-my-claudecode GitHub 仓库
• oh-my-claudecode 官网
• oh-my-claudecode 文档站
• oh-my-claude-sisyphus npm 包页面
• oh-my-codex 项目
• gajae-code 项目
• OMC Discord 社区
• Yeachan Heo GitHub Sponsors 页面