Oh My Codex (OMX) 详细部署教程

OMX 是 OpenAI Codex CLI 的工作流增强层，它不替代 Codex，而是提供更好的提示词、工作流和运行环境。本教程将引导你完成从零开始的完整部署。

1. 准备工作

1.1 基础环境要求

要求	版本/说明
操作系统	macOS 或 Linux（官方推荐和主动优化）
Node.js	20+
npm	随 Node.js 安装
Git	推荐用于项目工作流
Codex CLI	已安装并认证
tmux	macOS/Linux（推荐，用于团队模式）

⚠️ 重要提示：OMX 主要针对 macOS 或 Linux 设计，原生 Windows 和 Codex App 体验欠佳，可能行为不一致。

1.2 安装 Codex CLI

OMX 依赖 Codex CLI 作为执行引擎。如果尚未安装 Codex CLI，根据你的系统选择安装方式：

macOS/Linux（推荐官方脚本） ：

1	curl -fsSL https://chatgpt.com/codex/install.sh \| sh

通用 npm 安装（需 Node.js 22+）：

1	npm install -g @openai/codex

macOS Homebrew ：

1	brew install --cask codex

验证安装：

1	codex --version

1.3 认证 Codex CLI

1	codex login

按提示用 ChatGPT 账号（Plus/Pro/Team/Enterprise）完成浏览器授权。

2. 安装 OMX

2.1 全局安装

1	npm install -g oh-my-codex

⚠️ 常见错误：如果已通过 Homebrew 安装 Codex，不要运行 npm install -g @openai/codex oh-my-codex 组合命令，否则 npm 可能因 EEXIST 错误失败。OMX 只需要 PATH 中有可用的 codex 命令即可。

验证安装：

1	omx --version

2.2 运行设置向导

进入你的项目目录后，运行设置命令：

项目级设置（推荐，从目标 Git 项目运行）：

1	omx setup --scope project --merge-agents

用户级设置（不在项目内时）：

1	omx setup --scope user

--merge-agents 会保留现有 AGENTS.md 中 OMX 标记区块之外的内容，仅插入/刷新 OMX 管理部分。

3. 验证安装

3.1 运行健康检查

1	omx doctor

这会检查 OMX 文件、钩子和运行时依赖是否完整。

3.2 执行真实请求烟雾测试

omx doctor 只能验证安装结构，不能证明 Codex 能成功调用模型。运行以下命令进行真实测试：

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

如果输出 OMX-EXEC-OK，说明环境配置正确。

4. 启动第一个 OMX 会话

4.1 基础启动方式

从 Git 项目目录启动（推荐使用命名工作树）：

1	omx --worktree=feat/task --madmax --xhigh

参数	说明
`--worktree=feat/task`	创建/复用名为 `feat/task` 的 Git 工作树，隔离变更
`--madmax`	Codex `--dangerously-bypass-approvals-and-sandbox` 简写（仅在可信环境使用）
`--xhigh`	模型推理强度最高（`-c model_reasoning_effort="xhigh"`）

在 macOS/Linux 且安装了 tmux 的环境下，这会启动一个 OMX 管理的分离 tmux 会话。

4.2 直接启动（无 tmux/HUD）

1	omx --direct --yolo

或设置环境变量默认使用直接模式：

1 2	export OMX_LAUNCH_POLICY=direct omx --yolo

5. 推荐工作流

OMX 的核心工作流围绕以下几个命令：

5.1 澄清需求

1	$deep-interview "clarify the authentication change"

当需求或边界不清晰时，使用此命令进行迭代式澄清。

5.2 制定计划

1	$ralplan "approve the auth plan and review tradeoffs"

将澄清后的范围转化为已批准的架构和实现计划。

5.3 执行任务

持久化多目标执行（推荐）：

1	$ultragoal "execute the approved auth fix with checkpoint evidence"

团队并行执行（仅当任务足够大时）：

1	$team 3:executor "execute the approved plan in parallel"

5.4 使用 `/goal` 设置持久目标

1	/goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior.

/goal 会建立持久的检查和目标结构，让 Codex 在多个交互轮次中持续对照。

6. 常用命令速查

命令	用途
`$deep-interview "..."`	澄清意图、范围和边界
`$ralplan "..."`	批准实施计划和权衡
`$ultragoal "..."`	持久化多目标执行
`$team "..."`	协调并行执行
`/skills`	浏览已安装的技能
`omx doctor`	检查安装状态
`omx hud --watch`	监控/状态面板
`omx update`	更新 OMX 并刷新设置

7. 故障排除

7.1 `omx` 命令未找到

# 重新运行全局安装，确保 npm 全局 bin 在 PATH 中
npm install -g oh-my-codex
# 检查 npm 全局路径
npm root -g

7.2 提示词或技能未加载

# 确认文件已安装
ls ~/.codex/prompts/
ls ~/.codex/skills/
# 重新运行设置
omx setup --scope project --merge-agents

7.3 `omx doctor` 通过但真实执行失败

检查 Codex 实际使用的环境：

# 确认认证
codex login status
# 检查配置，特别是 openai_base_url（如果使用代理）
cat ~/.codex/config.toml

7.4 Intel Mac 启动时 CPU 占用高

部分 Intel Mac 上，--madmax --high 启动时可能因 macOS Gatekeeper 验证而 spike syspolicyd/trustd ：

1	xattr -dr com.apple.quarantine $(which omx)

或将终端应用添加到 macOS 安全设置的“开发者工具”白名单。

7.5 团队模式残留会话

1
2
3

omx team shutdown <team-name> --force --confirm-issues
omx cancel
omx doctor --team

8. 下一步

阅读官方文档：Getting Started
加入社区：Discord（共享 Gajae 社区服务器）
查看技能参考和代理目录

OMX 的核心价值是 更好的任务路由 + 更好的工作流 + 更好的运行时，而不是一个需要整天手动操作命令的工具。掌握 $deep-interview → $ralplan → $ultragoal 这条主线，就能发挥 OMX 的最大效用。