oh-my-codex - 基于 OpenAI Codex CLI 的结构化工作流与运行时层

约 1572 字大约 5 分钟

AICodexAgentWorkflow

2026-04-09

简介

oh-my-codex（简称 OMX）是一个构建在 OpenAI Codex CLI 之上的工作流与运行时层。它并不取代 Codex，而是通过结构化的任务路由、一致的 Agent 工作流、持久化状态管理和协调的并行执行能力来增强 Codex 的原始功能。

该项目由 Yeachan-Heo 开发，采用 TypeScript 编写，核心定位是为复杂的 AI 辅助编码会话提供一个可靠、可重复的运行时环境，让开发者能够从意图澄清到任务完成的整个流程都保持结构化和可追踪。

解决什么问题？

原始的 OpenAI Codex CLI 在以下方面缺乏内置支持：

多步骤工作流：没有标准化的方式来串联澄清、规划、审批、执行等阶段
持久化上下文：会话之间的状态和上下文无法自动保存与恢复
多 Agent 协调：缺乏并行执行和角色分工的机制
可重复性：同样的任务在不同时间运行可能得到不同结果

OMX 通过以下方式解决这些痛点：

提供 Canonical Skills（$deep-interview、$ralplan、$ralph、$team）来标准化各个阶段
使用 .omx/ 目录实现计划、日志、内存和运行时状态的持久化存储
支持基于 tmux/psmux 的并行团队运行时，实现多 Agent 协调
通过结构化路由和钩子集成确保行为的可重复性

核心概念

概念	说明
Canonical Skills	OMX 预定义的标准技能，包括意图澄清（`$deep-interview`）、规划与审批（`$ralplan`）、持久化完成（`$ralph`）和并行执行（`$team`）
`.omx/` 目录	持久化存储目录，保存计划、日志、内存、运行时状态和钩子配置
Hooks	与 Codex 原生钩子（`.codex/hooks.json`）集成的事件机制，位于 `.omx/hooks/*.mjs`
HUD	实时监控界面（`omx hud --watch`），用于跟踪任务和 Agent 状态
Explore	只读的仓库探索模式（`omx explore`），用于安全地分析和理解代码库
Sparkshell	受限的 Shell 验证环境（`omx sparkshell`），用于安全执行和验证命令
AGENTS.md	项目级上下文规则文件，为不同目录提供 scoped 的配置和指导

安装与配置

前置要求：

Node.js 20+
OpenAI Codex CLI 已安装并配置认证
tmux（macOS/Linux）或 psmux（Windows），用于团队并行模式

安装命令：

# 全局安装 Codex CLI 和 oh-my-codex
npm install -g @openai/codex oh-my-codex

初始化：

# 生成脚手架配置和 Codex 钩子
omx setup

# 可选：验证安装是否正确
omx doctor

使用方式

基本用法

启动一个 OMX 会话：

# 基础启动
omx

# 启用激进模式和高性能设置
omx --madmax --high

# 启用终端复用器模式（需要 tmux）
omx --madmax --high --tmux

Canonical 工作流

OMX 推荐的标准四阶段工作流：

# 1. 意图澄清 - 让 AI 通过提问理解你的需求
$deep-interview "clarify the authentication change"

# 2. 规划与审批 - 生成并审查最安全的实现路径
$ralplan "approve the safest implementation path"

# 3. 持久化执行 - 将审批通过的计划执行到完成
$ralph "carry the approved plan to completion"

# 4. 并行执行 - 多 Agent 并行执行已审批的计划
$team 3:executor "execute the approved plan in parallel"

团队管理

# 启动 3 个并行 Agent 执行任务
omx team 3:executor "fix the failing tests with verification"

# 查看团队状态
omx team status <team-name>

# 关闭团队
omx team shutdown <team-name>

探索与验证

# 只读探索代码库
omx explore --prompt "find where team state is written"

# 在受限 Shell 中验证命令
omx sparkshell git status

# 实时监控面板
omx hud --watch

实际示例

假设你接到一个任务：为现有的 Node.js 项目添加 OAuth2 认证系统。

步骤 1：启动会话

cd your-project
omx --madmax --high

步骤 2：意图澄清

$deep-interview "add OAuth2 authentication with GitHub provider to the existing Express app"

AI 会询问你一系列问题来澄清需求：是否需要支持多个 Provider、用户表结构如何设计、是否保留现有认证方式等。

步骤 3：生成并审批计划

$ralplan "implement OAuth2 with minimal changes to existing routes, add fallback to local auth"

生成详细的实现计划，包括需要修改的文件、新增的依赖、数据库迁移等，供你审查。

步骤 4：执行计划

$ralph "execute the approved OAuth2 implementation plan"

AI 按照审批的计划逐步实现，并将进度和状态持久化到 .omx/ 目录。

步骤 5：并行验证

$team 2:verifier "write tests for the new auth routes and verify existing tests still pass"

启动 2 个并行 Agent，一个编写新认证的测试，另一个验证现有测试未被破坏。

整个过程中，你随时可以通过 omx hud --watch 监控进度，或在任何阶段介入审查和调整计划。

确保任务之间没有共享状态的冲突
使用 omx team status 跟踪各 Agent 进度
复杂任务建议先用 $ralplan 拆分好再并行

持久化状态的利用

.omx/ 目录保存了完整的会话状态，这意味着：

可以中断会话后恢复继续工作
便于团队协作，其他人可以理解当前进度
出现问题时可以回溯和审计 AI 的决策过程

探索模式用于代码审查

使用 omx explore 的只读模式来安全地分析和理解大型代码库。它不会修改任何文件，适合用于代码审查、架构分析或生成文档。