oh-my-codex 上手：给 Codex 加一层工作流和团队运行时

如果你已经在用 Codex，装 oh-my-codex 之前最好先把一件事想清楚：

它不是另一个 coding agent。

它更像是包在 Codex 外面的一层工作流和运行时，把原本你要自己维持的几件事补齐了：

• 什么时候先澄清需求

• 什么时候先把方案定下来

• 什么时候该单人持续推进

• 什么时候该并行拆给多个 worker

• 计划、日志、状态放在哪里

仓库首页那句定位写得很直接：

Start Codex stronger, then let OMX add better prompts, workflows, and runtime help when the work grows.

这基本就是它的定位。

OMX 到底是什么

README 给的定义是：

OMX is a workflow layer for OpenAI Codex CLI.

也就是说，Codex 还是执行引擎，OMX 不替掉它。 它加上去的是三层东西：

• 一套固定的工作流

• 一批可复用的 prompts / skills / agent roles

• 一层更完整的本地运行时

仓库里反复出现的 4 个关键词是：

• $deep-interview

• $ralplan

• $ralph

• $team

这 4 个入口，就是 OMX 试图固定下来的默认动作顺序。

它补的不是“更多命令”，而是默认工作顺序

README、Getting Started 和 Skills 文档都在强调同一条主线：

1. 先用 $deep-interview 把需求、边界和非目标问清楚

2. 再用 $ralplan 把方案、tradeoff 和执行计划收稳

3. 然后在执行阶段二选一： - $ralph：一个 owner 持续推进到完成 - $team：多 worker 并行执行

如果把它翻成更接地气的话，大概就是：

• 别一上来就写

• 先把需求问明白

• 再把方案定下来

• 最后再决定是一个 agent 持续推，还是开并行团队

这和很多人直接开 Codex 会话、边聊边改代码的习惯不一样。 OMX 主要补的就是这层顺序。

第一次先试这 4 个入口

第一次上手不用先研究完全部命令。

先把这 4 个摸一遍就够了。

1. $deep-interview

这是澄清入口。

适合这些情况：

• 需求还模糊

• 你只知道“要做什么”，还说不清“不做什么”

• 你担心直接开写会带偏

例如：

$deep-interview "clarify the authentication change"

它想解决的不是实现，而是边界。

2. $ralplan

这是方案确认入口。

适合这些情况：

• 需求已经清楚

• 但还没有落成能执行的计划

• 你想先把实现路径和 tradeoff 定下来

例如：

$ralplan "approve the auth plan and review tradeoffs"

这一步放在执行前。 OMX 这套设计里，计划不是顺手补一下，而是一个明确的关口。

3. $ralph

这是持续推进入口。

README 里的原话是：

• persistent completion

• persistent completion loop

可以把它理解成：

一个 agent 持续拿着同一个目标往前推，直到完成和验证。

例如：

$ralph "carry the approved plan to completion"

如果你不想一层层拆 worker，而是想让一个 owner 把事情收完，这个入口更贴切。

4. $team

这是并行执行入口。

例如：

$team 3:executor "execute the approved plan in parallel"

从 README 到 DEMO 文档，$team 都被定位成“协同并行执行”，不是默认上来就开。 它更像是在计划已经清楚以后，才启动的一层团队运行时。

第一天怎么装，装完先怎么试

按文档给的最短路径，先做 3 步：

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

omx setup

omx doctor

要求也不复杂：

• Node.js 20+

• Codex CLI 已安装

• Codex 已完成认证

第一步是全局安装：

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

这里一次装了两个东西：

• @openai/codex

• oh-my-codex

装完以后，先确认两个命令都在：

codex --version

omx version

安装完成后先确认 Codex 和 OMX 都可用

第二步是跑 omx setup：

omx setup

第一次运行 omx setup 时，会把 prompts、skills、AGENTS.md 和配置一起补齐

这一步不是简单写几个配置。按仓库的 demo，它至少会做这些事：

• 安装 agent prompts

• 安装 skills

• 更新 Codex 的配置

• 生成项目里的 AGENTS.md

• 配置 notification hook

• 配置 HUD

如果你是第一次装，最值得确认的是这几类结果：

• ~/.codex/prompts/ 里有 OMX 的 prompts

• ~/.codex/skills/ 里有 OMX 安装进去的 skills

• 当前项目根目录出现 AGENTS.md

setup 跑完后，终端里会给出刷新结果和后续动作

第三步是跑 omx doctor：

omx doctor

omx doctor 会把安装、配置、skills、AGENTS.md 和 MCP 配置一起过一遍

这一步相当于验收。README 和 demo 里给的检查项主要有这些：

• Codex CLI 是否安装

• Node.js 版本是否符合要求

• ~/.codex 是否存在

• config.toml 里有没有 OMX 配置

• prompts 和 skills 有没有装进去

• 项目里的 AGENTS.md 是否生成

• .omx/state 这类状态目录是否可用

• MCP 配置是不是完整

如果只是第一轮体验，接下来直接这样开：

omx

或者在信任环境里，按它推荐的高强度参数开：

omx --madmax --high

然后不要去试一堆命令。 直接按这条顺序走一遍：

$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"

这样第一轮体验会更直接。

如果你后面想试 team runtime，再补平台依赖：

• macOS / Linux：装 tmux

• Windows：装 psmux

如果安装过程里一开始就不顺，先查这几项：

• omx 命令是不是在 PATH 里

• omx setup 跑完后，~/.codex/prompts/ 和 ~/.codex/skills/ 里有没有内容

• omx doctor 报的是配置问题，还是安装问题

• 项目根目录下有没有生成 AGENTS.md

.omx/ 和 AGENTS.md，才是它和普通命令集合的区别

只看首页命令，很容易把 OMX 误解成“帮 Codex 多装一些 prompt”。

但它和单纯 prompt 包的区别，主要在两块：

1. AGENTS.md

Getting Started 文档写得很清楚，OMX 默认会通过：

-c model_instructions_file="<cwd>/AGENTS.md"

把项目里的 AGENTS.md 接进 Codex 会话。

这意味着它不是单纯装全局 prompt，而是在项目目录里生成一层面向当前仓库的指导文件。

2. .omx/

README 直接把 .omx/ 定义成：

• plans

• logs

• memory

• runtime state

也就是说，OMX 不只是在给你提供命令，还在提供一块稳定的本地状态目录。

这和纯 prompt/skill 集的差别在于：

它开始关心运行时。

团队模式不是口号，仓库里已经把运行时铺开了

如果只看首页，你会以为 $team 只是“多开几个 agent”。

但 DEMO 文档展开以后，团队模式其实是一套更重的东西：

• tmux session

• leader pane

• worker pane

• shared task queue

• mailbox communication

• claim-safe task lifecycle

• status / resume / shutdown

文档里甚至给了完整的 omx team api 命令矩阵，包括：

• create-task

• claim-task

• transition-task-status

• send-message

• broadcast

• mailbox-list

• mailbox-mark-delivered

这说明它的团队模式不是口头上的并行，而是把任务领取、状态迁移、消息收发、恢复和清理都写进了 CLI。

这也是为什么它要求：

• macOS/Linux 用 tmux

• Windows 用 psmux

这部分更接近一个本地编排运行时，不只是普通命令助手。

HUD、doctor、explore、sparkshell 这些东西，说明它已经不只是 workflow

首页把这些都归为 operator surfaces：

• omx setup

• omx doctor

• omx hud --watch

• omx explore --prompt "..."

• omx sparkshell ...

这里能看出另一层意思：

OMX 不只是想规范你“怎么想、怎么计划、怎么执行”，还想把观测和辅助操作一起包进去。

比如：

• doctor 负责查安装状态

• hud 负责状态观察

• explore 负责只读检索

• sparkshell 负责 shell-native inspection 和有边界的验证

做到这一步，它已经不太像“工作流模板”，而更像一层本地开发 runtime。

OpenClaw 集成也说明了一件事：它在往通知和外部协同扩

仓库里还有一份单独的 openclaw-integration 指南，讲的是：

• notification hooks

• webhook / CLI gateway

• session-start

• session-idle

• ask-user-question

• session-end

而且不只是消息推送，还支持通过 clawdbot agent command 做后续跟进。

这一层不是每个人第一天都会用到，但能看出 OMX 的方向：

它不满足于把 Codex 包起来，还想把会话事件往外抛，把外部协同也接进来。

这套东西适合谁

更适合下面这几类人：

• 已经在长期用 Codex

• 觉得自己每次会话都在重复做澄清、规划、收尾

• 开始需要并行 worker 或团队模式

• 愿意接受一套固定工作顺序

如果你现在已经有明确痛点，像是：

• 需求总是没问清就开写

• 计划经常是边做边补

• 想把并行执行拉进终端工作流

• 想把计划、日志、状态和消息都留在本地运行时里

OMX 会更对路。

哪些人先别急着装

如果你现在的使用习惯是：

• 就想开一个干净的 Codex

• 不想多一层 workflow

• 不想接受固定的命令顺序

• 也暂时不需要 team runtime、HUD、doctor、通知和状态目录

那你可能并不需要 OMX。

README 其实也说得很直：

If you want plain Codex with no extra workflow layer, you probably do not need OMX.

这句已经把边界说清了。

最后一句

如果只用一句话概括这个项目：

oh-my-codex 不是在替 Codex 再造一个 agent，而是在 Codex 外面补了一层更完整的工作流和运行时。

它真正要解决的，不是“模型会不会写”，而是当工作变大以后，澄清、规划、并行、状态和协同怎么收进一套默认动作里。

项目名：Yeachan-Heo/oh-my-codex