oh-my-codex（OMX）实战指南：为 Codex CLI 构建多智能体编排层、Spark 原生工具链与团队并行工作流

本篇技术指南围绕 OpenAI Codex CLI 的多智能体编排层 oh-my-codex（简称 OMX）展开，完整介绍其在当前仓库 docs/readme/README.ru.md 中定义的 v0.9.0 Spark Initiative 原生探索工具链、推荐工作流、核心命令、启动安全标志、团队（team）并行模式与 omx setup 的落盘内容。读完本文，你将能够独立完成 OMX 的安装诊断、首次会话启动、提示工程与 Hooks 扩展配置，并在真实仓库中调度 $deep-interview → $ralplan → $team/$ralph 的澄清—规划—执行闭环。

OMX 是什么：Codex 之上的编排层，而非替代品

OMX 是 OpenAI Codex CLI 之上的多智能体工作流层。其核心设计哲学是：Codex 负责真正执行代理工作，OMX 负责让角色可复用、让工作流可复用、让运行态可持久化。它通过 AGENTS.md、提示目录、技能目录、配置与 .omx/ 运行态目录把五个层面绑定在一起：

User
  -> Codex CLI
    -> AGENTS.md（编排大脑）
    -> ~/.codex/prompts/*.md（代理提示目录）
    -> ~/.codex/skills/*/SKILL.md（技能目录）
    -> ~/.codex/config.toml（功能、通知、MCP）
    -> .omx/（执行状态、记忆、计划、日志）

这一分层模型明确表达了 OMX 的边界：它不替换、也不绕过 Codex 的核心系统策略，只是在外部追加一层"更强的启动默认值、更一致的工作流、更持久的运行态"。

v0.9.0 Spark Initiative：原生探索与检查工具链

Spark Initiative 是强化 OMX 原生探索与检查路径的版本，包含四大要点：

1. omx explore 的原生 harness：通过 Rust 路径加速并收紧只读仓库探索；
2. omx sparkshell：原生的检查操作员界面，支持长输出摘要与显式 tmux-pane 捕获；
3. 跨平台原生 release 产物：omx-explore-harness、omx-sparkshell 与 native-release-manifest.json 的 hydration 路径已进入 release pipeline；
4. 增强的 CI/CD：在 build job 中显式配置 Rust toolchain，并启用 cargo fmt --check 与 cargo clippy -- -D warnings。

源码视角：explore harness 的约束边界

从源码结构看，原生探索路径由独立 crate 承载，仓库 Cargo.toml 将工作区拆分为 omx-api、omx-explore、omx-mux、omx-runtime、omx-runtime-core 与 omx-sparkshell 六个成员。crates/omx-explore/src/main.rs 中定义了一系列默认约束：默认 Codex 调用超时 DEFAULT_CODEX_TIMEOUT_MS: u64 = 180_000（180 秒）、默认进程上限 DEFAULT_PROCESS_LIMIT: usize = 96、默认输出字节上限 DEFAULT_CODEX_OUTPUT_LIMIT_BYTES: usize = 8 * 1024 * 1024（8 MiB），并会清理 BASH_ENV、ENV、PROMPT_COMMAND、NODE_OPTIONS 等子进程环境变量，避免继承的 shell 配置污染只读探索。这些常量体现了"严格只读、可审计、资源受限"的设计意图。

源码视角：sparkshell 的 tmux-pane 捕获与输出摘要

crates/omx-sparkshell/src/main.rs 定义了三种检查目标：普通命令（Command）、shell 字符串（Shell）以及 tmux-pane 捕获（TmuxPane { pane_id, tail_lines }）。其 tmux 尾部行数默认值为 200 行，最小 100 行、最大 1000 行（见 DEFAULT_TMUX_TAIL_LINES、MIN_TMUX_TAIL_LINES、MAX_TMUX_TAIL_LINES 常量）。omx_sparkshell 还通过 omx-mux crate 的 build_capture_pane_args 构建 pane 捕获参数，并对输出进行阈值判定（threshold.rs 中的 combined_visible_lines、read_line_threshold）、敏感信息脱敏（redaction.rs）与 Codex 摘要桥接（codex_bridge.rs），实现"长输出先摘要、关键证据显式捕获"的操作员体验。

相关 release 说明详见 docs/release-notes-0.9.0.md 与 docs/release-body-0.9.0.md。

首次会话：在 Codex 内与在终端内

在 Codex 会话内使用技能

安装并完成 setup 后，在 Codex 内部可以直接以 $ 前缀调用 OMX 技能：

$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"

从终端操作团队

omx team 4:executor "parallelize a multi-module refactor"
omx team status <team-name>
omx team shutdown <team-name>

推荐工作流：澄清 → 规划 → 执行

OMX 推荐的默认路径是三段式：

1. $deep-interview —— 当任务规模或边界尚未明确时先做澄清式深访；
2. $ralplan —— 将澄清后的范围转化为经批准的架构与实现计划；
3. $team 或 $ralph —— 需要协调的并行执行用 $team；需要一个负责人持续迭代直至完成并校验时用 $ralph。

这一链条对应仓库中 skills/deep-interview/SKILL.md、skills/ralplan/SKILL.md、skills/ralph/SKILL.md 与 skills/team/SKILL.md 四个技能的实现定位。

核心命令速查

omx                # 启动 Codex（存在 tmux 时附带 HUD）
omx setup          # 按作用域安装 prompts/skills/config + 项目 .omx + 所选作用域的 AGENTS.md
omx doctor         # 诊断安装/运行环境
omx doctor --team  # 诊断 Team/swarm
omx team ...       # 启动/查看状态/恢复/终止工作 tmux
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 可执行入口在 package.json 的 bin 字段中声明为 dist/cli/omx.js，且要求 Node.js >=20。omx doctor 负责核对 OMX 文件、hooks 与运行前置条件，建议首次安装后先跑一次；再配合 codex login status 与一次真实执行探测（如 omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"）验证认证与 provider 链路。

Hooks 扩展：tmux-hook 与插件式 hooks

OMX 在原有 omx tmux-hook 之外新增了 omx hooks 子命令，用于生成插件模板与校验：

• omx tmux-hook 保持兼容、行为不变；
• omx hooks 是额外的扩展表面，不替代 tmux-hook 工作流；
• 插件文件位于 .omx/hooks/*.mjs；
• 插件默认关闭，需通过环境变量 OMX_HOOK_PLUGINS=1 启用。

完整的事件模型与扩展工作流记录在 docs/hooks-extension.md，仓库 plugins/oh-my-codex/hooks/ 下提供了官方插件布局样例。

启动标志与安全边界

--yolo
--high
--xhigh
--madmax
--force
--dry-run
--verbose
--scope <user|project>  # 仅对 setup 生效

安全提示：--madmax 对应 Codex 的 --dangerously-bypass-approvals-and-sandbox，会移除常规审批与沙箱护栏，只能在受信任的仓库与外部沙箱环境中使用。--high 与 --xhigh 则是对 -c model_reasoning_effort="high|xhigh" 的简写，用于提升推理强度，属于日常强会话的推荐组合（如 omx --madmax --xhigh）。

MCP workingDirectory 策略（可选加固）

默认情况下，state/memory/trace 等 MCP 工具接受调用方提供的 workingDirectory。若希望收紧权限，可设置允许根目录列表：

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

设置后，超出这些根目录的 workingDirectory 会被拒绝。源码实现在 src/mcp/state-paths.ts：该文件以 OMX_MCP_WORKDIR_ROOTS 作为白名单环境变量（WORKDIR_ALLOWLIST_ENV），解析并规范化根列表后，用 isWithinRoot 判断目标目录是否落在允许根之内，越界则抛出 outside allowed roots 错误；同时会拒绝含 NUL 字节的路径，并在非 Windows 主机上拒绝 Windows 风格路径。

Codex-First 的提示管理

默认情况下 OMX 会注入：

-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

团队模式：并行执行的生命周期

团队模式面向"受益于并行执行者"的大规模工作。其生命周期为：

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。

Team shutdown 策略

在团队达到终态（terminal state）后使用 omx team shutdown <team-name>。团队清理现在走唯一独立路径；旧的 linked-Ralph shutdown 处理已不再是独立的公开工作流。相关实现可见 src/team/team-ops.ts 与 src/team/runtime.ts，团队运行态类型定义在 src/team/contracts.ts。

Worker CLI 选择

团队 worker 的 CLI 选择由以下环境变量控制：

OMX_TEAM_WORKER_CLI=auto    # 默认；worker --model 含 "claude" 时使用 claude
OMX_TEAM_WORKER_CLI=codex   # 强制 Codex CLI
OMX_TEAM_WORKER_CLI=claude  # 强制 Claude CLI
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；
• 触发发送默认采用自适应重试（queue/submit，必要时安全回退为 clear-line+resend）；
• Claude worker 模式下，OMX 以普通 claude 启动 worker（不带额外参数），并忽略显式的 --model / --config / --effort 覆盖，让 Claude 使用标准 settings.json。

从源码结构看，worker CLI 选择逻辑集中在 src/team/runtime-cli.ts，其中定义了 TeamWorkerProvider = 'codex' | 'claude' | 'gemini' 联合类型，并对 agentTypes 非法取值抛出 Expected codex|claude|gemini 错误；OMX_TEAM_WORKER_CLI_MAP 会被暂存并在 worker 启动后恢复。src/team/ 目录下还包含 scaling.ts、allocation-policy.ts、rebalance-policy.ts、tmux-session.ts、worktree.ts 等模块，共同支撑并行度扩展、分配策略、tmux 会话与 worktree 隔离。

omx setup 会写入什么

omx setup 的落盘内容分为四类：

• .omx/setup-scope.json：保存安装作用域；
• 按作用域安装：
  • 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_HOME=./.codex；启动指令合并 ~/.codex/AGENTS.md（或覆盖后的 CODEX_HOME/AGENTS.md）与项目 ./AGENTS.md，再追加 runtime-overlay；
• 保护策略：现有 AGENTS.md 不会被静默覆盖——交互式 TTY 下 setup 会先询问，非交互模式无 --force 则跳过替换（活动会话安全检查仍然生效）。

config.toml 更新内容（两种作用域一致）：

• notify = ["node", "..."]
• model_reasoning_effort = "medium"
• developer_instructions = "..."
• [features] multi_agent = true, child_agents_md = true
• MCP server 条目（omx_state、omx_memory、omx_code_intel、omx_trace、omx_wiki）
• [tui] status_line

此外还包括所选作用域的 AGENTS.md、.omx/ 目录与 HUD 配置。

代理与技能体系

• 提示（Prompts）：prompts/*.md，user 作用域安装到 ~/.codex/prompts/，project 作用域安装到 ./.codex/prompts/；
• 技能（Skills）：skills/*/SKILL.md，user 作用域安装到 ~/.codex/skills/，project 作用域安装到 ./.codex/skills/。

典型代理：architect、planner、executor、debugger、verifier、security-reviewer。典型技能：deep-interview、ralplan、team、ralph、plan、cancel。这些名字在当前仓库的 prompts/ 与 skills/ 目录下均有对应实现，例如 prompts/planner.md、prompts/executor.md、skills/team/SKILL.md、skills/ralph/SKILL.md。

项目结构

oh-my-codex/
  bin/omx.js
  src/
    cli/
    team/
    mcp/
    hooks/
    hud/
    config/
    modes/
    notifications/
    verification/
  prompts/
  skills/
  templates/
  scripts/

当前仓库的实际结构与文档一致：src/cli/ 承载命令入口，src/team/ 承载团队编排，src/mcp/ 承载 state/memory/code-intel/trace/wiki 等 MCP 服务器，src/hooks/ 承载扩展与原生钩子，src/hud/ 承载 tmux HUD 渲染，src/config/ 承载配置生成。自 v0.9.0 起，仓库还新增了 crates/ 目录，以 Rust 实现 explore harness、sparkshell、mux 与 runtime 等原生组件。

开发与测试

从源码构建与测试：

git clone https://gitcode.com/GitHub_Trending/oh/oh-my-codex
cd oh-my-codex
npm install
npm run build
npm test

构建产出为 dist/，入口为 dist/cli/omx.js。若需要构建 Rust 原生组件，可执行 npm run build:explore（cargo build -p omx-explore-harness）或 npm run build:runtime（cargo build -p omx-runtime），完整构建使用 npm run build:full。npm test 会依次执行 TypeScript 构建、原生代理校验、插件包校验、能力锁校验、提示指导校验与全量 node 测试，并附带生成目录校验（见 package.json 中 test 脚本）。运行时与探索相关的测试还可通过 npm run test:explore（cargo test + 对应 node 测试）执行。

补充文档与后续阅读

• 完整变更日志：CHANGELOG.md
• v0.4.4 mainline 之后的迁移指南：docs/migration-mainline-post-v0.4.4.md
• 覆盖率与 parity 说明：COVERAGE.md
• Hook 扩展工作流：docs/hooks-extension.md
• 安装与参与贡献细节：CONTRIBUTING.md
• OpenClaw 集成指南（俄语版）：docs/openclaw-integration.ru.md

OMX 受 oh-my-claudecode 启发，并为 Codex CLI 重新适配，项目采用 MIT 许可证。无论你是想为日常 Codex 会话加上更强的工作流，还是需要多 worker 并行的大型重构，OMX 的澄清—规划—执行闭环与原生 Rust 探索工具链都提供了开箱即用的路径——先 omx setup 选择作用域，再 omx doctor 验证环境，然后从一个 $deep-interview 开始你的第一次 OMX 会话。