Oh My Codex（OMX）实战指南：为 OpenAI Codex CLI 打造的多智能体编排层与 Spark Initiative 原生加速路径

OMX（Oh My Codex）是围绕 OpenAI Codex CLI 构建的多智能体编排与工作流增强层：它不替换 Codex 执行引擎本身，而是通过分层编排、skill 目录、tmux 团队运行时与 Rust 原生侧车，让 Codex 会话从一开始就更强、更可控。本文以仓库自带的土耳其语版项目总览 docs/readme/README.tr.md 为主体骨架，结合 TypeScript 主仓源码与 Rust crates 实现，系统讲解 OMX 的安装、首次会话、推荐工作流、核心命令、启动标志、Hooks 扩展、团队模式与配置细节，帮助你掌握一套可直接落地的 Codex 多智能体工作环境。

一、OMX 是什么：Codex 不是孤军奋战

OMX 的定位一句话即可概括：Codex 负责真正干活，OMX 负责让活干得更有条理。官方 README 明确强调，OMX 不替换 Codex，而是在它外围叠加了三层能力：

• 角色关键词（role keywords）：让有价值的角色（architect、planner、executor、debugger、verifier、security-reviewer 等）可以被复用；
• Skills 工作流：把常见工作流（deep-interview、ralplan、team、ralph、plan、cancel 等）固化为可复用技能；
• .omx/ 运行时代：保存计划、日志、记忆与模式跟踪状态。

官方推荐把 OMX 理解成 "更好的任务路由 + 更好的工作流 + 更好的运行时"，而不是一个需要全天手动敲命令的操作台。对应地，仓库根目录的 README.md 给出的心智模型是：Codex 是执行引擎，OMX 让默认会话更强、让从澄清到完成的流程一致、让项目指导、计划、日志与状态统一落在 .omx/ 目录内。

二、Spark Initiative：v0.9.0 引入的原生快速路径

README.tr.md 将 Spark Initiative 描述为"强化 OMX 内部 native 发现与检查路径"的版本。结合 docs/release-notes-0.9.0.md 可以确认，它在 v0.9.0 中带来四项核心变化：

1. omx explore 的 native harness：把只读仓库发现放到 Rust 实现上，走更快、更严格的路径；
2. omx sparkshell：面向操作者的原生检查界面，支持总结长输出与显式 tmux pane 捕获；
3. 跨平台 native release 资产：omx-explore-harness、omx-sparkshell 与 native-release-manifest.json 的 hydration 路径成为 release 流水线的一部分；
4. 强化 CI/CD：在 build job 中显式安装 Rust 工具链，并新增 cargo fmt --check 与 cargo clippy -- -D warnings 检查。

2.1 从 Spark 到现状：explore 已硬弃用，sparkshell 是推荐入口

需要特别说明的是，仓库当前的实际状态比 README.tr.md 更进一步：在 src/cli/explore.ts 中，omx explore 已被标记为 hard-deprecated，直接命令表面已被移除，源码中的弃用提示明确写着：

omx explore 已被硬弃用，直接命令表面已移除。只读仓库查询请使用常规 Codex 仓库检查工具/子代理；显式的 shell 原生只读取证请使用 omx sparkshell -- <command>，或使用 --tmux-pane 总结。

因此，当前版本真正可用的原生快速路径是 omx sparkshell。它的用法在 src/cli/sparkshell.ts 中有明确定义：

Usage: omx sparkshell <command> [args...]
   or: omx sparkshell [--json] [--budget <chars>] <command> [args...]
   or: omx sparkshell --shell '<shell command>'
   or: omx sparkshell --tmux-pane <pane-id> [--tail-lines <100-1000>]

要点：

• 默认 argv 直接执行：shell 元字符只有在显式 --shell 选择加入时才会被解释；
• --tmux-pane 模式：显式选择加入，先捕获更大的 pane 尾部，再应用 raw-vs-summary 行为，适合总结某个 tmux 窗格的长输出；
• 环境变量覆盖面刻意收窄，来自源码的完整清单为：
  • OMX_SPARKSHELL_BIN：指定 native 侧车二进制路径；
  • OMX_SPARKSHELL_MODEL：选择主要总结模型；
  • OMX_SPARKSHELL_FALLBACK_MODEL：选择重试模型；
  • OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE：覆盖打包的总结指令；
  • OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS：控制本地 API 总结超时。

典型示例：

omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400

2.2 底层 Rust 实现：允许列表与进程限制

omx sparkshell 与（曾经的）explore harness 都构建在 Rust 侧车之上。仓库 crates/ 下提供了一组原生 crate：crates/omx-api、crates/omx-explore、crates/omx-mux、crates/omx-runtime、crates/omx-runtime-core 与 crates/omx-sparkshell。

从 crates/omx-explore/src/main.rs 可以清楚看到"只读 + 允许列表 + 受限"的设计哲学：

• 允许列表直接命令：rg、grep、ls、find、wc、cat、head、tail、pwd、printf；
• 默认超时与进程上限：OMX_EXPLORE_CODEX_TIMEOUT_MS 默认 180000ms，进程上限默认 96，输出上限默认 8MB；
• 环境清洗：子进程会剥离 BASH_ENV、ENV、PROMPT_COMMAND、NODE_OPTIONS、SHELLOPTS、BASHOPTS、GREP_OPTIONS、GREP_COLORS 等可能注入副作用的环境变量；
• Windows 限制：内置 harness 依赖 POSIX sh/bash 包装器，因此在原生 Windows 上不可用，需设置 OMX_EXPLORE_BIN 指向兼容的自定义 harness，或改用 sparkshell。

三、首次会话与推荐工作流

3.1 安装与前置要求

官方安装路径（来自 README.md）要求：

• Node.js 20+；
• 已安装并完成认证的 Codex CLI（codex --version 验证；Homebrew 或 npm 安装均可，不要在 Homebrew 已拥有 codex 二进制的情况下再用 npm 重装 @openai/codex，否则可能因 EEXIST 失败）；
• tmux（macOS/Linux 上若想使用推荐的持久团队运行时）；
• 原生 Windows 上仅当刻意选择次级 Windows 团队路径时才需要 psmux。

安装：

codex --version
npm install -g oh-my-codex
# 在你要让 Codex 编辑的 git 项目中，用任务相关名称启动
omx --worktree=feat/task --madmax --xhigh

安装后建议立即做两道边界检查：

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

其中 omx doctor 检查 OMX 文件、hooks 与运行时前置是否齐备；真正的冒烟测试是第三行——它能暴露认证、profile、provider/base-URL 等只有在 Codex 真正发起模型请求时才会出现的问题（详见 docs/troubleshooting.md 的"false-green readiness"一节）。

3.2 Codex 内的首个会话

README.tr.md 给出了进入 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.3 从终端启动与团队操作

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

3.4 官方推荐流程（三阶段）

README.tr.md 给出的推荐链路是：

1. $deep-interview——当范围或边界还不清晰时，用苏格拉底式追问澄清需求；
2. $ralplan——把澄清后的范围转化为已批准架构与实现计划，评审权衡；
3. $team 或 $ralph——需要协调的并行执行用 $team；想要单一负责人、持久完成/验证循环时用 $ralph。

仓库 README.md 在此基础上给出更完整的默认路径：$deep-interview -> $ralplan -> $ultragoal，其中 $ultragoal 是默认的持久多目标完成包装器（配合 .omx/ultragoal 账本检查点），而 $autopilot 是这条链的首选一等编曲器。若任务需要显式的目标/检查点结构，使用 /goal；/skills 用于浏览已安装技能。

四、核心模型：OMX 的分层结构

README.tr.md 用一段文本图清晰描述了 OMX 建立并连接的层：

User
  -> Codex CLI
    -> AGENTS.md (orkestrasyon beyni / 编排大脑)
    -> ~/.codex/prompts/*.md (ajan prompt kataloğu / agent prompt 目录)
    -> ~/.codex/skills/*/SKILL.md (skill 目录)
    -> ~/.codex/config.toml (özellikler, bildirimler, MCP / 特性、通知、MCP)
    -> .omx/ (çalışma zamanı durumu, bellek, planlar, günlükler / 运行时状态、内存、计划、日志)

这条链路的核心含义是：

• AGENTS.md 是编排大脑：默认情况下 OMX 会注入 -c model_instructions_file="<cwd>/AGENTS.md"（详见下文"Codex-First Prompt 控制"），将 CODEX_HOME 中的 AGENTS.md 与项目级 AGENTS.md 合并，再叠加运行时覆盖；
• prompts/skills 是能力目录：角色与技能以文件形式安装在 ~/.codex/（user 范围）或 ./.codex/（project 范围）下；
• config.toml 是特性开关：功能、通知、MCP 服务器配置都聚合在这里；
• .omx/ 是持久状态：计划、日志、内存与模式跟踪统一落盘。

五、主要命令速查

README.tr.md 列出的一组核心命令是日常操作的基础面：

omx                # 启动 Codex（tmux 中带 HUD）
omx setup          # 按范围安装 prompt/skill/config + 项目 .omx + 范围专属 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

从 src/cli/index.ts 与 src/cli/omx.ts 的源码结构看，CLI 入口是一个大型命令分发器：omx.ts 只是加载 dist/cli/index.js 的引导脚本，真正的子命令在 src/cli/ 下按文件拆分（setup.ts、doctor.ts、team.ts、tmux-hook.ts、hooks.ts、hud/、ralph.ts、ralplan.ts、ultragoal.ts、sparkshell.ts 等），这也是本文引用各个命令实现时可追溯的目录。

六、启动标志与安全边界

README.tr.md 列出以下启动标志：

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

关键语义（结合 README.md 确认）：

• --madmax：OMX 对 Codex --dangerously-bypass-approvals-and-sandbox 的简写，会移除常规的审批与沙箱护栏。README.tr.md 明确警告：只能在受信任/外部沙箱环境中使用；
• --high / --xhigh：分别是 -c model_reasoning_effort="high" 与 "xhigh" 的简写；一个标准的强会话是 omx --madmax --xhigh；
• --force：交互式 TTY 下跳过 setup 改写前的询问（详见下文 setup 章节）；
• --dry-run / --verbose：试运行与详细输出；
• --scope <user|project>：仅用于 omx setup，决定安装范围。

安全建议：在 git 仓库中使用 --madmax 时，优先采用 worktree 启动 omx --worktree=<task> --madmax --xhigh 而非直接在当前 checkout 运行；并发的 --madmax 会话绝不放在同一目录，每个会话使用独立的命名 worktree（如 --worktree=feature/auth 与 --worktree=fix/flaky-tests）。worktree 名会创建在 ../<repo>.omx-worktrees/ 下。

七、MCP workingDirectory 白名单策略（可选加固）

OMX 内置的 MCP 状态/内存/trace 工具默认接受调用方提供的 workingDirectory 值。README.tr.md 提供了一种可选加固手段——通过环境变量设置白名单根目录：

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

一旦设置，白名单之外的 workingDirectory 值会被直接拒绝。这属于可选的硬化策略，适合多项目共享环境或对路径敏感的安全场景。

八、Codex-First Prompt 控制

OMX 默认注入：

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

其效果是：把 CODEX_HOME 内的 AGENTS.md 与项目 AGENTS.md（若存在）合并，再叠加运行时覆盖层。README.tr.md 特别强调：这扩展了 Codex 的行为，但不会修改或跳过 Codex 的核心系统策略。

两个控制开关：

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

从 docs/codex-native-hooks.md 还可以看到，.codex/hooks.json 与 .omx/hooks/*.mjs 是两条不同的 hook 落点：前者是 omx setup 安装的原生 Codex hook 注册，后者是运行时/原生事件分发的 OMX 插件 hook。

九、Hooks 扩展：插件化的事件表面

9.1 命令与脚手架

README.tr.md 指出 omx hooks 是"附加表面"：omx tmux-hook 继续受支持且不变，omx hooks 是增量式的，不会改变 tmux-hook 工作流。插件文件位于 .omx/hooks/*.mjs。

从 src/cli/hooks.ts 的 HELP 文本可以看到完整子命令：

omx hooks init       # 创建 .omx/hooks/sample-plugin.mjs 脚手架
omx hooks status     # 显示插件目录 + 已发现的插件
omx hooks validate   # 校验插件导出/签名
omx hooks test       # 向插件分发合成 turn-complete 事件

9.2 启用模型

docs/hooks-extension.md 明确了启用模型：

• 插件默认启用；显式禁用：export OMX_HOOK_PLUGINS=0；
• 可选超时调优（默认 1500ms）：export OMX_HOOK_PLUGIN_TIMEOUT_MS=1500。

需要提醒的是，README.tr.md 写的是"默认关闭、用 OMX_HOOK_PLUGINS=1 启用"，而当前仓库的 hooks 扩展文档已更新为"默认启用、用 OMX_HOOK_PLUGINS=0 禁用"。以当前仓库的 docs/hooks-extension.md 为准。

9.3 事件词汇与插件契约

OMX 向插件暴露的统一事件词汇（v1）为：session-start、keyword-detector、pre-tool-use、post-tool-use、stop、session-end、turn-complete、session-idle。OMX 刻意保留这套既有词汇而非直接暴露 Codex 原生 hook 名，使原生 hook 与 fallback/派生路径共享同一套插件/运行时表面。

事件信封字段包括：schema_version: "1"、event、timestamp、source（native 或 derived）、context，以及可选的 session_id、thread_id、turn_id、mode。

每个插件必须导出：

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()

其中 sdk.omx 在第一阶段刻意保持窄且只读，用于读取当前工作区仓库根目录 .omx/state/*.json 的运行时文件。hooks.ts 中自带的 sample-plugin.mjs 脚手架演示了完整写法——它监听 turn-complete，用 sdk.state.read/write 维护一个 sample-seen-count 计数，并通过 sdk.log.info 输出观察结果。

插件分派与日志写入 .omx/logs/hooks-YYYY-MM-DD.jsonl。团队 worker 会话（设置了 OMX_TEAM_WORKER）中插件副作用默认被跳过，以保证 lead 会话是唯一的副作用发射者、避免重复发送。

十、团队模式：tmux 上的并行 workers

10.1 生命周期与操作命令

README.tr.md 给出的团队生命周期为：

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 作为公开工作流（omx team shutdown 即统一入口）。

10.2 Worker CLI 选择

README.tr.md 给出了 worker 执行器选择的完整环境变量矩阵：

OMX_TEAM_WORKER_CLI=auto    # 默认；若 worker 包含 --model "claude" 则用 claude
OMX_TEAM_WORKER_CLI=codex   # 强制 Codex CLI workers
OMX_TEAM_WORKER_CLI=claude  # 强制 Claude CLI workers
OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # 按 worker 的 CLI 混合（长度=1 或 worker 数量）
OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # 可选：禁用自适应 queue->resend 回退

补充说明（来自 README.tr.md 的 Notes）：

• 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 启动 workers（无额外启动参数），并忽略显式的 --model / --config / --effort 覆盖，以便使用 Claude 的默认 settings.json。

10.3 平台注意

团队运行时在 macOS/Linux + tmux 上效果最佳；原生 Windows 是次级路径，推荐 WSL2。平台安装方式：README.md 中给出了 brew install tmux（macOS）、sudo apt install tmux（Ubuntu/Debian）、sudo dnf install tmux（Fedora）、sudo pacman -S tmux（Arch）、winget install psmux（Windows 原生）、sudo apt install tmux（Windows WSL2）。

十一、omx setup 究竟写了什么

README.tr.md 对此有非常详尽的清单，是理解 OMX 落盘行为的关键：

持久化范围文件：.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。

AGENTS.md 合并策略：启动指令合并 ~/.codex/AGENTS.md（或被覆盖时的 CODEX_HOME/AGENTS.md）与项目 ./AGENTS.md，再叠加运行时覆盖层。现有的 AGENTS.md 不会被静默覆盖：交互式 TTY 下 setup 在改动前会先询问；非交互运行下，若没有 --force 则跳过改写（active-session 安全检查仍然生效）。

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

另外还有：范围专属 AGENTS.md，以及 .omx/ 运行时目录与 HUD 配置。

Agents 与 Skills 的安装位置：

• Prompts：prompts/*.md（user 范围装到 ~/.codex/prompts/，project 范围装到 ./.codex/prompts/）；
• Skills：skills/*/SKILL.md（user 范围装到 ~/.codex/skills/，project 范围装到 ./.codex/skills/）；
• 示例 Agents：architect、planner、executor、debugger、verifier、security-reviewer；
• 示例 Skills：deep-interview、ralplan、team、ralph、plan、cancel。

仓库 README.md 还补充了 AGENTS 合并策略的三态选择器：omx setup --merge-agents（保留既有项目 AGENTS.md 指导，仅在 <!-- OMX:AGENTS:START --> / <!-- OMX:AGENTS:END --> 之间插入或刷新 OMX 生成的段落）、--no-merge-agents（记录显式的非合并选择）、--clear-merge-agents-policy（总是移除记录的选择，且不能与 set 选择器组合）。策略按工作根目录存储（即使是 user 范围），仅在保存的范围有效且匹配时由即时/延迟更新重放，且永远不会成为强制/默认策略。

十二、项目结构：TypeScript 主仓 + Rust 原生侧车

README.tr.md 给出的顶层结构：

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

结合当前仓库实际，可以进一步看到两类关键源码位置：

• TypeScript 主仓：src/cli/ 是命令分发层，src/team/ 是团队运行时（约 96 个文件），src/hooks/ 含 extensibility 插件系统，src/hud/ 是 HUD 渲染/状态，src/mcp/ 是 MCP 服务器（state、memory、code-intel、hermes、trace、wiki 等）；
• Rust crates：crates/omx-sparkshell（侧车，含按语言拆分的 registry：git.rs、python.rs、node_js.rs、rust.rs、go.rs、c_cpp.rs、java_kotlin.rs、ruby.rs、swift.rs、csharp.rs 与 generic_shell.rs）、crates/omx-explore（探索 harness）、crates/omx-mux（tmux 多路复用）、crates/omx-runtime / omx-runtime-core（含 authority、dispatch、engine、mailbox、replay 模块的运行时核心）。

从 crates/omx-sparkshell/src/registry/ 的按语言注册表可以推断：sparkshell 对不同语言的 shell 命令做了分类化识别，配合 redaction.rs 与 threshold.rs 实现输出裁剪与敏感信息处理——这正是"总结长输出"能力的基础。

十三、开发构建与诊断

README.tr.md 给出的开发流程：

git clone <仓库地址>
cd oh-my-codex
npm install
npm run build
npm test

配套的日常运维入口是 omx doctor（诊断安装/运行时）与 omx doctor --team（诊断团队/swarm）。当 omx doctor 全绿但真实执行仍失败时，docs/troubleshooting.md 建议检查 Codex 实际使用的环境：在同一个 shell/profile 中运行 codex login status 与 omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"；确认激活的 ~/.codex（或 CODEX_HOME）带有预期的认证与配置；若依赖本地 OpenAI 兼容代理，确认 config.toml 中包含预期的 openai_base_url，否则代理签发的 key 可能被发往默认端点而返回 401 Unauthorized。

十四、配套文档索引

README.tr.md 末尾列出的配套资料（均已转换为仓库根目录相对路径）是深入使用 OMX 的入口：

• 变更日志：CHANGELOG.md；
• 迁移指南（v0.4.4 之后 mainline）：docs/migration-mainline-post-v0.4.4.md；
• 覆盖率与对等性说明：COVERAGE.md；
• Hook 扩展工作流：docs/hooks-extension.md；
• 安装与贡献细节：CONTRIBUTING.md；
• v0.9.0 版本发布说明：docs/release-notes-0.9.0.md、docs/release-body-0.9.0.md；
• OpenClaw 集成（土耳其语版）：docs/openclaw-integration.tr.md。

结语

OMX 的价值不在于替代 Codex，而在于把 Codex 的日常使用变得有章法：用 AGENTS.md 做编排大脑，用 prompts/skills 固化角色与工作流，用 .omx/ 持久化运行时状态，用团队模式在 tmux 上并行多个 worker，再用 Rust 侧车（sparkshell）提供只读、受限、可总结的 shell 原生检查路径。无论你从 $deep-interview -> $ralplan -> $ultragoal 的推荐链路开始，还是直接 omx --worktree=feat/task --madmax --xhigh 启动一个强会话，这套分层都能让 Codex 从"孤军奋战"变成"有组织地协作"。