oh-my-codex（OMX）实战指南：基于 OpenAI Codex CLI 的多 Agent 编排层

2026-09-09 21:18:00作者：瞿蔚英Wynne

本文以仓库 docs/readme/README.de.md 为核心骨架，结合 src/cli、src/team、src/config、src/mcp 等源码与测试，系统讲解 OMX 的安装、核心模型、常用命令、Hooks 扩展、团队模式（Team Mode）与配置注入原理。读完本文，你将掌握如何在 Codex CLI 之上叠加 Agent 团队、技能（Skills）、HUD 与通知层，并能够用 omx setup、omx team、omx hooks 独立完成一套多 Agent 工作流的部署与运维。文中所述版本、命令与配置均以当前仓库（oh-my-codex v0.21.2，Node.js >= 20）为准。

一、OMX 是什么：一条比"单机 Codex"更厚的编排链路

OMX（Oh My codeX）是面向 OpenAI Codex CLI 的多 Agent 编排层（Multi-Agenten-Orchestrierungsschicht）：Dein Codex ist nicht allein（"你的 Codex 不再孤军奋战"）是它的核心标语。它不替换 Codex，而是在 Codex 之上补充 hooks、Agent 团队、HUD、通知、MCP 服务器等能力，让一个 Codex 会话可以驱动多个专职角色并行工作。

从其 package.json 可以确认定位与边界：

"name": "oh-my-codex",
"version": "0.21.2",
"description": "Multi-agent orchestration layer for OpenAI Codex CLI",
"bin": { "omx": "dist/cli/omx.js" },
"engines": { "node": ">=20" }

入口脚本 src/cli/omx.ts 会先加载编译产物 dist/cli/index.js 并调用 main(process.argv.slice(2))，因此所有 omx 子命令都需先执行 npm run build 生成 dist/。

核心模型：OMX 安装并串接的六层

README 给出了清晰的"分层模型"，这是理解 OMX 一切行为的钥匙：

User
  -> Codex CLI
    -> AGENTS.md (Orchestrierungs-Gehirn)            // 编排大脑
    -> ~/.codex/prompts/*.md (Agenten-Prompt-Katalog)  // Agent 提示词目录
    -> ~/.codex/skills/*/SKILL.md (Skill-Katalog)       // 技能目录
    -> ~/.codex/config.toml (Features, Benachrichtigungen, MCP) // 特性/通知/MCP 配置
    -> .omx/ (Laufzeitzustand, Speicher, Pläne, Protokolle)      // 运行时状态

AGENTS.md 是"编排大脑"，OMX 通过 -c model_instructions_file="<cwd>/AGENTS.md" 注入到 Codex 会话（详见下文"Codex-First Prompt 控制"）。
prompts/（安装到 ~/.codex/prompts/ 或 ./.codex/prompts/）是 Agent 角色提示词目录，仓库中 prompts 下可见 architect.md、planner.md、executor.md、verifier.md、team-executor.md 等 30 个角色文件。
skills/（安装到 ~/.codex/skills/ 或 ./.codex/skills/）是技能目录，每个技能一个 SKILL.md，仓库 skills 下有 deep-interview、ralplan、team、ralph、plan、cancel、pipeline 等。
config.toml 承载特性开关、通知与 MCP 服务器注册，由 omx setup 负责写入。
.omx/ 保存会话状态、记忆、计划与日志等运行时产物。

二、第一次会话：从一条指令到一支并行团队

在 Codex 会话内（`$` 触发技能）

$deep-interview "clarify the auth change"              # 澄清范围与边界
$ralplan "approve the auth plan and review tradeoffs"  # 产出并审批架构/实施计划
$ralph "carry the approved plan to completion"         # 由单一负责实例坚持跑完并验证
$team 3:executor "execute the approved plan in parallel" # 3 个 executor 并行执行

从终端直接驱动

omx team 4:executor "parallelize a multi-module refactor"  # 4 个 executor 并行重构
omx team status <team-name>                                # 查看团队状态
omx team shutdown <team-name>                              # 终止团队

$ 前缀技能（如 $team、$ralph）是安装到 Codex 的 Skill，而 omx team ... 是 OMX 自己的 CLI 命令族。二者的任务相同，只是触发渠道不同。

推荐工作流：三阶段链路

$deep-interview —— 当范围或边界不清晰时，先做需求澄清；
$ralplan —— 把澄清结果转成一份"已对齐的架构与实施计划"；
$team 或 $ralph —— 需要协调并行执行用 $team；需要"一名负责实例坚持完成 + 验证闭环"用 $ralph。

这条"澄清 → 计划 → 执行"链路是 OMX 官方推荐的标准姿势，与仓库中 skills 目录下 deep-interview、ralplan、ralph、team 四个技能一一对应。

三、主命令速查

omx                # 启动 Codex（tmux 可用时附带 HUD）
omx setup          # 按范围安装 prompts/skills/config，创建项目 .omx 与范围 AGENTS.md
omx doctor         # 安装/运行时诊断
omx doctor --team  # 团队/Swarm 诊断
omx team ...       # 启动/查看状态/继续/关闭 tmux 团队 Worker
omx status         # 显示当前激活的模式
omx cancel         # 取消激活中的执行模式
omx reasoning <mode> # low|medium|high|xhigh
omx tmux-hook ...  # init|status|validate|test
omx hooks ...      # init|status|validate|test（插件扩展工作流）
omx hud ...        # --watch|--json|--preset
omx help

从源码结构看，omx doctor、omx setup、omx team、omx hooks、omx ralph、omx ralplan 等均有独立实现文件（见 src/cli），如 src/cli/setup.ts、src/cli/team.ts、src/cli/doctor.ts、src/cli/hooks.ts。

启动 Flags

--yolo
--high
--xhigh
--madmax
--force
--dry-run
--verbose
--scope <user|project>  # 仅用于 setup

其中 --madmax 等价于 Codex 的 --dangerously-bypass-approvals-and-sandbox（绕过审批与沙箱），README 明确警告：只在可信/隔离的沙箱环境中使用。--dry-run 与 --force 在 omx setup 中尤其重要：非交互运行中，没有 --force 时不会覆盖已存在的 AGENTS.md。

四、Spark Initiative：v0.9.0 引入的 Rust 原生探索/检视通道

README 的"Neu in v0.9.0"章节说明了 Spark Initiative 版本，它强化了 OMX 的原生探索与检视路径：

omx explore 的原生 Harness —— 通过更快、更严格的 Rust 路径执行只读仓库探索；
omx sparkshell —— 面向检视的原生操作界面，支持长输出的摘要与显式 tmux Pane 捕获；
跨平台原生 Release 产物 —— omx-explore-harness、omx-sparkshell 与 native-release-manifest.json 的水合路径已纳入发布流水线；
加固的 CI/CD —— build 任务新增显式 Rust 工具链配置，并启用 cargo fmt --check 与 cargo clippy -- -D warnings。

仓库中可以看到对应的 Rust 实现：crates/omx-explore、crates/omx-sparkshell、crates/omx-api、crates/omx-runtime、crates/omx-runtime-core。package.json 中 build:explore、build:sparkshell、test:explore 等脚本也印证了这条 Rust 构建链：例如 "build:explore": "cargo build -p omx-explore-harness"、"test:explore": "cargo test -p omx-explore-harness && node --test dist/cli/__tests__/explore.test.js ..."。相关内容可进一步阅读 docs/release-notes-0.9.0.md 与 docs/release-body-0.9.0.md。

五、Hooks 扩展：在 `.omx/hooks/*.mjs` 上叠加插件

OMX 提供一套加法式（additive）的插件扩展面：omx hooks 命令族用于插件的脚手架生成与校验，而 omx tmux-hook 继续受支持且保持不变——omx hooks 不替代任何 tmux-hook 工作流。

插件文件位于 .omx/hooks/*.mjs；
README.de.md 提示"插件默认禁用，用 OMX_HOOK_PLUGINS=1 启用"；而仓库中更专门的 docs/hooks-extension.md 已更新为"插件默认启用，显式禁用用 OMX_HOOK_PLUGINS=0"，并支持超时调节 OMX_HOOK_PLUGIN_TIMEOUT_MS（默认 1500ms）。建议以最新的 docs/hooks-extension.md 为准，该文档还定义了完整的扩展工作流与事件模型。

快速开始：

omx hooks init
omx hooks status
omx hooks validate
omx hooks test

omx hooks init 会在 .omx/hooks/sample-plugin.mjs 生成一个脚手架插件。插件契约要求导出：

export async function onHookEvent(event, sdk) {
  // handle event
}

SDK 提供 sdk.tmux.sendKeys(...)、sdk.log.info|warn|error(...)、sdk.state.read|write|delete|all(...)（插件命名空间隔离）以及只读的 sdk.omx.session.read()、sdk.omx.hud.read()、sdk.omx.notifyFallback.read()、sdk.omx.updateCheck.read()。事件包络字段包括 schema_version: "1"、event、timestamp、source（native 或 derived）、context 以及可选的 session_id/thread_id/turn_id/mode；事件词汇表有 session-start、keyword-detector、pre-tool-use、post-tool-use、stop、session-end、turn-complete、session-idle。插件日志写入 .omx/logs/hooks-YYYY-MM-DD.jsonl。团队 Worker 会话（OMX_TEAM_WORKER 置位）默认跳过插件副作用，避免重复发送。

六、MCP workingDirectory 白名单：可选的安全加固

默认情况下，MCP 的 state/memory/trace 工具接受调用方提供的 workingDirectory。若要收紧，可设置允许的根目录白名单（多个根用冒号分隔）：

export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"

设置后，任何落在这些根之外的 workingDirectory 值都会被拒绝。该行为在源码 src/mcp/state-paths.ts 中有明确实现（常量 WORKDIR_ALLOWLIST_ENV = 'OMX_MCP_WORKDIR_ROOTS'，见第 60 行），对应测试集中在 src/mcp/tests/state-paths.test.ts：测试覆盖了"白名单外的 state root 被拒绝"（错误消息形如 State root ... is outside allowed roots (OMX_MCP_WORKDIR_ROOTS)）、"配置后强制白名单"、"拒绝通过符号链接逃逸白名单的 workingDirectory"以及"拒绝符号链接形式的白名单根目录本身"等场景——可见该加固不仅校验路径前缀，还防御 symlink 逃逸。

七、Codex-First Prompt 控制：AGENTS.md 注入与覆盖

默认情况下，OMX 向 Codex 注入：

-c model_instructions_file="<cwd>/AGENTS.md"

这会把 CODEX_HOME 下的 AGENTS.md 与项目 AGENTS.md（若存在）合并，然后把运行时叠加层（runtime overlay）置于其上。它扩展 Codex 行为，但不替换也不绕过 Codex 核心系统策略。

控制方式：

OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # 禁用 AGENTS.md 注入
OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx   # 指定自定义指令文件

这两条环境变量在仓库测试中均有覆盖（见 src/cli/tests/index.test.ts 中 respects OMX_MODEL_INSTRUCTIONS_FILE env override 等用例）。

八、Team 模式：tmux 驱动的并行 Worker 编排

Team 模式适合"能从并行 Worker 中获益的大规模工作"。生命周期如下：

start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown

操作命令：

omx team <args>
omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>

重要规则：除非是要取消，否则不要在任务仍处于 in_progress 时 shutdown。 团队到达终态后再 omx team shutdown <team-name>；团队清理现在走单一独立路径，旧式的 linked-Ralph shutdown 处理不再是独立的公开工作流。

从 src/cli/team.ts 可以看到实现侧的关键依赖：它调用 src/team/runtime.ts 的 startTeam/monitorTeam/resumeTeam/shutdownTeam，并复用 src/team/repo-aware-decomposition.ts 的仓库感知任务分解、src/team/role-router.ts 的角色路由、src/team/allocation-policy.ts 的任务分配。src/team 目录下还有 rebalance-policy.ts、worktree.ts、phase-controller.ts、progress-evidence.ts 等 40+ 模块，说明团队模式是 OMX 最重的运行时子系统之一。

Worker CLI 选择与环境变量

OMX_TEAM_WORKER_CLI=auto    # 默认；Worker --model 含 "claude" 时使用 claude，否则用 codex
OMX_TEAM_WORKER_CLI=codex   # 强制 Codex CLI Worker
OMX_TEAM_WORKER_CLI=claude  # 强制 Claude CLI Worker
OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # 按 Worker 逐个指定 CLI（长度=1 或等于 Worker 数）
OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # 可选：关闭自适应 Queue->Resend 回退

注意事项：

Worker 启动参数仍通过 OMX_TEAM_WORKER_LAUNCH_ARGS 共享；
OMX_TEAM_WORKER_CLI_MAP 会以 Worker 级选择覆盖 OMX_TEAM_WORKER_CLI；
触发（Trigger）提交默认带自适应重试：先 Queue/Submit，必要时再走"安全清行 + 重发"回退；
Claude Worker 模式下，OMX 以裸 claude 启动 Worker（不带额外启动参数），并忽略显式的 --model / --config / --effort 覆盖，让 Claude 使用默认 settings.json。

九、`omx setup` 到底写了什么

写入内容清单

.omx/setup-scope.json —— 持久化的安装范围；
按范围的安装（user vs project）：
- user：~/.codex/prompts/、~/.codex/skills/、~/.codex/config.toml、~/.omx/agents/、~/.codex/AGENTS.md
- project：./.codex/prompts/、./.codex/skills/、./.codex/config.toml、./.omx/agents/、./AGENTS.md
启动行为：若持久化范围是 project，则 omx 自动使用 CODEX_HOME=./.codex（前提是 CODEX_HOME 尚未设置）；
启动指令把 ~/.codex/AGENTS.md（若被覆盖则取 CODEX_HOME/AGENTS.md）与项目 ./AGENTS.md 合并，再追加运行时叠加层；
已有 AGENTS.md 从不静默覆盖：交互式 TTY 运行在替换前会询问；非交互运行在没有 --force 时跳过替换（活跃会话安全校验仍然生效）。

config.toml 更新内容（两个范围都生效）

notify = ["node", "..."]
model_reasoning_effort = "medium"
developer_instructions = "..."
[features]
multi_agent = true
child_agents_md = true
# MCP 服务器条目：omx_state、omx_memory、omx_code_intel、omx_trace、omx_wiki
[tui]
status_line

这些写入行为在 src/cli/setup.ts 中有完整实现（该文件约 6500 行，是 OMX 安装逻辑的核心），并通过 src/config/tests/generator-notify.test.ts 与 src/config/tests/generator-idempotent.test.ts 验证：例如测试断言 model_reasoning_effort = "medium" 会写入且位于 [features] 之前、child_agents_md = true 会写入、重复运行不会出现两个 model_reasoning_effort（幂等性）、用户自定义值（如 model_reasoning_effort = "high"）会被保留。此外 setup 还会写入范围专属 AGENTS.md、.omx/ 运行时目录与 HUD 配置，并为项目追加 .gitignore 条目（.omx/、.omx-state-locks/ 等，见 src/cli/setup.ts 中 PROJECT_GITIGNORE_ENTRIES）。

十、Agent 与 Skills 目录

Prompts：prompts/*.md，user 范围安装到 ~/.codex/prompts/，project 范围安装到 ./.codex/prompts/；
Skills：skills/*/SKILL.md，user 范围安装到 ~/.codex/skills/，project 范围安装到 ./.codex/skills/。

示例：

Agent：architect、planner、executor、debugger、verifier、security-reviewer；
Skills：deep-interview、ralplan、team、ralph、plan、cancel。

十一、项目结构：源码地图

README 给出顶层结构，结合当前仓库可得到完整对应：

oh-my-codex/
  bin/omx.js            # 实际为 dist/cli/omx.js（见 package.json bin 字段）
  src/
    cli/                # 全部子命令（setup/team/doctor/hooks/explore/ralph/ralplan...）
    team/               # 团队运行时（runtime/allocator/phase-controller/...）
    mcp/                # MCP 服务器（state/memory/trace/wiki/hermes/code-intel）
    hooks/              # 会话钩子、关键词检测、任务规模探测
    hud/                # HUD 渲染与 tmux 集成
    config/             # config.toml 生成器与特性开关
    modes/              # 模式状态机
    notifications/      # 通知调度（Discord/Telegram/Slack/webhook）
    verification/       # 验证与门禁
  prompts/              # Agent 角色提示词（30 个 *.md）
  skills/               # 技能（每个 SKILL.md）
  templates/            # 模板（AGENTS.md、model-instructions）
  scripts/              # 构建/发布/CI 脚本
  crates/               # Rust 原生组件（omx-explore/omx-sparkshell/...）

十二、开发与构建

git clone https://gitcode.com/GitHub_Trending/oh/oh-my-codex
cd oh-my-codex
npm install
npm run build    # tsc 编译到 dist/ 并生成可执行 omx
npm test         # 构建 + 原生 Agent/插件校验 + 全套 Node 测试 + 目录文档一致性检查

注意 package.json 中 build 会先清空 dist/，再执行 tsc 并给 dist/cli/omx.js 加执行权限；完整构建 npm run build:full 还会构建 Rust 的 explore/explore-harness/sparkshell/api 产物。因此首次使用任何 omx 命令前必须先 npm run build。