如果你已经在使用 OpenAI Codex CLI，但希望它在真实项目里更像一个“会规划、会拆解、会持续推进”的协作搭档，那么 oh-my-codex 值得一试。
- 认识
oh-my-codex到底是什么 - 正确安装它
- 避开常见坑
- 真正启动起来
- 用一个实际例子理解它的工作流
一、oh-my-codex 是什么？
oh-my-codex（简称 OMX）不是另一个大模型，也不是用来替代 Codex CLI 的工具。
它更像是一个“编排层”或者“工作流增强层”，套在 Codex CLI 外面，给你补上这些能力：
- 更清晰的任务推进流程
- 更适合复杂任务的多代理协作方式
- 项目级的
AGENTS.md规范注入 - 持久化的状态、计划、日志和运行时目录
- 一套约定好的工作方式，比如先澄清、再计划、再执行
可以把它理解成：
Codex CLI = 真正干活的 agent
oh-my-codex = 帮你组织 agent 怎么更聪明地干活
如果你平时直接把需求扔给 Codex，但希望它：
- 少一点“上来就乱改代码”
- 多一点“先确认范围、先给计划、再落地执行”
- 在复杂任务中更稳定、更可控
- 自己24小时跑任务，自己迭代功能
那 oh-my-codex 正好适合你。
二、安装前要准备什么？
最基本的要求包括：
- Node.js 20+
- 已安装 Codex CLI
- 已完成 Codex 登录/鉴权
如果你后面要使用团队模式，还会涉及：
- macOS / Linux 下的
tmux - Windows 下的
psmux
但如果你只是想先体验单人工作流，其实前面三项就够了。
三、最容易踩坑的地方：它不是 Python 项目
很多人第一次看到一个本地仓库，会下意识想：
pip install -e .
但这里不能这么做，因为 oh-my-codex 不是 Python 包，而是一个 Node.js / TypeScript CLI 项目。
所以：
pip install -e .：不适用pnpm install/pnpm run build：才是正确方向
这也是很多初学者第一次安装时最容易绕进去的地方。
四、正确安装 oh-my-codex
下面给出一套最稳妥的本地仓库安装流程。
假设你已经把仓库拉到本地：
cd /path/to/oh-my-codex
1）安装依赖
pnpm install
2）构建 CLI
pnpm run build
这一步很重要。
因为这个项目的 CLI 命令入口在：
dist/cli/omx.js
如果没有先执行 build，这个文件不存在，那么你后面无论执行 omx 还是 pnpm exec omx，都可能失败。
直接运行：
node dist/cli/omx.js --version
如果能看到版本输出，说明 CLI 已经构建成功。
五、初始化：第一次执行 setup
构建成功后，执行：
node dist/cli/omx.js setup
这时它会让你选择安装作用域：
1) user (default)
2) project
选 user 还是 project？
对大多数第一次使用的人，我建议直接选：
1
也就是 user 作用域。
原因很简单：
- 会安装到
~/.codex - 以后在别的项目里也能复用
- 更接近“给自己整套 Codex 工作流增强”的使用方式
如果你只是想把它完全限制在当前项目目录里，再选 project。
遇到 Overwrite existing AGENTS.md 怎么办？
如果你看到类似提示：
Overwrite existing AGENTS.md at "~/.codex/AGENTS.md"? [y/N]
一般情况下可以直接输入：
y
因为 setup 的目的就是帮你刷新和生成 OMX 所需的全局指导文件。
除非你明确知道自己以前手动维护过这份文件，并且里面有你不想丢失的内容，否则通常选择覆盖是正确的。
六、安装完成后，先跑一次体检
执行：
node dist/cli/omx.js doctor
如果一切正常，你会看到类似：
- Codex CLI 已安装
- Node.js 正常
- Explore Harness 正常
- Codex home 已配置
- Prompts 已安装
- Skills 已安装
- AGENTS.md 存在
- MCP Servers 已配置
如果只有警告、没有失败，一般都可以继续使用。
例如有一种常见警告是：
legacy ~/.agents/skills still exists
这通常表示你机器上还保留着旧版技能目录，可能会导致技能重复显示，但不会阻止你开始使用。
七、为什么我装好了，还是不能直接输入 omx？
这是很多人第一次会遇到的问题。
比如你可能会看到：
zsh: command not found: omx
这不一定说明安装失败，更常见的原因是：
- 当前 shell 的 PATH 里没有对应的全局 bin
- 你是在本地源码仓库里构建的，还没做全局链接
pnpm exec omx在当前 workspace 环境下没有正确解析到bin
最实用的解决方法
先不要纠结 PATH，直接这样用：
node dist/cli/omx.js setup
node dist/cli/omx.js doctor
node dist/cli/omx.js --help
如果你想让本终端里用起来更顺手，可以临时加个别名：
alias omx='node /你的路径/oh-my-codex/dist/cli/omx.js'
例如：
alias omx='node /Users/yourname/path/to/oh-my-codex/dist/cli/omx.js'
加完后，这个终端就能直接输入：
omx doctor
omx --help
八、真正重要的一点：omx 不是主要操作界面
这是理解 oh-my-codex 的关键。
很多人以为安装完之后，平时都在终端里疯狂敲 omx ...。
其实不是。
更准确地说：
omx：负责安装、诊断、团队运行时、辅助命令codex：才是你真正和 agent 交互、做任务的主界面
也就是说，oh-my-codex 的核心价值不是“多了几个 shell 命令”，而是：
当你进入 Codex 会话后，你可以用一组更强的工作流指令来组织任务。
九、安装完之后到底怎么用？
最直接的方式是：
1）进入你的项目
cd /path/to/your-project
2）启动 Codex
codex
3）在 Codex 会话里输入 OMX 工作流指令
比如：
$deep-interview "clarify the auth change"
$ralplan "approve the auth plan and review tradeoffs"
$ralph "carry the approved plan to completion"
这三步分别代表：
$deep-interview：先澄清需求和边界$ralplan：把澄清后的需求整理成实施计划$ralph：按照批准的计划执行到完成
这就是 oh-my-codex 最核心的使用方式。
十、给一个真正能看懂的实际例子
光讲概念还是容易抽象，我们来看一个真实场景。
场景：修复登录按钮点击没反应的问题
你在一个前端项目里发现：登录页点了 Sign in 没任何反应。
过去你可能直接对 Codex 说：
帮我修一下登录按钮没反应。
问题是，它有时候会：
- 没搞清楚复现路径
- 不知道你是否允许重构
- 不知道要不要补测试
- 一上来就改多个文件
而使用 OMX 工作流，你可以这样做。
第一步：先澄清任务
在 codex 会话里输入：
$deep-interview "登录页点击 Sign in 没反应，帮我先澄清问题边界，不要急着改代码"
这一步的目标不是修复，而是把这些事情问清楚：
- 是所有用户都会遇到，还是特定环境才会出现？
- 预期行为是什么？
- 只修 bug，还是顺手优化？
- 是否允许修改接口逻辑？
- 怎么验证这个 bug 真的修好了？
第二步：先出方案
接着输入：
$ralplan "基于刚才确认的范围，给我一个最稳妥的修复计划和验证方案"
这一步它通常会输出：
- 可能的 root cause
- 需要检查的文件
- 预期最小改动范围
- 验证步骤
- 是否需要新增测试
第三步：再执行
最后输入：
$ralph "按刚才批准的计划直接修复并验证到完成"
这时候它才开始：
- 查找代码入口
- 修改相关文件
- 运行测试或验证命令
- 回报最终结果
这套方式的好处是什么？
它强迫 agent 按照更像工程实践的流程工作：
- 先定义边界
- 再给可审阅的计划
- 最后再执行
这样比“一句话直接开改”更稳定，也更适合真实项目。
十一、如果任务很大怎么办？
如果你面对的是一个较大的任务，比如：
- 多模块重构
- 前后端联动改造
- 大范围测试修复
- 多文件并行修改
这时可以考虑 team 模式。
例如：
$team 3:executor "execute the approved plan in parallel"
它的含义可以简单理解为：
- 启动 3 个执行代理
- 在可拆分的范围内并行推进任务
当然，初学者不需要一开始就上 team。
你完全可以只记住下面两句：
$ralplan "先给我计划"
$ralph "按计划执行到完成"
这已经足够覆盖大多数日常使用场景。
十二、一个适合新手的最小练习
如果你刚装好，还不知道怎么体验，推荐做这个 10 分钟练习。
在 oh-my-codex 仓库目录里启动：
codex
然后依次输入：
$deep-interview "请用中文帮我澄清一个小任务：我想在当前项目里找一个适合新手理解的命令入口，并说明它的作用、执行路径和相关文件。先不要改代码。"
$ralplan "基于刚才澄清的结果，给我一个最小学习计划：我应该看哪些文件、按什么顺序看、每个文件看什么。不要实现，只输出计划。"
$ralph "按照刚才批准的计划，带我完成这次代码导览；如果需要，顺便做最小验证，但不要做无关修改。"
这个练习的优点是：
- 不需要你先准备业务项目
- 风险很低
- 能直接体验 OMX 的完整工作流
- 能迅速理解它和“普通直接提问”有什么不同
十三、把它讲得更直白一点
如果你到这里还是有点抽象，我用一句更直白的话来概括：
没有 OMX 时
你通常是这样：
我：帮我改这个功能
Codex：开始直接干
有了 OMX 时
你更像这样：
我：先帮我确认需求边界
我：再给我计划
我：最后按计划执行
所以，oh-my-codex 并不是“让模型更聪明”的魔法插件，
而是让你和模型协作的方式更工程化、更可控。
十四、常见问题答疑
1）我是不是应该用 pip install -e .？
不是。
这是 Node.js / TypeScript 项目，不是 Python 项目。
2）我已经 pnpm run build 了，为什么还是 omx: command not found？
因为构建成功不等于 shell 已经把 omx 当成全局命令识别。
先直接用：
node dist/cli/omx.js setup
这是最稳的方式。
3）平时我到底是用 omx 还是用 codex？
两者都用，但用途不同：
omx：安装、诊断、团队运行时、辅助命令codex：真实任务执行的主界面
4）我必须使用 $deep-interview -> $ralplan -> $ralph 吗？
不一定，但这是最推荐、最稳定的路径。
尤其是当任务稍微复杂一点时，这种方式明显更可靠。
5）第一次使用最值得记住什么？
如果只能记住一句话，那就是：
先计划，再执行。
十五、推荐给初学者的最小命令清单
如果你想把整篇文章压缩成最小可执行版，记住这几条就够了。
安装阶段
pnpm install
pnpm run build
node dist/cli/omx.js setup
node dist/cli/omx.js doctor
使用阶段
codex
在 Codex 里输入：
$ralplan "先给我计划"
$ralph "按计划执行到完成"
十六、结语
oh-my-codex 最有价值的地方，不在于它提供了多少命令，而在于它把“如何与 agent 协作”这件事，做成了一套更成熟的工程流程。
它特别适合下面这类人：
- 已经在使用 Codex CLI
- 希望 agent 少走弯路
- 希望复杂任务更可控
- 希望任务推进更像真实团队协作
如果你以前总觉得 AI 编程助手“有时很好，有时很飘”，那么试试 oh-my-codex，你会明显感觉到：
不是模型突然变聪明了，
而是你的协作方式变专业了。
附：一套可以直接复制的体验脚本
先启动：
codex
然后复制下面三条：
$deep-interview "请用中文帮我澄清一个小任务：我想在当前项目里找一个适合新手理解的命令入口，并说明它的作用、执行路径和相关文件。先不要改代码。"
$ralplan "基于刚才澄清的结果，给我一个最小学习计划：我应该看哪些文件、按什么顺序看、每个文件看什么。不要实现，只输出计划。"
$ralph "按照刚才批准的计划，带我完成这次代码导览；如果需要，顺便做最小验证，但不要做无关修改。"
如果你是第一次上手，这三条已经足够让你真正理解 oh-my-codex 的核心价值。
