oh-my-codex使用技巧与常用命令整理

OMX（oh-my-codex）是 OpenAI Codex CLI 的多 Agent 编排层。它不是新模型，而是在 Codex CLI 之上增加了：

• 多 Agent 协作
• 持久化状态 / 记忆 / 日志
• 分阶段工作流（澄清 → 计划 → 执行 → 验证）
• 团队并行执行（team）
• 只读探索与恢复能力（explore / resume / sparkshell）
• hooks、skills、MCP servers、HUD 等工程化能力

官方首页把它描述为：“Multi-agent orchestration layer for OpenAI Codex CLI”，并强调 staged team pipelines、persistent memory/state MCP servers、extensible hooks。

---

2. 什么时候适合用 OMX

适合

• 大型重构
• 多模块并行开发
• 长链路任务
• 复杂 bug 排查
• 需要计划、验证、恢复、追踪状态的任务
• 想把 Codex 从“单轮助手”升级成“工程代理系统”

不太适合

• 只改一个小函数
• 查一个简单报错
• 写一段很短的脚本

这类小任务直接用原生 Codex CLI 往往更轻。

---

3. 官方推荐工作流

官网给出的推荐流程是：

# 1. 启动交互式 Codex 会话
omx --madmax --high

# 2. 在 Codex 内使用技能/关键词
$deep-interview "clarify the auth change"
$ralplan "approve the implementation plan"
$ralph "carry the plan to completion"

对应思路：

1. $deep-interview：需求不清时先澄清
2. $ralplan：大任务先做共识计划
3. $ralph：单 owner 持续推进直到验证完成
4. $team：需要并行时切团队模式

如果你经常一上来就“直接改代码”，OMX 最大的价值就是把这条流程固定下来，减少返工。

---

4. 安装与启动

官方文档给出的快速开始：

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

常见启动方式：

omx                # 启动 Codex CLI（带 OMX 运行时/HUD）
omx --high         # 更高推理强度
omx --xhigh        # 更高一档推理强度
omx --madmax       # 危险：绕过审批与沙箱，仅限可信环境
omx --spark        # 团队 worker 使用更快的 spark 路线
omx --yolo         # yolo 模式启动

启动建议

• 日常开发：omx --high
• 复杂任务：omx --xhigh
• 完全信任的本地仓库：才考虑 omx --madmax --high
• 不要默认开 --madmax，除非你明确知道它会放开什么

---

5. 常用命令速查

5.1 核心 CLI 命令

命令	用途	适用场景
omx	启动 Codex CLI + OMX 运行时	日常入口
omx setup	安装 skills、prompts、MCP、AGENTS.md	初装/升级后
omx doctor	检查安装健康状态	出现异常时先跑
omx resume	恢复之前的会话	中断后继续
omx status	查看活跃模式和执行状态	想知道当前到底在跑什么
omx cancel	取消活跃执行模式	停止 autopilot/team 等
omx hud	查看 HUD 运行信息	观察运行态
omx reasoning [mode]	查看或设置推理强度	low/medium/high/xhigh
omx version	查看版本	对照文档版本
omx help	看帮助	第一手命令来源
omx agents-init .	为仓库/子树生成轻量 AGENTS.md	初始化约束

实用示例

omx setup
omx doctor
omx status
omx hud --watch
omx reasoning xhigh
omx cancel
omx resume

---

5.2 探索 / 恢复 / shell 观察

omx explore

适合：只读、快速、仓库探索。

omx explore --prompt "which files define team routing"
omx explore --prompt-file prompts/explore-task.md

官方强调它是：

• read-only
• shell-only
• 会阻止 pipe、重定向、shell chaining、越界路径访问
• 目前允许的命令包括：rg、grep、ls、find、wc、cat、head、tail、pwd、printf

技巧：

• 先用 omx explore 做文件/符号/模式定位
• 不要拿它做编辑或复杂诊断
• 如果问题超出只读探索，再切回完整 Codex/OMX 主会话

omx sparkshell

适合：shell 原生命令检查、摘要、tmux pane 观察。

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

技巧：

• noisy shell 输出、日志尾部、pane 摘要很适合它
• 如果要真正修改代码，不要停留在 sparkshell

omx resume

适合：会话断掉后继续接着干。

omx resume

技巧：

• 大任务优先用 OMX，恢复价值比原生一次性会话高很多
• 在多阶段任务里，resume 比“重开一个新上下文”更稳

---

5.3 团队并行执行

omx team

适合：多 Agent 并行执行。

omx team 3:executor "full-stack implementation"
omx team 4:executor "feature work" --worktree=feature-branch

官方文档强调：

• Team workers 默认会使用 git worktree 隔离
• 适合并行开发，降低互相覆盖和冲突
• 支持恢复：omx team resume <team-name>
• 支持 team api 做 JSON 化任务流转

团队使用技巧

1. 单文件小改动不要上 team，会太重
2. 明确 worker 职责，如：前端 / 后端 / 测试 / 文档
3. 优先让并行 worker 处理独立文件树
4. 大仓库重构特别适合 team + worktree
5. 如果你要跨模型混编，文档还提到了 OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini

---

5.4 询问外部顾问

omx ask

适合：直接把问题发给外部 advisor/provider（文档示例为 claude / gemini）。

omx ask claude "review this diff"
omx ask gemini "brainstorm alternatives for the auth system"
omx ask claude --agent-prompt executor "implement feature X with tests"
omx ask gemini --agent-prompt planner "draft a rollout plan for v0.9"

技巧：

• 适合做“第二意见”
• 用 --agent-prompt 指定角色，比纯自然语言更稳
• 最适合：评审、方案比较、diff 解释、风险提示

---

5.5 运行时与插件相关

omx hooks init
omx hooks status
omx hooks validate
omx hud --watch
omx hud --json
omx tmux-hook init

使用技巧

• omx hud --watch：适合长任务时盯运行态
• omx hud --json：适合脚本化或接外部监控
• omx hooks status：当你怀疑 hooks 没装好时特别有用
• omx doctor 和 omx hooks status 往往要一起看

---

6. 会话内常用技能（不是 shell 命令）

这些通常是在 进入 Codex/OMX 会话后 使用的 $name 技能，而不是直接在 shell 里敲的命令。

技能	作用	建议用法
$deep-interview	先澄清需求	需求模糊、边界不清时先用
$ralplan	共识规划	改动较大时先规划
$ralph	持续执行直到完成	单 owner 长任务
$team	多 agent 并行协作	并行任务
$autopilot	从 idea 到 working code 的自治模式	任务明确且你愿意让它全自动推进
$ultrawork / ulw	并行加速	多子任务可拆时
$ultraqa	test → verify → fix 循环	修 bug、补验证
$cancel	停止当前模式	紧急终止
$note	写入记忆	记录关键决策

高频组合

组合 1：大需求

$deep-interview -> $ralplan -> $ralph

组合 2：并行开发

$ralplan -> $team

组合 3：Debug

$plan -> $ralph -> $ultraqa

组合 4：一把梭（官方 no-brainer）

$autopilot -> $ultrawork -> $ralph

---

7. 最有价值的使用技巧

技巧 1：不要把 OMX 当成“更复杂的启动器”

它真正的价值不是 omx 这个命令，而是：

• 有状态
• 可恢复
• 可并行
• 有计划与验证流程
• 能把复杂任务拆成工程系统

技巧 2：需求不清时，先 $deep-interview

很多返工来自“没想清楚就改”。

适用场景：

• 需求描述很短
• 用户说“先不要假设”
• 你自己发现边界不清

技巧 3：大改动先 $ralplan

不要上来就 ralph 或 team。先定：

• 改哪些模块
• 如何验证
• 风险在哪
• 是否要并行拆分

技巧 4：只读定位优先 omx explore

查“某个逻辑在哪”“哪些文件引用某函数”时，优先：

omx explore --prompt "which files reference X"

比直接让主 agent在整仓里乱翻更省、也更安全。

技巧 5：长任务中随时看 status / hud

omx status
omx hud --watch

这能显著减少“它现在到底在干嘛”的不透明感。

技巧 6：优先把 team 用在“天然可并行”的工作上

例如：

• 前后端分离
• 多个独立 bug
• 重构 + 测试补齐 + 文档更新

不适合：

• 多个人同时改同一核心文件
• 任务边界完全没划清

技巧 7：版本漂移时，以本机帮助为准

官方资料里有些命令会先出现在 release notes，再逐步进入 CLI reference。比如文档明确提到过 omx exec、omx autoresearch，但不是每一处都给了完整说明。
所以最稳妥的方式永远是：

omx help
omx <subcommand> --help

---

8. 常见坑

坑 1：把 owx 写成命令

官方命令是：

omx

不是 owx。

坑 2：没安装就直接敲命令

如果你看到类似“command not found / 无法识别为 cmdlet”，通常是：

• 没安装 oh-my-codex
• npm 全局 bin 不在 PATH
• 当前 shell 没刷新

坑 3：在不可信环境直接用 --madmax

官方已经明确标为危险模式。只有在你确信仓库、命令、权限都可信时再用。

坑 4：把 explore 当全功能 agent

explore 是故意受限的，只适合只读探索，不适合复杂编辑与全功能诊断。

坑 5：大任务不做状态管理

复杂任务里最好：

• 用 status
• 用 resume
• 用记忆 / notepad / plans

否则任务一长，恢复与交接成本会很高。

---

9. 一页 Cheat Sheet

# 安装与体检
npm install -g @openai/codex oh-my-codex
omx setup
omx doctor

# 启动
omx
omx --high
omx --xhigh
omx --madmax --high

# 运行态
omx status
omx hud --watch
omx cancel
omx resume
omx reasoning xhigh

# 只读探索 / shell 观察
omx explore --prompt "which files define team routing"
omx sparkshell git --version

# 团队并行
omx team 3:executor "full-stack implementation"

# 外部 advisor
omx ask claude "review this diff"
omx ask gemini --agent-prompt planner "draft a rollout plan"

会话内高频技能：

$deep-interview
$ralplan
$ralph
$team
$autopilot
$ultrawork
$ultraqa
$cancel

---

10. 我的建议：新手最值得先学的 5 个

如果你刚开始用 OMX，优先掌握这 5 个：

1. omx setup
2. omx doctor
3. omx explore
4. $deep-interview
5. $ralplan / $ralph

原因很简单：

• setup / doctor 解决“能不能用”
• explore 解决“去哪找”
• deep-interview 解决“先想清楚”
• ralplan / ralph 解决“怎么持续做完”

---

11. 参考来源

• 官网首页：https://oh-my-codex.dev/
• 官方文档：https://oh-my-codex.dev/docs.html
• GitHub 仓库：https://github.com/scalarian/oh-my-codex

本整理主要依据官网与官方文档当前页面内容汇总而成。