oh-my-codex 使用教程与最佳实践
文章目录
- 1. 这是什么
- 2. 适合谁用
- 3. 版本说明
- 4. 安装与启动
- 4.1 前置要求
- 4.2 推荐安装
- 4.3 推荐启动
- 5. OMX 的核心心智模型
- 5.1 常见命令词释义
- `deep-interview`
- `ralplan`
- `ralph`
- `team`
- `explore`
- `sparkshell`
- `setup`
- `doctor`
- `review`
- `code-review`
- `security-review`
- `hooks`
- `native hooks`
- `tmux`
- `madmax`
- `high`
- `prompt`
- `skill`
- `agent`
- 6. 最推荐的标准工作流
- 6.1 每个阶段的职责
- 6.2 我建议的选择规则
- 7. 常用命令与使用时机
- 7.1 基础命令
- 7.2 团队协作
- 7.3 只读代码探索
- 7.4 Shell 检查与验证
- 8. 安装后会写入什么
- 9. 最佳实践
- 9.1 不要一开始就沉迷团队模式
- 9.2 `project` 级 setup 通常优于 `user` 级 setup
- 9.3 默认优先 `$ralph`，不是 `$team`
- 9.4 把 `omx explore` 和 `omx sparkshell` 用起来
- 9.5 hooks 安装后先验证
- 9.6 通知集成先最小化接入
- 9.7 `omx doctor` 优先于“重装试试”
- 10. 三个完整实战示例
- 示例一：0 到 1 功能开发
- 目标
- 推荐流程
- 第一步：启动 OMX
- 第二步：先澄清需求
- 第三步：产出正式计划
- 第四步：如果需要，先做代码结构探索
- 第五步：进入执行
- 第六步：把代码审核融进交付前流程
- 第七步：验证
- 这一类任务的最佳实践
- 一条可以直接照抄的完整输入链
- 示例二：1 到 N 的新功能开发
- 目标
- 推荐流程
- 第一步：先查现有结构
- 第二步：确认新增边界和兼容性
- 第三步：必要时进入并行执行
- 第四步：在开发中途插入定向代码审核
- 第五步：验证和收尾
- 这一类任务的最佳实践
- 一条可以直接照抄的完整输入链
- 示例三：代码审核作为独立流程
- 目标
- 推荐流程
- 第一步：先理解改动范围
- 第二步：发起代码审核
- 第三步：把审核结果转成行动
- 最佳实践
- 11. 我建议你日常这样用
- 轻量稳妥型
- 需求复杂型
- 大任务并行型
- 12. 一些容易踩的坑
- 13. 总结
- 14. 参考资料
1. 这是什么
oh-my-codex，简称OMX，是运行在OpenAI Codex CLI外层的一套工作流和运行时增强。
它不是替代 Codex，而是给 Codex 增加这些能力：
- 更强的默认启动方式
- 标准化的需求澄清、规划、执行、验证流程
- 可复用的技能入口，例如
$deep-interview、$ralplan、$ralph、$team - 项目级上下文沉淀，例如
AGENTS.md、.omx/状态、计划、日志、记忆 - Native hooks、tmux 团队协作、通知集成等增强能力
一句话理解：
Codex 负责“执行”，OMX 负责“让执行更稳定、更有方法、更适合复杂任务”。
2. 适合谁用
适合以下人群：
- 经常用 Codex 做中大型开发任务的人
- 希望把“澄清需求 -> 规划 -> 执行 -> 验证”固定成标准流程的人
- 希望在项目里长期沉淀代理规则和执行状态的人
- 需要多人协作式并行开发体验的人
如果你只想用最原始、最轻量的 Codex，不需要工作流层，那你未必一定需要 OMX。
3. 版本说明
截至 2026-04-09，我核对到的版本状态如下：
- GitHub 仓库已有
v0.12.4tag - npm registry 当前
latest为0.12.3
这意味着：
- 如果你直接
npm install -g oh-my-codex，大概率拿到的是0.12.3 - 如果你参考 GitHub
main分支文档，会看到比 npm 包更靠前的一些能力说明
写教程和落地时，建议优先以“当前 npm 可安装版本 + 主分支文档趋势”一起理解。
4. 安装与启动
4.1 前置要求
- Node.js 20+
- 已安装并完成认证的
OpenAI Codex CLI - macOS / Linux 下如果要用团队模式，建议安装
tmux - Windows 原生环境如需团队模式，文档建议使用
psmux
4.2 推荐安装
npminstall-g@openai/codex oh-my-codex omx setup4.3 推荐启动
默认推荐启动方式：
omx--madmax--high更稳妥的启动方式：
omx--high说明：
--high表示更高的推理强度--madmax会映射到更激进的放行模式- 在你完全信任当前环境时再使用
--madmax
如果你想把 leader 会话直接放进 tmux：
omx--tmux--madmax--high5. OMX 的核心心智模型
你可以把 OMX 理解为 5 层：
Codex CLI：真正执行任务的代理引擎AGENTS.md：项目级代理规则prompts/与skills/：角色与工作流快捷入口.omx/：计划、状态、记忆、日志hooks / team runtime / 通知：自动化和协作增强层
最重要的一点是：
不要把 OMX 理解成“很多命令”，而要把它理解成“把复杂任务做顺的一套流程”。
5.1 常见命令词释义
为了方便中文使用者理解，下面把文档里最常出现的一些英文命令词做一个简明释义，并附上音标。
deep-interview
deep/diːp/：深的、深入的interview/ˈɪn.t̬ɚ.vjuː/：访谈、面谈- 合起来可以理解为：
深入访谈式澄清 - 在 OMX 里表示：先通过追问把需求、边界、非目标问清楚
ralplan
- 这是一个项目内工作流命名，不是标准英语单词
- 可以把它理解为：
一种用于形成正式计划和共识的规划流程 plan/plæn/：计划、规划- 在 OMX 里表示：把已澄清的需求整理成可执行、可评审的正式方案
ralph
Ralph/rælf/：英语人名，项目里被借用为工作流名称- 在 OMX 里表示：
持续推进直到完成的执行模式 - 你可以把它记成：
单负责人持续推进模式
team
team/tiːm/：团队、小组- 在 OMX 里表示：多代理并行协作模式
explore
explore/ɪkˈsplɔːr/：探索、查找、探查- 在 OMX 里表示：只读代码探索、结构定位、关系梳理
sparkshell
spark/spɑːrk/：火花、快速触发shell/ʃel/：命令行 shell- 合起来可以理解为：
轻量快速的 shell 检查入口 - 在 OMX 里表示：执行命令检查、读取输出、做有限验证
setup
setup/ˈset.ʌp/：安装、配置、初始化- 在 OMX 里表示：安装 prompts、skills、AGENTS、hooks、
.omx/等运行基础设施
doctor
doctor/ˈdɑːk.tɚ/：医生- 在命令行工具语境里通常引申为：
诊断问题 - 在 OMX 里表示：检查安装状态、配置状态、运行环境问题
review
review/rɪˈvjuː/：审查、复查、评审- 在 OMX 里表示：对当前实现做质量评审
code-review
code/koʊd/：代码review/rɪˈvjuː/：审查- 合起来可以理解为：
代码审查 - 在 OMX 里表示：重点检查逻辑问题、回归风险、边界条件和缺失测试
security-review
security/səˈkjʊr.ə.t̬i/：安全review/rɪˈvjuː/：审查- 合起来可以理解为：
安全审查 - 在 OMX 里表示：重点检查权限、数据、命令执行、金额计算等安全风险
hooks
hook/hʊk/：钩子、挂钩点hooks/hʊks/：多个钩子