基于 Codex CLI 的工作流层：oh-my-codex (OMX) 快速上手与团队协作实战指南

本文以仓库中的乌克兰语 README（docs/readme/README.uk.md）为骨架，结合主仓库 README.md、package.json 与 skills/、src/cli/ 等源码细节整理而成。OMX 并不替换 OpenAI Codex CLI，而是在它外面加一层"更强的默认会话 + 一致的流程 + 可复用的技能与持久状态"，适合已经习惯 Codex、但希望日常开发更顺手、任务规模变大时获得运行时协助的开发者。读完本文，你将掌握 OMX 的安装路径、以 $deep-interview → $ralplan → $team/$ralph 为核心的规范流程、团队模式与各项运维命令，并理解这些能力在仓库源码中的对应实现。

OMX 是什么：一张清晰的心智模型

OMX（Oh My codeX）是 OpenAI Codex CLI 之上的工作流层（workflow layer）。它在概念上把系统分成四部分：

• Codex：负责执行真正的 agent 工作，是底层执行引擎；
• OMX 角色关键词：让有用的角色变得可复用（例如通过 $deep-interview、$ralplan、$team、$ralph 触发）；
• OMX 技能（skills）：让常见工作流变得可复用，技能本体位于仓库的 skills/ 目录，每个技能一个 SKILL.md；
• .omx/ 目录：持久保存计划、日志、记忆与工作状态。

大多数用户应当把 OMX 理解为"更好的任务路由 + 更好的工作流 + 更好的运行时"，而不是一组需要整天手动管理的命令。换句话说：omx 帮你用更强大的默认配置启动 Codex 会话、从一个清晰的澄清阶段一路走到完成，并把项目指引（AGENTS.md）、计划、日志和状态都沉淀到 .omx/ 下。如果你只想要一个不带任何额外流程层的"裸 Codex"，那么 OMX 大概率不是你的菜。

从仓库证据看，这一"流程层"定位在 package.json 的 description 中也有体现：Multi-agent orchestration layer for OpenAI Codex CLI（面向 OpenAI Codex CLI 的多 Agent 编排层）。

安装与首次会话

环境要求

根据乌克兰语 README 与主 README 的一致口径，运行 OMX 需要：

• Node.js 20+（package.json 的 engines.node 同样标注 >=20）；
• 已安装并通过 codex --version 验证的 Codex CLI（Homebrew 或 npm 安装均可），且已完成 Codex 登录鉴权；
• tmux（macOS/Linux）：后续若要使用持久化的团队命令引擎；
• psmux（原生 Windows）：仅在需要 Windows 上的团队命令模式时安装。

两种安装路径

路径 A：Codex CLI 已安装（例如通过 Homebrew）

codex --version
npm install -g oh-my-codex
omx setup
omx --madmax --high

路径 B：还没有 Codex CLI，希望由 npm 统一管理

npm install -g @openai/codex
npm install -g oh-my-codex
omx setup

需要注意：主 README 明确提醒，不要在已由 Homebrew 管理的 codex（例如 /opt/homebrew/bin/codex）之上再执行 npm install -g @openai/codex oh-my-codex 的合并安装，否则 npm 可能因二进制同名而报 EEXIST。OMX 只要求 PATH 上有一个可用的、已鉴权的 codex 命令，并不强制要求 Codex 通过 npm 安装。

第一次会话怎么跑

安装完成后，用推荐方式启动：

omx --madmax --high

然后可以尝试一组规范的流程关键词（在 Codex 会话内直接输入）：

$deep-interview "clarify the authentication change"
$ralplan "approve the safest implementation path"
$ralph "carry the approved plan to completion"
$team 3:executor "execute the approved plan in parallel"

参数说明（结合主 README 补充）：--madmax 是 Codex 的 --dangerously-bypass-approvals-and-sandbox 的 OMX 简写，会移除常规的审批与沙箱护栏，因此只应在可信仓库与可信环境中使用；--high/--xhigh 是 -c model_reasoning_effort="high|xhigh" 的简写，用来设定模型推理强度。这一点在仓库测试 src/cli/tests/autoresearch.test.ts 中也有对应断言：normalizeAutoresearchCodexArgs(['--madmax']) 会被规约为 ['--dangerously-bypass-approvals-and-sandbox']。

规范工作流：从澄清到完成

乌克兰语 README 推荐的标准工作流是一条主线：

1. $deep-interview —— 当请求或边界还模糊时，先澄清范围；
2. $ralplan —— 把澄清后的范围转化为经审批的架构与实现计划；
3. $team 或 $ralph —— 计划获批后，若需要多 Agent 协调并行执行则用 $team；若需要单个负责人坚持不懈地循环到完成则用 $ralph。

$deep-interview：先问清楚再做

对应技能见 skills/deep-interview/SKILL.md。这是一个"意图优先"的苏格拉底式澄清循环：在规划与实现之前，通过提问弄清"为什么改、改到什么程度、什么不做、哪些决策可以不需要用户确认"，把模糊想法转成可执行、可测试的规格。它支持三种深度档位：

• --quick：快速预 PRD 澄清，目标歧义阈值 <= 0.30，最多 5 轮；
• --standard（默认）：完整需求访谈，阈值 <= 0.20，最多 12 轮；
• --deep：高严格度探索，阈值 <= 0.15，最多 20 轮。

每轮只问一个问题，先问意图与边界再问实现细节，并在每次回答后重新计算歧义分数、透明地展示收敛进度；分数降到阈值以下后才结晶需求、交接给下游规划。

$ralplan：审批计划与权衡

对应技能见 skills/ralplan/SKILL.md。它驱动 Planner → Architect → Critic 三个角色依次评审（使用 omx ralplan run --task <arguments> [--session <id>] 运行自己的共识运行时），关键开关包括：

• --interactive：在草稿评审与最终审批两个关键决策点向用户提问，否则全自动运行后直接输出最终计划；
• --deliberate：强制"深思模式"，用于高风险工作，会追加 3 个场景的 pre-mortem 与扩展测试计划（单元/集成/e2e/可观测性）；
• --advisory：独立的咨询式规划，运行同一套顺序评审但不会形成执行授权。

Critic 的评审结论非 APPROVE（即 ITERATE 或 REJECT）时会进入最多 5 次的重评审闭环（Planner 修改 → Architect 复查 → Critic 再评），直到获批或达到迭代上限。规划获批并持久化评审证据后，才进入执行阶段——不要在 Ralplan 内部直接动手实现。

$team 与 $ralph：并行执行或单线坚持

• $team：当已批准的计划需要协调的并行工作时使用。技能说明见 skills/team/SKILL.md，启动形态为 omx team [N:agent-type] "<task>"，例如 omx team 3:executor "implement X"，需要 tmux、一个持有 $TMUX 的 leader 会话以及可用的 omx 可执行文件；
• $ralph：当希望一个单一负责人持续循环到完成时使用。

版本提示（事实校准）：乌克兰语 README 仍以 $ralph 作为"坚持到完成"的规范入口，但依据 skills/ralph/SKILL.md 与主仓库 README.md，$ralph 已在 OMX 0.21 中被移除，其"循环到完成"行为被判定为 $ultragoal 单目标运行的特例，官方建议改用 $ultragoal。当前仓库 package.json 版本为 0.21.2，主 README 的规范流程已更新为 $deep-interview → $ralplan → $ultragoal。$ultragoal 对应 skills/ultragoal/SKILL.md，通过 .omx/ultragoal/brief.md、goals.json、ledger.jsonl 等持久化制品承载多目标计划与检查点。因此在新版本上，上述规范流程实际写作 $deep-interview "..." → $ralplan "..." → $ultragoal "..."（团队场景仍可叠加 $team）。

会话常用命令一览

命令	用途
$deep-interview "..."	澄清意图、边界与非目标
$ralplan "..."	审批实现计划与权衡
$ralph "..."	坚持到完成的循环与验证（0.21 起改用 $ultragoal）
$team "..."	规模足够大时做协调的并行执行
/skills	查看已安装的技能与辅助工具

团队模式（Team Mode）与平台准备

团队模式属于"高级/实用功能"，文档强调它不是开始使用 OMX 的默认方式，只有当你确实需要持久的 tmux/worktree 协调时才使用：

omx team 3:executor "fix the failing tests with verification"
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>

从 skills/team/SKILL.md 的源码级描述看，运行时会在 .omx/state/team/<name>/ 下创建 config.json、manifest.v2.json、tasks/task-<id>.json、worker 身份/收件箱、邮箱文件与派发队列；worker 会收到 OMX_TEAM_WORKER、OMX_TEAM_STATE_ROOT、OMX_TEAM_LEADER_CWD 等环境变量；omx team api send-message / read-task / transition-task-status 是推荐的可机读操作接口；omx team status <name> --json 与 omx team await <name> --timeout-ms 30000 --json 用于监控，直到 pending=0、in_progress=0、failed=0 才执行 omx team shutdown <name>。

omx team 需要一个兼容 tmux 的工具，各平台安装方式如下：

平台	安装方式
macOS	brew install tmux
Ubuntu/Debian	sudo apt install tmux
Fedora	sudo dnf install tmux
Arch	sudo pacman -S tmux
Windows	winget install psmux
Windows (WSL2)	sudo apt install tmux

运维工具链：Setup、Doctor 与 HUD

以下属于支持性运维命令，而非日常主流程：

• omx setup：安装 prompts、技能、配置与 AGENTS 结构。乌克兰语 README 特别指出，omx setup 应在受支持的范围内启用 Codex 原生 hooks（[features].hooks = true）；主 README 进一步补充了作用域选择（omx setup --scope project / --scope user）与 --merge-agents 等 AGENTS 合并策略，策略会记录在 ./.omx/setup-scope.json 中；
• omx doctor：当安装看起来有问题时检查安装状况（缺失的 OMX 文件、hooks、运行时前置条件）；
• omx hud --watch：状态监控工具（HUD），并非用户主工作流。

Sparkshell 与原生 Hooks 所有权

Sparkshell

• omx sparkshell <command> 用于终端内的冒烟测试与受限校验；
• 需要只读的仓库检索时，请使用 Codex 常规的仓库检视工具/子代理（已过时的 omx explore 命令已从项目中移除，相关说明见 docs/architecture/cli-first-mcp-taxonomy.md 所记录的 CLI 优先演进方向）。

示例：

omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400

原生 Hooks 所有权

对于非团队会话，OMX 现在主要通过 Codex 原生 hooks 工作：

• omx setup 应在受支持的范围内启用 Codex 原生 hooks（[features].hooks = true）；
• 仓库级别的本地 Codex hooks 是非团队会话的规范自动化面；
• omx tmux-hook 保留给团队命令引擎行为与旧版 tmux 问题的排障；
• 不支持或已禁用原生 hooks 引擎时，应当通过 setup/doctor 给出明确的显式状态，而不是静默回退到非团队的 tmux 实现。

完整的原生 hooks 所有权与插件契约参见 docs/hooks-extension.md。

已知问题：Intel Mac 上的高 CPU 占用

在部分 Intel Mac 上，启动 OMX（尤其是 --madmax --high）可能会让 syspolicyd / trustd 的 CPU 占用率飙升，原因是 macOS Gatekeeper 需要同时校验大量并发启动的进程。如果遇到该问题，可以尝试：

• xattr -dr com.apple.quarantine $(which omx)
• 在 macOS 安全设置中把终端加入 Developer Tools 白名单
• 降低并行度（例如避免 --madmax --high）

进一步阅读与本地化资源

乌克兰语 README 是项目多语言文档矩阵中的一份，对应的本地化文档还包括简体中文、繁体中文、日语、韩语、俄语等 16 个语种（见 docs/readme/ 目录）。建议继续阅读：

• 开始使用（Getting Started）
• Demo 演示
• Agent 目录
• 技能参考
• 集成（Integrations）
• OpenClaw 集成指南（乌克兰语）
• Hooks 扩展契约
• 参与贡献
• 变更日志

许可证

oh-my-codex 以 MIT 许可证发布，package.json 中同样标注 "license": "MIT"。

总而言之，OMX 的价值不在于替代 Codex，而在于把"澄清 → 规划 → 并行/坚持执行"这一整套高质量工作流固化下来：omx setup 负责装配，omx --madmax --high 负责用更强的配置开场，$deep-interview/$ralplan/$team（或新版本上的 $ultragoal）负责在会话内把任务从模糊推进到验证完成，而 .omx/ 则把过程中产生的计划、日志与状态全部留存，成为可复盘的持久记忆。