OpenAI Codex CLI 是一个强大的 AI 编程执行器，但它有一个核心限制：只能单轮对话、没有工作流记忆、无法并行分工。
Oh-My-Codex (OMX) 在不替换 Codex 的前提下，为它套上了一层完整的"智能体外骨骼"
30 个专家 Agent、40 个可复用 Skill、4 个 MCP 状态服务器、tmux 原生多进程隔离，以及完整的任务生命周期状态机。
以下是 OMX 的核心架构和使用教程。
核心洞察：Codex 本体不是瓶颈，工作流才是
OMX 的设计哲学建立在一个清醒的判断上：当下 AI 编程的核心瓶颈，已经不是"模型有多聪明"，而是"如何组织一个大型任务让模型持续推进而不迷失"。
原生 Codex 的问题不在于能力，而在于缺乏：
- 澄清任务边界的机制
- 把规划和执行解耦的流程
- 在多个并行方向上协调工作的基础设施
- 跨会话保存上下文和状态的持久层
OMX 逐一补齐了这四块短板。
四步黄金工作流：从混沌到可执行
OMX 的核心是一套经过大量实战验证的四步标准 SOP，每一步对应一个专用命令关键字：
$deep-interview：苏格拉底式需求澄清
在你还没想清楚需求时，OMX 化身苏格拉底反向拷问用户。v0.14.0 引入结构化问题义务（pending-question obligations），未回答的关键问题会锁住 Stop 操作，阻止 AI 仓皇开干。
$ralplan：强制输出 PRD
澄清边界后，强制输出带架构图和实施步骤的 PRD。它会暴露可观测的运行时状态（Live ralplan state visibility），让 HUD 和 Pipeline 都能跟踪规划进度，供人类审核后再放行。
$team N:executor：并行 Agent 编队
一键在 tmux 里拉起 N 个并行 Agent（支持 Codex + Claude 混合编队）。每个 Worker 独占一个 git worktree，彼此隔离，通过版本化 Claim Token 竞争领取任务队列中的子任务，防止 race condition。
$ralph：单一 Owner 持续执行
当某个任务需要单一 Owner 持续死磕时，Ralph 模式会持续发送"continue steer"心跳信号，并在进度停滞时自动扩展 max_iterations，直到任务完成为止。
四层 MCP 状态引擎：让记忆跨越会话边界
OMX 内置 4 个 MCP（Model Context Protocol）服务器，赋予 Agent 一套可持久化、可查询的外脑：
- omx_state — 会话级模式状态（ralplan/ralph/team 是否激活）
- omx_memory — 跨会话的项目长期记忆（project-memory.json）
- omx_code_intel — 代码库结构索引和符号检索
- omx_trace — 完整的执行轨迹追溯（可事后审计）
.omx/ 目录结构是持久化外脑的核心。AGENTS.md 是整个系统的编排大脑，由 omx setup 自动生成：里面包含 30 个 Agent 的角色描述、委派规则、40 个 Skill 的触发模式、模型路由策略（按复杂度分配 gpt-5.5 / gpt-5.4-mini / gpt-5.3-codex-spark 三档）。
Codex 在每次会话启动时自动加载它，相当于给 AI 团队发放了岗位说明书和组织架构图。
任务队列的工业级保障：Claim-Safe 生命周期
OMX 的团队运行时实现了一套完整的分布式任务状态机，这是大多数"多 Agent"框架根本没有的东西：
Claim-Safe 任务生命周期（防 race condition）
- create-task
- claim-task (versioned token)
- in_progress
- transition-task-status
- completed / failed
- release-task-claim（失败时归还任务）
Worker 必须持有版本化的 Claim Token 才能修改任务状态。某个 Worker 崩溃后，Token 自动失效，任务被重新放回队列供其他 Worker 接管——和真实的分布式系统如出一辙。
Worker 之间通过 Mailbox 收发结构化消息（send-message / broadcast / mailbox-mark-delivered），Leader 通过 HUD（实时 status line）监控全局进度，同时 omx hud --watch 提供独立的监控视窗，不打扰工作 pane。
Rust 原生引擎：omx explore 与 sparkshell
v0.9.0 起，OMX 引入了 Rust 编写的原生探索引擎，以 omx-explore-harness 和 omx-sparkshell 两个二进制形式分发，在 npm install 后自动解压到本地缓存。
为什么要用 Rust 做这件事？
- omx explore 需要在大型 repo 里做高速文件树遍历和符号搜索（底层集成了 ripgrep）
- sparkshell 是只读的 Shell 原生检视工具，需要在沙箱中以极低延迟执行 git status / ps / tail 等命令并汇总结果
TypeScript 无法在这个场景下达到足够低的启动时间，Rust 原生二进制才是正确答案。
两分钟部署全套战队
前提：Node.js 20+，OpenAI API Key 已配置，macOS/Linux 需安装 tmux。
Step 1：全局安装
npm install -g @openai/codex oh-my-codexStep 2：一键初始化
omx setup && omx doctor（安装 30 Agent + 40 Skill + 4 MCP 服务器 + AGENTS.md）
Step 3：以强力模式启动，并拉起 3 个并行执行者
omx --madmax --high
# 在会话内输入：
$ralplan "重构认证模块，引入 JWT 并添加单测"
$team 3:executor "按上面的计划并行执行"总结
OMX 最令人印象深刻的地方，是它把一个原本"聪明但混乱"的 AI 程序员，改造成了一个有 SOP、有记忆、有分工、有监控的工程团队。它证明了一件事：AI 协作的天花板不在于单个模型的参数量，而在于多智能体之间的协调质量。
苏米注：OMX 的设计思路值得所有 AI 编程工具用户学习。与其追求单个模型的能力上限，不如花时间在"如何组织任务"上。Claim-Safe 任务生命周期、MCP 持久化外脑、Rust 原生引擎——这些设计决策体现了对分布式系统和工程实践的深刻理解。