5分钟上手oh-my-codex：给Codex CLI加钩子、代理团队与HUD的实战指南
【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex
你有没有把一个大任务丢给 Codex CLI，跑了一阵之后却说不清它在干什么、做到哪一步？OmX（oh-my-codex）就是解决这个问题的：它是架在 Codex CLI 之上的一层工作流工具，Codex 继续当执行引擎，OMX 补上钩子、多代理团队、HUD 和可持久化的状态，让长任务可规划、可拆分、可追踪。
它具体能帮你做什么
把模糊需求变成一份批准的方案
需求边界不清时，Codex 容易跑偏。OMX 的默认工作流是三步走：$deep-interview先向你追问范围和非目标，$ralplan把澄清后的需求转成方案并让你确认取舍，$ultragoal再把批准的方案落成带检查点的持久目标，存到.omx/ultragoal下，中途断掉也能接着跑。
$deep-interview "..."：意图或边界还不清楚时用$ralplan "..."：批准计划、评审取舍，到方案为止不直接动代码$ultragoal "..."：把批准的方案变成持久的多目标执行
👥 让多个代理并行分工
任务大到单会话效率不够时，可以用团队模式：omx team 3:executor "fix the failing tests with verification"会在 tmux 分屏里拉起 3 个 worker 会话，每个 worker 用独立的 git worktree，通过.omx/state/team/下的状态文件协调进度。跑乱了也不怕，omx team status <team-name>随时看状态，omx team resume <team-name>可恢复中断的跑批。
- 需要 tmux（macOS/Linux 是主路径）
- 很小的原子任务不建议开团队，OMX 对过度编排会给出警告
📟 随时看清AI在干什么
状态全部落在磁盘上：计划、日志、记忆、模式状态都放在.omx/目录里。omx hud --watch给你一个实时监控面板，omx doctor检查安装形状、钩子和运行时前置条件。注意 doctor 全绿只代表安装没问题，要确认真实执行链路，再跑一次omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"，它能暴露鉴权和 endpoint 问题。
🔌 把重复操作变成一条钩子
钩子系统让你把自己的逻辑挂进会话生命周期事件：session-start、pre-tool-use、post-tool-use、stop、session-end等。omx hooks init会在.omx/hooks/sample-plugin.mjs生成一个样例插件，之后用init / status / validate / test四个子命令迭代即可，插件文件统一放在.omx/hooks/下。
从零跑起来：最短上手路径
第一步，确认前置条件：Node.js 20+、已登录的 Codex CLI（codex --version验证），想用团队运行时再装好 tmux。
第二步，全局安装并在 git 项目里初始化：
npm install -g oh-my-codex omx setup --scope project --merge-agents # 用户级配置用 --scope user omx doctor第三步，做真实冒烟测试，确认当前 shell 里的鉴权和模型请求没问题：omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"。
第四步，用推荐的姿势启动：
omx --worktree=feat/task --madmax --xhigh--worktree会把启动切进独立 worktree，和--madmax（它对应 Codex 的跳过审批与沙箱开关，只在可信仓库用）搭配更安全；把feat/task换成你的任务分支名就行。
进阶玩法与实用技巧
技巧一：并行会话必须隔离。多个--madmax会话不要共享同一个 checkout，给每个会话一个独立命名 worktree，例如--worktree=feature/auth和--worktree=fix/flaky-tests；同一台机器开多个对话时，给每个会话指一个不同的OMX_ROOT目录。
技巧二：自己写钩子插件。一个插件只需导出onHookEvent函数，SDK 提供 tmux 发键、插件命名空间的 state 读写，以及只读的 omx 状态读取。插件默认超时 1500ms，可用OMX_HOOK_PLUGIN_TIMEOUT_MS调整。事件契约和 SDK 面在 docs/hooks-extension.md 里写得很细。
技巧三：排障先查状态模型。ralplan、ralph、team 等模式的权威状态都在.omx/state/*.json，会话级优先于根级；想知道哪些状态迁移合法，直接读 docs/STATE_MODEL.md。
官方文档里还留了一组小基准：同一个 Tetris 任务的两种实现并排对比，能直观看到工作流层的产出差异。
适合谁 & 下一步
如果你在 macOS 或 Linux 上日常用 Codex CLI，有真实的长任务（重构、跨文件改动），并且希望计划、状态、监控可见可恢复，OMX 值得装。反过来，只用 Codex 做小改动、或者在原生 Windows 上工作（它不是主支持路径），直接用 Codex 本身可能更省心。
下一步：先读 docs/getting-started.html 的完整安装与首跑流程；遇到问题时从 README.md 末尾的排障表入手，先跑omx doctor定位。
【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
