oh-my-claudecode 安装与配置总入口：`/omc-setup` 命令兼容层与四阶段设置向导全解析

omc-setup 是 oh-my-claudecode（OMC）在 Claude Code 中的安装、刷新与修复总入口，负责把 OMC 的智能体、Hook 与技能接入项目级或全局的 CLAUDE.md。commands/omc-setup.md 定义了一条轻量兼容命令，真正的执行逻辑则委托给 skills/omc-setup/SKILL.md 及其四个分阶段文件。读完本文，你将掌握这条命令的完整工作流：如何以 --local/--global/--force/--help 精确控制配置范围，理解插件本地协调器（Coordinator）为何是唯一允许写 CLAUDE.md 的组件，并能借助断点续跑与快速更新机制，在每次 OMC 升级后以最低 token 成本保持配置最新。

从 Dispatch 到执行：兼容命令的设计意图

在 Claude Code 会话中直接以 /oh-my-claudecode:omc-setup 调用时，触发的其实是 commands/omc-setup.md 这样一个"分发表"。它的全部职责是两行：

1. 读取当前活动 OMC 插件/安装捆绑的完整技能说明：skills/omc-setup/SKILL.md；
2. 严格按该 SKILL.md 执行，把用户随命令传入的参数原样视为 $ARGUMENTS。

若 SKILL.md 无法从当前工作目录直接读到，则从活动的 CLAUDE_PLUGIN_ROOT/OMC_PLUGIN_ROOT、包根目录或已安装的 OMC 插件目录中定位后继续。这种"命令壳 + 技能体"分层的原因在文件开头写得很清楚：避免在每个 Claude Code 会话中加载完整的 omc-setup 技能描述，从而省下上下文 token。仓库中 commands/omc-doctor.md 等同类兼容命令采用完全相同的结构，可见这是一种全项目统一的命令瘦身模式。

真正决定"接下来做什么"的，是技能体内维护的一份状态机：一条 SKILL.md 主控 + phases/01-install-claude-md.md～phases/04-welcome.md 四个阶段文件 + 若干 shell 脚本。

命令面：四个 Flag 与一段帮助文本

SKILL.md 首先定义了标志解析规则，五个入口行为互斥清晰：

调用方式	行为
/oh-my-claudecode:omc-setup --help	显示完整帮助文本后停止
/oh-my-claudecode:omc-setup --local	仅执行 Phase 1（目标 local）后停止
/oh-my-claudecode:omc-setup --global	仅执行 Phase 1（目标 global）后停止
/oh-my-claudecode:omc-setup --force	跳过"是否已配置"预检，完整跑 Phase 1→2→3→4
无参数	先做"是否已配置"预检，需要时执行完整设置

技能体还要求：当命令被调用时必须立即执行下面的工作流，而不能只向用户复述或总结这些指令。四种无 --help 的入口分别对应四类典型场景：

• 刚执行完 /plugin install oh-my-claudecode 的 Marketplace/插件用户；
• 刚执行完 npm i -g oh-my-claude-sisyphus@latest 的 npm 用户；
• 更新完检出仓库并重跑设置的 local-dev/worktree 用户；
• 以及任何想重设偏好或修复 OMC 自身的用户。

--help 展示的帮助文本完整列出用法与模式差异：

USAGE:
  /oh-my-claudecode:omc-setup           Run initial setup wizard (or update if already configured)
  /oh-my-claudecode:omc-setup --local   Configure local project (.claude/CLAUDE.md)
  /oh-my-claudecode:omc-setup --global  Configure global settings (~/.claude/CLAUDE.md)
  /oh-my-claudecode:omc-setup --force   Force full setup wizard even if already configured
  /oh-my-claudecode:omc-setup --help    Show this help

--local 只改当前项目的 .claude/CLAUDE.md；--global 默认显式覆盖 ~/.claude/CLAUDE.md，让普通 claude 启动也加载 OMC，也可选择 preserve 模式把 OMC 装进 CLAUDE-omc.md，仅由 omc 启动加载；--force 绕过已配置检查、从零重跑完整向导。

预检与分支：避免每次更新都重跑向导

已配置检查（Pre-Setup Check）

在任何改动前，技能会先读取持久化标记文件 .omc-config.json（路径尊重 CLAUDE_CONFIG_DIR，未设置时默认 $HOME/.claude，~ 与 ~/... 两种前缀写法会先被展开成真实路径）。脚本先用 jq -r '.setupCompleted // empty' 与 '.setupVersion // empty' 提取状态；若 jq 缺失或 JSON 无效，直接报错并退出，保证已有配置不被触碰。若存在 setupCompleted 时间戳，则置 ALREADY_CONFIGURED="true" 并打印完成时间与版本。

对已配置且未带 --force/--local/--global 的情况，会通过 AskUserQuestion 给出三个选项：

1. Update CLAUDE.md and clear retired setup values —— 安装当前插件的权威 CLAUDE.md，仅执行 Phase 2 步骤 2.4 清理退役配置，不再重跑完整向导（这是升级后最常用的快速路径）；
2. Run full setup again —— 进入完整向导；
3. Cancel —— 不做任何改动退出。

选项 1 的核心逻辑值得注意：它检测本地（.claude/CLAUDE.md）还是全局（~/.claude/CLAUDE.md）配置存在，分别调用 setup-claude-md.sh local 或 setup-claude-md.sh global，再补跑一次步骤 2.4，跳过其余全部步骤后直接报告成功。

断点续跑检测（Resume Detection）

每个阶段执行前先询问进度状态：

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" resume

输出不是 fresh 即代表存在上次会话，用户可选"从第 N 步续跑"或"清空状态重头开始"。状态文件存放在 .omc/state/setup-state.json。结合 scripts/setup-progress.sh 的源码可见三个关键策略：

• 进度对象记录 lastCompletedStep、ISO 时间戳 timestamp、configType 三个字段，跨平台地把 ISO 时间换算为 epoch 后判断新旧；
• 超过 24 小时的状态会被判为过期，自动删除并当作 fresh 处理，避免陈旧会话误导续跑；
• complete 子命令在写 setupCompleted/setupVersion 前，还会清理嵌套技能（如旧版 mcp-setup）遗留的 skill-active-state.json，防止 stop hook 在设置明明已完成时仍报"skill still executing"。

Phase 1：通过插件本地协调器安装 CLAUDE.md

对应文件 phases/01-install-claude-md.md。这一阶段在所有模式中都会被触及：--local/--global 单独跑它即结束，完整向导从它开始。

确定配置目标与全局安装风格

• --local → CONFIG_TARGET=local；--global → CONFIG_TARGET=global；
• 无参数向导时用 AskUserQuestion 问"配置到本项目还是所有项目"；
• 若选全局且 ~/.claude/CLAUDE.md 已存在且不含 OMC 标记，需再追问一次：Overwrite base CLAUDE.md（默认推荐）——claude 与 omc 都全局启用 OMC；或 preserve——保留用户基线文件，把 OMC 装进 CLAUDE-omc.md 并让 omc 启动时强制加载。未询问时默认 GLOBAL_INSTALL_STYLE=overwrite。

唯一的写入通道

本阶段的强制性铁律是：始终执行以下命令，不得跳过，不得使用 Write 工具：

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" <local|global> [overwrite|preserve]

该脚本是唯一的插件缓存解析器，并负责调用选中插件根的 bridge/claude-md-coordinator.cjs。从 scripts/setup-claude-md.sh 源码看，它按 "fails closed" 原则工作：

• 候选插件根必须完整包含 scripts/setup-claude-md.sh、scripts/lib/config-dir.sh、docs/CLAUDE.md、bridge/claude-md-coordinator.cjs 以及非空的 skills/wiki/SKILL.md（技能探测充当"该检出确实带有真实技能内容"的金丝雀）；
• 在缓存目录里用严格完整 SemVer 排序（脚本内置了一段手写 semver 比较的 Node 单行程序）选取最新可用版本，而不是轻信 Claude Code 启动时捕获的根路径；
• 先向协调器请求 --handshake，校验响应携带 schemaVersion === 1、非空 engineVersion、形如 64 位十六进制的 sourceSha256，再对本次将要写入的权威源 docs/CLAUDE.md 独立计算 SHA-256 与之比对——协调器对"将要安装的字节"的权威性由此被绑定；
• 随后以单条版本化 JSON 请求调用协调器，并对响应做 ok === (exitCode === 0) 的一致性校验、备份路径与回滚路径的透出校验；
• 对 Windows 下 installed_plugins.json 记录 Windows 风格 installPath 导致无限 re-exec 的问题（Issue #3743），用 cygpath 物理规范化根路径，并用 OMC_SETUP_REEXEC_DEPTH 上限 2 次的有界重执行兜底，防止死循环挂死 shell。

从 bridge/claude-md-coordinator.cjs 的编译后源码（对应源码 src/cli/claude-md-coordinator.ts 与事务逻辑 src/installer/claude-md-transaction.ts）可见协调器的工作本质是一场文件事务：

• 用 <!-- OMC:START -->/<!-- OMC:END --> 双标记识别并替换受管区间，把用户自定义内容原样保留在 <!-- User customizations --> 段下方；
• 对 markerless 的旧版（legacy-01～legacy-29）CLAUDE.md 做开行/末行 + 归一化 SHA-256 指纹匹配，识别出历史版本以便安全替换；
• 仅在文件需要变更时才创建 byte-identical 校验备份（写盘后读回比对，避免静默坏备份）；
• 通过捕获事务根（canonical realpath + dev/ino）防符号链接逃逸，拒绝任何 root 之外的写入目标；
• 用临时文件 + rename 实现原子写；任何一步失败都按逆序回滚已完成操作并清理临时文件。

此外，global-preserve 模式会写入受管导入块 <!-- OMC:IMPORT:START -->\[e-mail]\n<!-- OMC:IMPORT:END -->，让基础 CLAUDE.md 通过 @import 加载伴侣文件。local 安装在 git 仓库内还会向 .git/info/exclude 追加一段 OMC 块，默认忽略本地 .omc/* 产物、重新包含 .omc/，并保留 .omc/skills/ 供打算提交的项目技能使用。

完成并校验（local/global-overwrite 验证双标记存在；global-preserve 验证 CLAUDE-omc.md 含双标记、基础文件恰含一个受管导入块）后汇报结果，然后保存进度并退出：

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" save 2 <CONFIG_TARGET>
# flag 模式在此清空状态并停止：
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" clear

Phase 2：环境配置的五个实操步骤

对应文件 phases/02-configure.md。开头先做恢复边界判定：读取 .omc/state/setup-state.json 的 lastCompletedStep，若 >= 4，则设 RESUMED_PHASE_TWO_BOUNDARY="true"，仅执行步骤 2.4 清理后即返回，绝不重复 2.5/2.6 的提问或覆盖更高的进度标记。

• Step 2.0 检查 Ralph 的 Ruby 依赖：Ralph 工作流需要 Ruby，全新 Ubuntu 缺少 Ruby 会让 Ralph 以不透明的 Claude Code abort 失败。command -v ruby 未命中时仅告警并给出安装提示（Ubuntu/Debian：sudo apt update && sudo apt install ruby-full；macOS：brew install ruby），不阻塞其余设置。
• Step 2.1 设置 HUD 状态栏：全部委托给 hud 技能（hud + 参数 setup），把包装脚本装到 ~/.claude/hud/omc-hud.mjs、在 ~/.claude/settings.json 配置 statusLine 并提示按需重启。禁止在本阶段内联生成或修补 statusLine 路径——尤其在 Windows 上反斜杠路径处理必须留在 hud 技能内部。完成后 save 3。
• Step 2.2 修复陈旧的插件缓存引用：市场更新后运行中的会话可能仍持有旧 OMC 缓存路径，运行 node "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/repair-plugin-cache.mjs" 先行修复，避免后续缓存清理反复报陈旧插件目录错误。
• Step 2.3 检查更新：跨平台解析已装版本（依次尝试插件缓存目录数字版本目录 → .omc-version.json → CLAUDE.md 头部的 v?\d+\.\d+\.\d+），再以 npm view oh-my-claude-sisyphus version 获取最新版，两者不一致时打印升级命令 claude /install-plugin oh-my-claudecode。
• Step 2.4 清理退役配置值（快速路径也会执行）：5.0.0 移除了 ultrawork 工作流，defaultExecutionMode 键不再被任何运行时读取，但从 4.x 升级可能残留死值。脚本用 jq 'del(.defaultExecutionMode)' 配合 mktemp + mv 原子清除。注意：绝不写入任何替代的执行模式值——通用关键词不再经配置的执行模式路由，应直接调用 /oh-my-claudecode:execute 或 /oh-my-claudecode:team。若为恢复边界模式，清理后即结束 Phase 2。
• Step 2.5 安装 OMC CLI（可选）：先探测 command -v omc；未安装时询问是否 npm install -g oh-my-claude-sisyphus（获得 omc、omc hud、omc teleport 等独立辅助命令），npm 缺失或权限/网络失败均给出手动安装提示但绝不阻断。
• Step 2.6 选择任务管理工具：探测 bd（beads）与 br（beads-rust），两者均未检测到则跳过（默认内置 Tasks）。检测到时询问使用内置 Tasks（会话级）、Beads（git 后端跨会话持久）还是 Beads-Rust（轻量 Rust 移植），并把偏好原子写入 .omc-config.json：. + {taskTool: ..., taskToolConfig: {injectInstructions: true, useMcp: false}}；beads 上下文指令将在下次会话启动时自动注入。全部完成后 save 4。

Phase 3：插件、MCP 与 Agent 团队集成

对应文件 phases/03-integrations.md。恢复时若 lastCompletedStep >= 6 整阶段跳过。

• Step 3.1 校验插件：grep -q "oh-my-claudecode" "$CONFIG_DIR/settings.json"，失败则提示 claude /install-plugin oh-my-claudecode。

• Step 3.2 MCP 服务器（仅指向原生入口）：5.0.0 起 OMC 不再自带 mcp-setup 技能（已删除且无替代），服务器一律通过 Claude Code 原生 MCP 面注册：claude mcp add <name> ...，或由 CLAUDE_MCP_CONFIG_PATH 选择的原生 MCP 配置（默认是 ${CLAUDE_CONFIG_DIR:-$HOME/.claude} 旁的 .claude.json）。OMC 自带的捆绑 MCP 服务器 bridge/mcp-server.cjs 经插件 .mcp.json 注册，无需用户操作；公司上下文指引见 docs/company-context-interface.md。

• Step 3.3 Agent 团队（可选、默认关闭）：团队是实验性 Claude Code 特性，可派生 N 个协同 agent 共享任务列表并实时通信。用户同意后：

  1. 在 settings.json 以 jq 安全合并 env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"（文件不存在则新建 {"env":{"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"1"}}），合并时保留全部既有设置；
  2. 询问队友显示模式：Auto（tmux 下分屏否则进程内，推荐） / In-process / Split panes (tmux)，非 Auto 时写入 teammateMode；
  3. 询问默认 spawn 数（推荐 3，最多 5，保守 2）与默认 CLI 提供方（claude 推荐 / codex / gemini / antigravity），原子写入 .omc-config.json 的 team.ops：

  {
    "team": {
      "ops": {
        "maxAgents": 3,
        "defaultAgentType": "claude",
        "monitorIntervalMs": 30000,
        "shutdownTimeoutMs": 15000
      }
    }
  }
  

  随后用 jq empty 校验 settings.json 为合法 JSON，并确认团队环境变量在位后 save 6。注意：teammate 无独立模型默认值，每个 teammate 都是继承你当前会话模型的完整 Claude Code 会话。

Phase 4：收尾欢迎信息与可选规则模板

对应文件 phases/04-welcome.md。

• 检测 2.x 升级：ls "$CONFIG_DIR/commands/ralph-loop.md" 存在则 IS_UPGRADE=true，展示面向老用户的"升级完成"消息（3.0 起关键词替代 /autopilot、/ralph 等显式命令）。

• 新用户欢迎消息集中预告"无需记忆命令"的自动行为与可选魔法关键词（power-user 快捷键），可整理为速查表：

  关键词	效果	示例
  autopilot	自主执行	autopilot build me a todo app
  ralph	持久化模式	ralph: fix the auth bug
  ralplan	迭代式共识规划	ralplan this feature
  deep interview	需求访谈	deep interview me before coding
  deslop / anti-slop	清理审查	deslop this module
  tdd	TDD 模式	tdd the parser
  deepsearch	代码库检索	deepsearch where config is loaded
  ultrathink	深度推理	ultrathink this design
  cancelomc	停止活动中的 OMC 模式	cancelomc

  同时列出 Tier-0 规范工作流（omc-plan → execute → omc-review → verify，以 /oh-my-claudecode:omc-plan、/oh-my-claudecode:omc-review 形式调用）、团队用法（/oh-my-claudecode:team 3:executor "fix all TypeScript errors"，基于 Claude Code 2.1.178+ 的隐式 agent team，无 TeamCreate/TeamDelete）、MCP 注册入口与 omc hud/omc teleport/omc team status 辅助命令。5.0.0 已退役且不提供别名的命令包括 /ultrawork、/ultraqa、/ultrapilot、/swarm、/pipeline、/merge-readiness、/deep-dive、/sciomc、/ccg、/omc-teams、/setup、/mcp-setup、/omc-reference、/learner 等，替换关系见 docs/MIGRATION.md。

• 可选规则模板：可把 templates/rules 下模板复制进项目 .claude/rules/ 以获得自动上下文注入：

  mkdir -p .claude/rules
  cp "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/templates/rules/"*.md .claude/rules/
  

  各模板用途：coding-style.md（代码风格/不可变性/文件组织）、testing.md（TDD 工作流、80% 覆盖率目标）、security.md（密钥管理/输入校验）、performance.md（模型选择/上下文管理）、git-workflow.md（提交规范/PR 流程）、karpathy-guidelines.md（先思考再编码、简洁、外科手术式改动）。

• 星标引导与收尾：若 gh auth status 可用且已认证，先 gh api user/starred/... 探测是否已星标，未星标才询问；任何失败都静默放行、绝不阻塞设置完成。最终从 CLAUDE.md 的 OMC:VERSION: 标记（或 omc --version 兜底）取得版本，执行 setup-progress.sh complete "$OMC_VERSION" 写入 setupCompleted/setupVersion。

升级后维护：用快速更新替代重复向导

npm 或插件更新后无需重跑完整向导。直接运行 /oh-my-claudecode:omc-setup，预检会识别到 setupCompleted 并提供"Update CLAUDE.md and clear retired setup values"快速选项，只刷新权威 CLAUDE.md + 清理退役键即完成。这条快速路径必须执行 Phase 2 步骤 2.4（确保升级清除退役的 defaultExecutionMode），且不得写入任何替代的执行模式设置。

手动维护入口与适用场景对照：

命令	适用场景
/oh-my-claudecode:omc-setup	首次设置；或已配置时走快速更新
/oh-my-claudecode:omc-setup --local	只更新当前项目配置
/oh-my-claudecode:omc-setup --global	只更新全局配置
/oh-my-claudecode:omc-setup --force	重新配置全部偏好

这套机制让升级后能拿到最新功能与 agent 配置，同时省去重复完整向导的 token 开销；一旦中断，任意阶段都有 .omc/state/setup-state.json 兜底可续。故障排查可另用兼容命令 /oh-my-claudecode:omc-doctor（同款 Dispatch 结构）定位异常，而其背后“脚本负责解析与校验、协调器负责事务写入”的职责切分，正是整个 omc-setup 可靠性的根基。