oh-my-codex (OMX) 深度拆解报告

"像 oh-my-zsh，但给 Codex 用。"

OMX 不替换 Codex CLI，而是把对话式的单 agent 变成了有编排、有记忆、能并行的工程流水线。

一、一句话定位

OMX 是 Codex CLI 的工作流增强层，不是替代品。

它的核心思路很简单：Codex 本身是个强大的代码生成器，但它缺少三件事——

1. 需求澄清流程（用户说不清楚自己要什么）
2. 持久状态管理（Codex 的上下文窗口会满，重启就失忆）
3. 并行执行能力（复杂任务不能只靠一个 agent 线性推进）

OMX 用一组预定义的工作流技能（Skills）和 .omx/ 目录下的持久状态来解决这三个问题。

二、四层架构：从底层到表层

2.1 Core Layer：Codex CLI 集成

OMX 不 fork Codex，也不绕过它。Codex CLI 仍然是唯一的执行引擎——所有代码生成、文件操作、命令执行都由 Codex 完成。OMX 做的是包装层（wrapper），在 Codex 之上添加结构化工作流。

这意味着：

• Codex 自身的改进（新模型、新功能）自动被 OMX 继承
• OMX 的 bug 不会破坏 Codex 的核心功能
• 卸载 OMX 就是回到原生 Codex，数据不会锁死

2.2 Workflow Layer：Skills 和 Prompts

这是 OMX 最显眼的层。核心工作流由四个关键词驱动：

除了这四个主干，还有 30+ 专业 agent 角色：

• \(tdd` — 测试驱动开发 - `\)code-review — 代码审查
• \(security-review` — 安全审计 - `\)frontend-ui-ux — 前端设计
• \(doctor` — 诊断和验证 - `\)help — 帮助系统
• \(note` — 快速笔记 - `\)trace — 追踪调试

这些不是简单的 prompt 模板，而是有生命周期管理的技能——激活、运行、退出、清理都有明确的 hook 和状态转移。

2.3 State Management Layer：.omx/ 目录

这是 OMX 与原生 Codex 最关键的区别之一。

.omx/
├── plans/           # \(ralplan 生成的审批计划
├── logs/            # 执行日志和会话历史
├── memory/          # 持久上下文和学习数据
└── mode/            # 当前工作流状态和激活的技能
```

`.omx/` 是 **durable state（持久状态）**，不依赖 LLM 的上下文窗口。重启 Codex、切换项目、甚至换机器，只要 `.omx/` 在，项目记忆就在。

对比：

| | 原生 Codex CLI | Codex + OMX |
|---|---|---|
| 规划阶段 | 无 |\)deep-interview → \(ralplan 门控 |
| 并行 workers | 无 | `omx team N:executor` 通过 tmux |
| Git 隔离 | 无 | 自动在 `.omx/team//worktrees/` 创建独立 worktree |
| 会话状态 | 丢失 | `.omx/` 持久化 plans、logs、memory |
| Hooks | 默认不接线 | 原生 `.codex/hooks.json` 的 PreToolUse/PostToolUse |
| 上下文重置后记忆 | 丢失 | Priority notepad + 项目记忆文件 |

### 2.4 Orchestration Brain：`AGENTS.md`

`AGENTS.md` 是 OMX 的"编排大脑"——项目特定的指导文件，定义：
- 项目架构和约定
- 编码标准和最佳实践
- 领域特定知识和约束
- 集成点和依赖关系

`omx setup` 会自动注入 AGENTS.md 模板，包括：
- 模型能力表（auto-generated，支持 gpt-5.5 frontier / gpt-5.4-mini / gpt-5.3-codex-spark）
- Lore commit protocol（结构化提交元数据）
- AGENTS autonomy directive（自导向 agent 操作）

---

## 三、关键设计：Team 运行时

`\)team` 是 OMX 最复杂的特性。它把单个 Codex 会话扩展为 tmux 中的多 agent 并行执行。

### 3.1 实现细节

- 每个 worker 是独立的 tmux pane，运行自己的 Codex 进程
- 每个 worker 有自己的 git worktree（`.omx/team/<name>/worktrees/worker-N`）
- Leader agent 在 orchestrator pane 中协调，通过 CLI API（`omx team api`）与 workers 通信
- Workers 可以是不同模型：Codex 默认，也可以通过 `OMX_TEAM_WORKER_CLI_MAP` 接入 Claude 或 Gemini
- 事件感知等待：`wake_on=event` / `after_event_id`，worker 完成后 leader 被唤醒

### 3.2 tmux 持久运行的工程意义

为什么用 tmux？因为 Codex CLI 是交互式的——它在终端里跑，如果窗口关了，进程就死了。tmux 提供：
- **会话持久**：关闭终端不影响后台进程
- **多 pane 布局**：orchestrator 和 workers 同时在视野内
- **HUD 监控**：`omx hud --watch` 可以实时监控所有 pane 的状态

这是把"对话式 AI"变成"工程流水线"的关键基础设施。没有 tmux，并行 workers 就是空谈。

### 3.3 安全边界

- `worker-agents.md` 是 team-scoped 的，不会修改项目的 `AGENTS.md`
- `omx exec` 和 `omx doctor` 提供执行验证和健康检查
- 代码审查 skill 要求"双视角审查"，避免单点偏差
- 安全审查 skill 专门审计注入风险

---

## 四、与 oh-my-claudecode (OMC) 的对比

OMX 和 OMC 是同一作者（Yeachan Heo）的姊妹项目，概念设计完全相同，执行引擎不同：

| | OMX | OMC |
|---|---|---|
| 执行引擎 | OpenAI Codex CLI | Claude Code |
| CLI 前缀 | `omx` | `omc` |
| npm 包名 | `oh-my-codex` | `oh-my-claude-sisyphus` |
| GitHub | Yeachan-Heo/oh-my-codex | Yeachan-Heo/oh-my-claudecode |
| 插件面 | AGENTS.md, .codex/hooks.json | Claude Code 插件市场 |

**为什么作者同时维护两个？**

因为不同用户有不同的偏好工具链。Codex 用户想要增强层就用 OMX，Claude Code 用户就用 OMC。OMX 作为 npm 包更轻量（`npm install -g`），OMC 作为 Claude Code 插件更集成。

这也体现了 OMX 的架构设计哲学：**增强而非替代**。不管是 Codex 还是 Claude，OMX/OMC 都不侵入核心引擎，只做外围编排。

---

## 五、评估：成熟度与社区

### 5.1 项目指标

| 指标 | 数值 |
|------|------|
| Stars | ~27,173 |
| Forks | ~2,201 |
| Issues | 3（活跃度低） |
| 最新版本 | v0.15.0（2026-04-25） |
| 开发节奏 | 极快——从 v0.3.7 到 v0.15.0 仅 2 个多月，100+ PR |

### 5.2 成熟度评估

**优势：**
- 架构清晰，分层设计合理
- 社区活跃，CHANGELOG 详细透明
- 多语言支持（15+）
- 与 Codex CLI 生态深度集成（hooks, plugins, AGENTS.md）
- tmux 并行 workers 是独特卖点
- 自更新机制完善（`omx update` 会刷新 setup 保持同步）

**风险：**
- 迭代速度过快（2 个月 12 个 minor 版本），API 稳定性存疑
- 只有 3 个 open issue，可能社区反馈渠道不够开放
- Team 运行时复杂度高，学习曲线陡峭
- 依赖 tmux，Windows 支持受限（虽有改进但非一等公民）

### 5.3 适合谁用？

- **不适合**：偶尔用 Codex 写个小脚本的人（overkill）
- **适合**：
  - 用 Codex CLI 做中型以上项目的开发者
  - 需要并行 workers 加速的团队
  - 想要 Codex 有持久记忆和状态管理的人
  - 喜欢 oh-my-zsh 式插件生态的用户

---

## 六、费曼视角：OMX 到底在解决什么问题？

费曼会说：**"如果你不能把它解释给一个大一学生听，那你也没真正理解。"**

好的，我来试试：

> Codex 是个很聪明的程序员，但它有个毛病——跟你聊了 50 轮后，它忘了你们第 3 轮时达成的那个关键约定。而且每次你重启终端，它从头开始。更糟的是，复杂任务它只能一件一件做，不能同时搞。
>
> OMX 就是给 Codex 配了一个助理团队：一个负责在开始干活前先跟你把需求聊清楚（\(deep-interview），一个负责写计划并确保所有人同意（\)ralplan），一个负责埋头干活的（\(ralph），还有一群能同时开工的实习生（\)team）。所有这些人的工作记录都存在一个 `.omx/` 文件夹里，Codex 失忆了就去翻笔记。

这就是 OMX 的本质：**不是让 Codex 更聪明，而是让 Codex 的工作方式更工程化。**

---

## 参考

- **仓库**: https://github.com/Yeachan-Heo/oh-my-codex
- **npm**: `npm install -g oh-my-codex`
- **文档**: https://yeachan-heo.github.io/oh-my-codex-website/
- **架构分析**: https://pyshine.com/Oh-My-Codex-Multi-Agent-Orchestration/
- **vs OMC 对比**: https://www.verdent.ai/ja/guides/what-is-oh-my-codex-omx
- **MCP 市场**: https://mcpmarket.com/tools/skills/omx-project-initializer
- **协议**: MIT