oh-my-codex（OMX）完整实战指南：为 OpenAI Codex CLI 构建提示词、工作流与运行时增强层

OMX（Oh My codeX）是构建在 OpenAI Codex CLI 之上的一层开源工作流扩展：它不替换 Codex，而是让 Codex 从第一个会话起就更强——提供更完善的配置、从需求澄清到交付的一致工作流（$deep-interview → $ralplan → $team/$ultragoal）、可复用的 Skill 封装，以及将项目指导、计划、日志与运行时状态统一存放在 .omx/ 目录的持久化机制。读完本文，你将掌握 OMX 的安装路径、核心会话工作流、常用命令速查、Team 多 worker 并行运行时的开启方式，以及 Sparkshell、HUD、doctor 等进阶运维工具的使用方法，并理解这些功能在仓库源码中的底层实现。

OMX 用来做什么：一个简单的心智模型

OMX 不 是 Codex 的替代品，也不是一个需要整天手动敲命令的"控制面板"。它是在 Codex 之上补充的一层支持：

• Codex 仍然是唯一的执行引擎，承担全部真实工作；
• OMX 的角色（Role） 让你能快速调用专业分工的角色（如 executor）；
• OMX 的 Skill 把常见工作流封装成一条命令（如 $deep-interview、$ralplan、$team）；
• .omx/ 目录 持久化保存计划、日志、记忆与运行时状态。

用一句话概括：OMX 的价值是更合理的任务分发 + 更清晰的工作流 + 更稳定的运行时。如果你只想用纯 Codex、不需要任何额外工作流层，那么大概率不需要 OMX。这一模型与仓库根目录 README.md 中 "OMX does not replace Codex" 的定位完全一致，也是理解后续所有命令的出发点。

环境要求与安装

前置条件

条件	说明
Node.js 20+	运行 OMX 的 JavaScript 运行时，见 package.json 中 engines.node 声明
Codex CLI	已安装且可用 codex --version 验证（Homebrew 或 npm 安装均可）
Codex 认证	在运行 OMX 的同一 shell/profile 中完成 Codex auth
tmux	macOS/Linux 上使用 Team 运行时（推荐路径）所需
psmux	Windows 上使用 Team 模式所需（较少受支持的路径）

两条安装路径

如果 Codex CLI 已经安装（例如通过 Homebrew）：

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

如果尚未安装 Codex CLI，希望由 npm 一并管理：

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

从当前仓库源码看（package.json），官方 npm 包名为 oh-my-codex，版本 0.21.2，二进制入口为 omx（dist/cli/omx.js）。安装后在目标 git 项目中执行 omx setup 即可安装 skill、prompt、CLI-first 配置并按 scope 生成 AGENTS.md。

安装后的边界检查

在把运行时视为"就绪"之前，建议按 README.md 的做法先做双重冒烟测试：omx doctor 检查安装形态，omx exec 验证当前环境的 Codex 运行时确实能完成一次真实的模型调用：

omx doctor
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

omx doctor 能发现缺失的 OMX 文件、hooks 与运行时前置依赖；而真正的冒烟测试才能暴露只在 Codex 发起真实请求时才出现的 auth、profile 与 provider/base-URL 问题。

首次会话与核心工作流

安装并完成 omx setup 后，启动 OMX：

omx --madmax --high

其中 --madmax 是 OMX 对 Codex --dangerously-bypass-approvals-and-sandbox 的简写（会绕过审批与沙箱，只在可信仓库与环境中使用），--high 是 -c model_reasoning_effort="high" 的简写。这些 flag 的完整语义可以在 CLI 帮助文本 中查到。

然后尝试 OMX 的核心工作流：

$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ralph "carry the approved plan to completion"
$team 3:executor "execute the approved plan in parallel"

推荐路径是：先启动 OMX，需求模糊时先澄清，再审批计划，最后按需选择并行或单 agent 交付——需要多个 worker 并行时用 $team，想要一个 agent 从头跟到尾时用 $ralph。

从 skills/deep-interview/SKILL.md 可以看到该流程的源码级设计：$deep-interview 是"意图优先"的苏格拉底式澄清循环，以数学化的模糊度评分（ambiguity scoring）作为执行前的门槛，支持 --quick（阈值 ≤0.30，最多 5 轮）、--standard（默认，阈值 ≤0.20，最多 12 轮）、--deep（阈值 ≤0.15，最多 20 轮）三档深度档位，并强制要求 Non-goals 与 Decision Boundaries 就绪后才能交接给下游执行。

新人起步清单

1. 运行 omx setup
2. 以 omx --madmax --high 启动
3. 需求模糊时用 $deep-interview "..." 澄清
4. 用 $ralplan "..." 审批计划并权衡取舍（trade-off）
5. 需要并行时选 $team，需要单 agent 一路做完时选 $ralph

推荐工作流

1. $deep-interview —— 当需求边界模糊时澄清范围；
2. $ralplan —— 把澄清后的范围转成可审批的实现计划；
3. $team 或 $ralph —— 任务够大需要多 worker 并行时用 $team，想要一个 agent 持续跑到完成并验证时用 $ralph。

会话内常用命令速查

命令	使用时机
$deep-interview "..."	澄清意图、范围（scope）与非目标（non-goal）
$ralplan "..."	审批实现计划与 trade-off
$ralph "..."	持续运行直到完成并验证
$team "..."	任务足够大时并行执行
/skills	查看已安装的 skill 与 helper 列表

版本差异提示：$ralph 已被 $ultragoal 取代

需要注意的是，本文所依据的越南语版 README（docs/readme/README.vi.md）撰写于较早版本，其中把 $ralph 作为默认完成路径之一。而当前仓库已演进到 0.21.2（见 package.json），skills/ralph/SKILL.md 已明确标注为 sunset stub：$ralph 在 OMX 0.21 中被移除，请改用 $ultragoal。

迁移要点：Ralph 的"循环直到完成"行为本质上是退化的单目标 ultragoal 运行。$ultragoal 拥有持久的 Codex goal 交接、.omx/ultragoal 账本检查点、实现与测试/构建/lint/typecheck 证据、以及跨 story 的续跑能力。因此最新版推荐流程实际为 $deep-interview → $ralplan → $ultragoal（或 $team 在需要协调并行时使用）。本文为忠实继承原文档，仍完整保留 $ralph 相关命令与语义，但请读者以 $ultragoal 作为默认完成路径。

进阶主题

以下内容对日常使用很有价值，但不属于启动阶段的核心步骤。

Team runtime：tmux 协调的多 worker 并行

当需要跨 tmux/worktree 协调多个 worker 时使用 team runtime：

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 team [N:agent-type] "<task>" 启动 N 个持久化 tmux worker pane，运行时会在 .omx/state/team/<name>/ 下创建 config.json、manifest.v2.json、任务文件、worker 身份/inbox 与派发队列，并通过 omx team api 系列命令进行机器可读的状态操作（如 send-message、read-task、transition-task-status）。团队运行的收尾条件是 pending=0、in_progress=0、failed=0（或显式确认的失败路径），只有满足这些条件后才应执行 omx team shutdown <name>。

Setup、doctor 与 HUD：运维与辅助工具

• omx setup 安装 prompt、skill、config，并脚手架生成 AGENTS；
• omx doctor 在安装出现问题时检查安装健康度（还支持 --repair-state 归档陈旧状态、--team 检查团队运行时诊断）；
• omx hud --watch 以 HUD 状态栏方式持续跟踪运行时状态——注意它是辅助工具，不是主工作流。

Sparkshell：可控的 shell 命令执行

• omx sparkshell <command> 执行 shell 命令并控制输出；
• 需要仓库只读检索时，应使用 Codex 常规的仓库检查工具/subagent（旧的 omx explore 命令已过时并被移除）。

示例：

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

从 sparkshell 命令实现 可以看到，omx sparkshell 实际调用的是原生 Rust sidecar 二进制（omx-sparkshell），支持三种模式：直接 argv 执行、显式 --shell 的 shell 执行（shell 元字符只有在显式 opt-in 时才解释）、以及 --tmux-pane <pane-id> [--tail-lines <100-1000>] 的 tmux pane 输出摘要模式。--tail-lines 必须介于 100 与 1000 之间。当原生二进制不可用（如 GLIBC 不兼容）时，命令会回退到不带摘要能力的裸命令执行。

按平台安装 tmux

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

已知问题：Intel Mac 启动时 syspolicyd / trustd CPU 飙高

在部分 Intel Mac 上启动 OMX——尤其是使用 --madmax --high 时——CPU 可能因 macOS Gatekeeper 同时校验多个进程而出现瞬时飙升。若遇到此情况，可以尝试：

• xattr -dr com.apple.quarantine $(which omx)
• 在 macOS 的"安全性与隐私"设置中，把终端应用加入 Developer Tools 列表
• 改用更轻量的配置（去掉 --madmax --high）

延伸阅读

• Getting Started 指南
• Demo 演示
• Agent 目录
• Skill 参考
• 集成指南
• OpenClaw / notification gateway 指南
• 贡献指南
• 变更日志
• 项目规范入口 README.md
• 各语言 README 索引（含越南语版 README.vi.md）见 docs/readme

项目定位速览：OMX 是一个多 agent 编排层（Multi-agent orchestration layer for OpenAI Codex CLI），采用 MIT 许可证。核心维护者为 Yeachan Heo 与 HaD0Yun。建议首次使用遵循"omx setup → 冒烟测试 → 工作树启动 → 澄清 → 计划 → 执行"的路径，把 OMX 的提示词、工作流与运行时能力逐步叠加到日常 Codex 会话之上。