oh-my-codex 教程：安装 OMX 0.21.6 并跑通首个工作流

oh-my-codex（OMX）不是另一个编码模型。它把技能、项目指引、长任务状态、团队调度和 HUD 加到 OpenAI Codex CLI 外面，真正执行代码和调用模型的仍是 Codex。是否值得装，取决于你是否需要这层固定流程。

1. 先确认它适合你的环境

官方 README 把 macOS 或 Linux 上的 Codex CLI 定为推荐路径。Node.js 要求 20 或更新版本；Codex CLI 必须已经安装、位于 PATH，并且能在同一个 shell/profile 下看到认证信息。Git 不是启动 CLI 的硬门槛，但项目 setup、计划和 worktree 都以 Git 项目为正常使用环境。

node --version
codex --version
codex login status

团队运行在 macOS/Linux 上通常还要 tmux。原生 Windows 可以走项目提供的兼容路径，但官方明确说它不是默认体验。主要在 Codex App 里工作的人也应先接受功能和支持差异，再决定是否安装。

2. 安装官方 npm 包

已有 Codex CLI 时，只装 OMX 本身：

npm install -g oh-my-codex
omx doctor

还没有 Codex CLI、并且希望交给 npm 管理时，再分别执行：

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

如果现有 codex 是 Homebrew 安装的，不要把两个包合成一条 npm 命令。官方文档说明，这样可能因为 npm 试图覆盖 /opt/homebrew/bin/codex 而报 EEXIST。安装目标也要认准 Yeachan-Heo/oh-my-codex 与 npm 包 oh-my-codex；带有“OMX v2”等名字的第三方项目不属于官方发布线。

3. 在真正的项目目录做 setup

项目要长期保存 OMX 指引时，进入目标 Git 仓库再执行：

cd /path/to/your-project
omx setup --scope project --merge-agents

--scope project 让项目自己持有持久的 AGENTS.md 指引。不要在包含许多仓库的工作总目录或 home 目录误跑项目 setup，否则上层规则与单个项目的规则容易混在一起。若你只想配置用户级环境，使用 omx setup --scope user。

--merge-agents 是明确的合并选择。官方还提供 --no-merge-agents 和 --clear-merge-agents-policy；这些选项应使用裸参数，不要写成 =true。选择会记录在当前工作根的 .omx/setup-scope.json，不会变成所有项目共享的全局偏好。

4. doctor 之后还要做真实请求

omx doctor 能发现 OMX 文件、hooks 和运行时前提的问题，却不能证明当前 Codex profile 真能调用模型。官方 Getting Started 因此要求再跑一次短请求：

codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

只有返回约定文本，才说明认证、profile、provider 和 base URL 这条链路已经走通。若 doctor 通过而这一步失败，先查 Codex 登录和 provider 配置，不要反复重装 OMX。

5. 当前工作流怎么选

旧页面把 $deep-interview、$ralplan、$ultragoal 写成唯一默认链。当前 README 的入口更灵活：$plan、$ultragoal、$team、$code-review、$ultraqa 可以独立使用，没有强制固定顺序。

第一次可选一个小改动，先用 $plan 写出可审阅计划，再用 $ultragoal 推进并保留检查点。只有任务真的能拆成互不冲突的块时再用 $team。需求本身还含糊时，先用 $deep-interview 补齐约束，再把结果交给 $ralplan 与 $ultragoal。

OMX 会把计划、日志、记忆和模式状态放进 .omx/。提交代码前应检查这些文件中哪些属于项目资产，哪些只适合留在本机，并按团队约定处理。

6. worktree、tmux 与权限边界

官方推荐在可信 Git 仓库中用命名 worktree 隔离长任务，例如 omx --worktree=feat/task。并发会话使用不同名字，避免多个代理同时写同一 checkout。macOS/Linux 有 tmux 时，OMX 可以把 leader 和 HUD 放在可恢复会话中。

--madmax 会绕过审批与沙箱。即使官方示例把它与 worktree 配合，也只能在你完全信任的代码、依赖和环境里使用。第一次验证 OMX 不需要它。

7. 与原生 Codex CLI 对比

OpenAI 官方 Codex CLI 已经能在本机运行编码代理，并提供安装、登录和基础交互。OMX 在这之上再加项目 setup、技能入口、.omx/ 状态、Team 和 HUD。

只需要直接聊天、修改代码和运行命令时，原生 Codex 的组件更少。经常跑长任务、需要可恢复状态、固定审查流程或多个 worker 时，OMX 才体现价值。

常见问题