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` 级 setup9.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.4tagnpm registry 当前latest为0.12.3这意味着：如果你直接npm install -g oh-my-codex，大概率拿到的是0.12.3如果你参考 GitHubmain分支文档，会看到比 npm 包更靠前的一些能力说明写教程和落地时，建议优先以“当前 npm 可安装版本 + 主分支文档趋势”一起理解。4. 安装与启动4.1 前置要求Node.js 20+已安装并完成认证的OpenAI Codex CLImacOS / Linux 下如果要用团队模式，建议安装tmuxWindows 原生环境如需团队模式，文档建议使用psmux4.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-interviewdeep/diːp/：深的、深入的interview/ˈɪn.t̬ɚ.vjuː/：访谈、面谈合起来可以理解为：深入访谈式澄清在 OMX 里表示：先通过追问把需求、边界、非目标问清楚ralplan这是一个项目内工作流命名，不是标准英语单词可以把它理解为：一种用于形成正式计划和共识的规划流程plan/plæn/：计划、规划在 OMX 里表示：把已澄清的需求整理成可执行、可评审的正式方案ralphRalph/rælf/：英语人名，项目里被借用为工作流名称在 OMX 里表示：持续推进直到完成的执行模式你可以把它记成：单负责人持续推进模式teamteam/tiːm/：团队、小组在 OMX 里表示：多代理并行协作模式exploreexplore/ɪkˈsplɔːr/：探索、查找、探查在 OMX 里表示：只读代码探索、结构定位、关系梳理sparkshellspark/spɑːrk/：火花、快速触发shell/ʃel/：命令行 shell合起来可以理解为：轻量快速的 shell 检查入口在 OMX 里表示：执行命令检查、读取输出、做有限验证setupsetup/ˈset.ʌp/：安装、配置、初始化在 OMX 里表示：安装 prompts、skills、AGENTS、hooks、.omx/等运行基础设施doctordoctor/ˈdɑːk.tɚ/：医生在命令行工具语境里通常引申为：诊断问题在 OMX 里表示：检查安装状态、配置状态、运行环境问题reviewreview/rɪˈvjuː/：审查、复查、评审在 OMX 里表示：对当前实现做质量评审code-reviewcode/koʊd/：代码review/rɪˈvjuː/：审查合起来可以理解为：代码审查在 OMX 里表示：重点检查逻辑问题、回归风险、边界条件和缺失测试security-reviewsecurity/səˈkjʊr.ə.t̬i/：安全review/rɪˈvjuː/：审查合起来可以理解为：安全审查在 OMX 里表示：重点检查权限、数据、命令执行、金额计算等安全风险hookshook/hʊk/：钩子、挂钩点hooks/hʊks/：多个钩子