oh-my-codex（OMX）多 Agent 编排层完全指南：从首会话到团队并行执行

2026-09-09 21:22:38作者：冯爽妲Honey

oh-my-codex（简称 OMX）是为 OpenAI Codex CLI 打造的多 Agent 编排层：它通过 AGENTS.md、prompts、skills、config.toml 与 .omx 运行状态目录，将单一 Codex CLI 升级为可规划、可分工、可监控、可并行交付的开发环境。本文以 docs/readme/README.fr.md 为骨架，结合仓库源码与 CLI 实现，完整覆盖首次会话、推荐工作流、setup 安装产物、启动 flags、hooks 扩展、团队模式与关键环境变量，帮助你从零上手并在真实仓库中跑通"访谈澄清 → 计划审批 → 团队/单人执行"的完整闭环。

说明：本文面向中文读者，命令与配置均以当前仓库实际内容为准；涉及版本号、路径与默认值的内容，均标注了对应源码或文档依据。

一、OMX 是什么

OMX（Oh My codeX）的口号是 "Votre codex n'est pas seul"（你的 Codex 不再孤单）。它是一层运行在 OpenAI Codex CLI 之上的多 Agent 编排层，安装并连接以下层次：

User
  -> Codex CLI
    -> AGENTS.md (编排大脑)
    -> ~/.codex/prompts/*.md (Agent 提示词目录)
    -> ~/.codex/skills/*/SKILL.md (技能目录)
    -> ~/.codex/config.toml (功能开关、通知、MCP)
    -> .omx/ (运行状态、记忆、计划、日志)

AGENTS.md 承担"编排大脑"职责：它注入 -c model_instructions_file="<cwd>/AGENTS.md"，将 CODEX_HOME 下的 AGENTS.md 与项目级 AGENTS.md 合并，再叠加运行 overlay，从而扩展 Codex 行为，但不替换、不绕过 Codex 的系统级基础策略（参见 src/cli/index.ts 中 MODEL_INSTRUCTIONS_FILE_KEY、OMX_BYPASS_DEFAULT_SYSTEM_PROMPT_ENV、OMX_MODEL_INSTRUCTIONS_FILE_ENV 的定义，以及 src/cli/index.ts 中 shouldBypassDefaultSystemPrompt 与 buildModelInstructionsOverride 的实现）。
~/.codex/prompts/*.md 存放 Agent 提示词目录（对应仓库 prompts 目录）。
~/.codex/skills/*/SKILL.md 存放技能目录（对应仓库 skills 目录）。
~/.codex/config.toml 存放功能开关、通知与 MCP 配置。
.omx/ 是项目运行状态目录：会话状态、记忆、计划与日志都落在这里。

从源码结构看，OMX 的核心模块分布在 src 下：cli/（命令行入口）、team/（团队编排）、mcp/（MCP 服务器）、hooks/（钩子扩展）、hud/（tmux HUD）、config/（配置）、modes/（运行模式）、notifications/（通知）、verification/（验证）。

二、首次会话：在 Codex 中与从终端开始

2.1 在 Codex 会话中使用 Skill 命令

OMX 通过 skills 提供一组以 $ 开头的会话内指令，推荐的首次体验顺序：

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

$deep-interview：当需求范围或边界模糊时，通过结构化追问澄清需求。
$ralplan：将澄清后的范围转化为经过审批的架构与实现计划。
$ralph：以单一责任人持续完成与验证已批准的计划。
$team：启动并行执行（上例为 3 个 executor worker）。

这些 skill 的实现对应仓库 skills 下的 deep-interview、ralplan、ralph、team 等目录。

2.2 从终端启动团队

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

第一条命令以 4 个 executor worker 并行执行多模块重构任务；后两条用于查看团队状态与关闭团队。

2.3 推荐工作流（Flux recommandé）

$deep-interview —— 当范围或边界仍不清晰时使用；
$ralplan —— 将澄清后的范围转化为经过验证的架构与实现计划；
$team 或 $ralph —— 需要并行协调执行时用 $team；需要单一责任人做持久化收尾/验证循环时用 $ralph。

三、主要命令速查

omx                # 启动 Codex（若可用则在 tmux 中显示 HUD）
omx setup          # 按 scope 安装 prompts/skills/config + 项目 .omx + scope 专属 AGENTS.md
omx doctor         # 安装/运行诊断
omx doctor --team  # Team/Swarm 诊断
omx team ...       # 启动/查看状态/恢复/关闭 tmux 团队 workers
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 裸命令会启动 Codex，并在 tmux 可用时渲染 HUD（HUD 相关实现位于 src/hud）。
omx doctor 与 omx doctor --team 对应 CLI 实现见 src/cli/doctor.ts。
omx sparkshell 是 v0.9.0 引入的面向操作者的原生 surface，支持直接执行命令或对 tmux pane 输出做摘要（参见 src/cli/index.ts 的 usage 文本与 src/cli/sparkshell.ts）。

四、启动 Flags 一览

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

--madmax 等价于 Codex 的 --dangerously-bypass-approvals-and-sandbox，只能在受信任/外部沙箱环境中使用。
--scope 仅对 setup 生效，用于指定安装范围。
--force 在非交互式 setup 中允许覆盖已存在的 AGENTS.md（详见下文 setup 一节）。

五、Hooks 扩展（附加式 Surface）

v0.9.0 起 OMX 提供 omx hooks 命令，用于插件的脚手架搭建与校验：

omx tmux-hook 仍然受支持且行为不变；
omx hooks 是附加式能力，不会取代 tmux-hook 工作流；
插件文件位于 .omx/hooks/*.mjs；
插件默认通过环境变量启用：OMX_HOOK_PLUGINS=1（法文 README 描述为"默认禁用，用该变量启用"；不过从当前源码看，src/hooks/extensibility/loader.ts 的 isHookPluginsEnabled 实现为"默认开启、仅当显式设置为 0/false/no 时关闭"，不同版本语义存在差异，请以你安装版本的实际行为为准）。

在 src/hooks/extensibility/loader.ts 中可以看到插件机制的关键细节：

插件目录固定为 cwd/.omx/hooks（hooksDir，见 loader.ts）；
插件必须以 .mjs 结尾，并通过 export function onHookEvent（支持 async）或 export const/let/var onHookEvent 暴露入口，否则校验失败（ON_HOOK_EVENT_EXPORT_PATTERN 与 validatePluginExport，见 loader.ts）；
插件 id 由文件名清洗生成，同名冲突时追加文件名 SHA-256 前 8 位哈希（sanitizePluginId 与 shortFileHash，见 loader.ts）；
插件执行超时可经 OMX_HOOK_PLUGIN_TIMEOUT_MS 调整，默认 1500ms，取值范围 100～60000ms（readTimeout，见 loader.ts）。

完整的扩展工作流与事件模型参见 docs/hooks-extension.md。

六、Codex-First 的提示词控制

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

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

这会合并 CODEX_HOME 下的 AGENTS.md 与项目级 AGENTS.md（如果存在），再叠加运行 overlay。它扩展 Codex 行为，但不会替换或绕过 Codex 的系统级基础策略。

在源码中，这一逻辑体现为：shouldBypassDefaultSystemPrompt 仅当环境变量 OMX_BYPASS_DEFAULT_SYSTEM_PROMPT 显式等于 "0" 时才返回 false（src/cli/index.ts），而 buildModelInstructionsOverride 会优先取 OMX_MODEL_INSTRUCTIONS_FILE，否则回退到 <cwd>/AGENTS.md（src/cli/index.ts）。

可控开关：

OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # 禁用 AGENTS.md 注入
OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx

七、团队模式（Mode équipe）

团队模式适用于需要并行 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，就不要关闭团队（除非决定放弃）。

7.1 Team shutdown 策略

当团队进入终态后使用 omx team shutdown <team-name>。当前团队清理走单一独立路径，旧的"linked-Ralph 联动 shutdown"处理已不再是独立的公开工作流。

7.2 Worker CLI 选择（重要环境变量）

OMX_TEAM_WORKER_CLI=auto    # 默认；当 worker --model 包含 "claude" 时使用 claude
OMX_TEAM_WORKER_CLI=codex   # 强制所有 worker 使用 Codex CLI
OMX_TEAM_WORKER_CLI=claude  # 强制所有 worker 使用 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。

源码佐证：resolveRuntimeCliProviderMap 会按 worker 解析 CLI 提供方并临时写入 OMX_TEAM_WORKER_CLI_MAP 环境变量，团队启动结束后再恢复或删除该变量（见 src/team/runtime-cli.ts）。团队运行时的中断/信号处理（SIGINT/SIGTERM）与 shutdown 路径也在 src/team/runtime-cli.ts 中体现：失败/取消路径强制清理以绕过 shutdown 门槛。

八、`omx setup` 会写入什么

.omx/setup-scope.json（持久化的 setup scope）
依赖 scope 的安装内容：
- 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
启动行为：若持久化 scope 为 project，则 omx 启动时自动使用 CODEX_HOME=./.codex（除非 CODEX_HOME 已定义）。
启动指令会合并 ~/.codex/AGENTS.md（或重定义后的 CODEX_HOME/AGENTS.md）与项目 ./AGENTS.md，再叠加运行 overlay。
已存在的 AGENTS.md 永远不会被静默覆盖：交互式 TTY 下 setup 会先询问；非交互式下除非带 --force，否则跳过覆盖（活跃会话安全检查始终生效）。
config.toml 更新（两个 scope 均适用）：
- 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
scope 专属的 AGENTS.md
运行目录 .omx/ 与 HUD 配置

8.1 MCP workingDirectory 策略（可选加固）

默认情况下，状态/记忆/追踪类 MCP 工具接受调用方提供的 workingDirectory。如需收紧，可设置根目录白名单：

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

设置后，位于这些根目录之外的 workingDirectory 值将被拒绝。源码中该白名单环境变量定义于 src/mcp/state-paths.ts（WORKDIR_ALLOWLIST_ENV），OMX 还支持 OMX_ROOT、OMX_STATE_ROOT、OMX_TEAM_STATE_ROOT、OMX_SESSION_ID 等状态路径相关环境变量（见 src/mcp/state-paths.ts）。

九、Agents 与 Skills

Prompts：prompts/*.md（user scope 安装到 ~/.codex/prompts/，project scope 安装到 ./.codex/prompts/）
Skills：skills/*/SKILL.md（user scope 安装到 ~/.codex/skills/，project scope 安装到 ./.codex/skills/）

示例：

Agents：architect、planner、executor、debugger、verifier、security-reviewer
Skills：autopilot、plan、team、ralph、ultrawork、cancel

仓库中可对应查看 prompts 目录（含 architect.md、planner.md、executor.md、debugger.md、verifier.md、security-reviewer.md 等）与 skills 目录（含 autopilot、plan、team、ralph、ultrawork、cancel 等）。

十、项目结构

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

仓库实际结构还包含 crates/（Rust 原生组件，如 omx-sparkshell、omx-explore、omx-runtime 等）、packages/、plugins/、docs/ 与 missions/ 等目录，与上述核心布局一致。

十一、开发与构建

git clone https://github.com/Yeachan-Heo/oh-my-codex.git
cd oh-my-codex
npm install
npm run build
npm test

十二、更多文档

完整文档与 CLI 参考：见项目站点的 Documentation 与 CLI Reference
通知配置（Discord、Telegram、Slack、webhooks）：见 Documentation 的 Notifications 章节
推荐工作流：见 Documentation 的 Workflows 章节
发布说明：见 Documentation 的 Release Notes 章节

仓库内可读资源：

完整变更日志：CHANGELOG.md
v0.4.4 主线迁移指南：docs/migration-mainline-post-v0.4.4.md
覆盖率与对等性说明：COVERAGE.md
Hooks 扩展工作流：docs/hooks-extension.md
配置与贡献细节：CONTRIBUTING.md
v0.9.0 发布说明：docs/release-notes-0.9.0.md
v0.9.0 发布正文：docs/release-body-0.9.0.md

十三、v0.9.0 Spark Initiative 亮点回顾

Spark Initiative 是强化 OMX 原生探索与检查路径的版本：

omx explore 原生 harness —— 通过更快的 Rust 原生路径执行只读仓库探索（相关原生组件见 crates/omx-explore）；
omx sparkshell —— 面向操作者的原生 surface，支持长输出摘要与显式 tmux pane 捕获（CLI 入口见 src/cli/sparkshell.ts，Rust 组件见 crates/omx-sparkshell；--tmux-pane <pane-id> [--tail-lines <100-1000>] 的参数解析与校验见 src/cli/sparkshell.ts）；
原生跨平台 artifacts —— omx-explore-harness、omx-sparkshell 与 native-release-manifest.json 的水合路径已纳入发布流水线；
强化 CI/CD —— 在 build job 中显式配置 Rust toolchain，并增加 cargo fmt --check 与 cargo clippy -- -D warnings。