Oh My Codex (OMX) 命令与工作流速查表
基于 OMX v0.8.2 官方文档整理，涵盖所有命令、技能关键词、工作流及使用案例。
1. 安装与初始化
# 全局安装
npm install -g oh-my-codex
# 运行设置向导（安装 skills、prompts、MCP 服务器、AGENTS.md）
omx setup
# 检查安装健康状态
omx doctor
# 检查 team 模式的 worker 诊断
omx doctor --team
2. CLI 核心命令
| 命令 | 说明 | 使用案例 |
|---|---|---|
omx | 启动 Codex CLI（tmux 中自动挂载 HUD） | omx — 进入交互式开发环境 |
omx setup | 安装 skills/prompts/MCP/AGENTS.md | omx setup --scope project — 仅在当前项目安装 |
omx doctor | 检查安装状态 | omx doctor --team — 诊断 worker 状态 |
omx ask <provider> | 直接查询 claude/gemini 顾问 | omx ask claude "review this diff" |
omx team | 生成/管理/关闭 tmux 并行 worker | omx team 3:executor "fix all errors" |
omx ralph | 以 Ralph 持久模式启动 Codex | omx ralph — 直到目标验证通过才停止 |
omx status | 显示当前活跃模式和执行状态 | omx status |
omx cancel | 取消活跃的执行模式 | omx cancel — 停止 autopilot/team 等 |
omx reasoning [mode] | 查看或设置推理强度 | omx reasoning xhigh |
omx version | 显示版本号 | omx version |
omx help | 显示帮助信息 | omx help |
3. 启动标志（Launch Flags）
| 标志 | 说明 | 使用案例 |
|---|---|---|
--yolo | Codex yolo 模式 | omx --yolo — 跳过确认直接执行 |
--high / --xhigh | 高/超高推理强度 | omx --xhigh — 复杂架构任务 |
--madmax | ⚠️ 危险：绕过审批和沙箱 | omx --madmax — 仅限可信环境 |
--spark | 使用 Spark 模型（~1.3x 更快） | omx --spark — 提速 team worker |
--madmax-spark | Spark + 绕过审批 | omx --madmax-spark — 极速模式 |
-w, --worktree[=<name>] | 在 git worktree 中运行（隔离环境） | omx -w=feature-auth |
--force | 强制重新安装（覆盖已有文件） | omx setup --force |
--dry-run | 只展示将执行的操作，不实际执行 | omx setup --dry-run |
--verbose | 详细输出，用于调试 | omx --verbose |
--scope <user|project> | 安装范围：全局或项目级 | omx setup --scope user |
💡 最强组合： omx --xhigh --madmax — 超高推理 + 全权限
4. 执行模式（Execution Modes）
4.1 Autopilot — 全自动执行
从想法到交付代码的完整自主循环，自带纠错。
触发关键词： autopilot
内部流程： 扩展（Analyst + Architect）→ 规划（Architect + Critic）→ 执行（Ralph + Ultrawork）→ QA 循环（UltraQA）
# Codex CLI 内
autopilot build a React dashboard
autopilot implement user authentication with OAuth2
autopilot create a REST API for order management
4.2 Ralph — 持久模式
“巨石永不停歇”，持续工作直到 Architect 验证目标达成。
触发关键词： ralph
特点： 无限持久循环 + 自动包含 Ultrawork + 强验证要求
# Codex CLI 内
ralph refactor the API layer
ralph fix all failing tests and ensure 100% pass rate
ralph migrate database schema to v3
# 终端直接启动
omx ralph
4.3 Ultrawork (ulw) — 极限并行
最大化并行度，将子任务分派给多个后台 agent（最多 5+ 并发）。
触发关键词： ulw
# Codex CLI 内
ulw fix these 5 bugs
ulw add input validation to all API endpoints
ulw update all deprecated dependencies
4.4 UltraQA — QA 循环
反复执行 测试 → 验证 → 修复，直到全部通过。
# 通常作为工作流末尾自动触发，也可单独使用
$ultraqa
5. 技能与关键词（Skills & Keywords）
5.1 核心技能
| 关键词/命令 | 说明 | 使用案例 |
|---|---|---|
autopilot | 全自动执行 | autopilot build a login page |
ralph | 持久模式 | ralph refactor the API |
ulw | Ultrawork 并行 | ulw fix these 5 bugs |
$team | tmux Team worker | $team 3:executor build it |
plan | 战略规划（交互式访谈） | plan the auth system |
$ralplan | 共识规划（Planner→Architect→Critic） | $ralplan the API redesign |
5.2 工具技能
| 命令 | 说明 | 使用案例 |
|---|---|---|
$cancel | 取消当前执行模式 | $cancel — 停止 autopilot/ralph 等 |
$note | 写入记事本（抗压缩记忆） | $note remember to update docs |
$hud | HUD 显示控制 | $hud — 查看/配置 HUD |
$omc-doctor | 健康检查 | $omc-doctor — 诊断问题 |
5.3 Agent Prompt 调用
通过 /prompts:name 调用特定角色 agent：
# 架构分析
/prompts:architect "analyze current auth boundaries"
# 代码执行
/prompts:executor "implement input validation in login"
# 搜索/探索
/prompts:explore "find all usages of the deprecated API"
# 代码审查
/prompts:code-reviewer "review the authentication module"
# 安全审查
/prompts:security-reviewer "check for SQL injection vulnerabilities"
# 调试
/prompts:debugger "investigate the memory leak in worker pool"
所有可用 Agent 角色：
- 构建与分析：
explore、planner、architect、executor、debugger、verifier - 审查：
code-reviewer、security-reviewer、performance-reviewer、api-reviewer、style-reviewer - 领域专家：
dependency-expert、test-engineer、git-master、designer、researcher - 产品与协调：
product-manager、ux-researcher、critic、vision
6. Team 命令（tmux 多 Worker 协作）
6.1 基础操作
# 启动 3 个 executor worker 执行任务
omx team 3:executor "fix all TypeScript errors"
# 查看 team 状态
omx team status my-team
# 恢复被中断的 team
omx team resume my-team
# 关闭 team
omx team shutdown my-team
# 强制关闭
omx team shutdown my-team --force
6.2 混合 CLI Provider
# 混合 Codex + Claude + Gemini worker
export OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini
omx team 3:executor "parallel refactoring"
# 全部使用 Gemini worker
export OMX_TEAM_WORKER_CLI=gemini
omx team 2:architect "large-scale architectural review"
# 指定模型
export OMX_TEAM_WORKER_LAUNCH_ARGS="--model gemini-2.0-flash-exp"
omx team 1:executor "experimental feature"
6.3 Team CLI API（程序化操作）
# 创建任务
omx team api create-task --input '{"team_name":"my-team","subject":"Fix bug","description":"..."}' --json
# 认领任务（版本安全）
omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json
# 转换任务状态
omx team api transition-task-status --input '{"team_name":"my-team","task_id":"1","from":"in_progress","to":"completed","claim_token":""}' --json
6.4 Worktree 隔离
# 在独立 worktree 中启动 team，防止 worker 间文件冲突
omx team 4:executor "feature work" --worktree=feature-branch
6.5 动态扩缩容
# 启用动态扩缩容
export OMX_TEAM_SCALING_ENABLED=1
omx team 2:executor "task"
# 运行中手动 scale_up / scale_down
6.6 Team 组合模板
| 场景 | 组合 | 说明 |
|---|---|---|
| 功能开发 | analyst→planner→executor→test-engineer→verifier | 完整开发流水线 |
| Bug 修复 | explore→debugger→executor→verifier | 定位→调试→修复→验证 |
7. Advisor（Ask）命令
# 简单查询
omx ask claude "review this diff"
omx ask gemini "brainstorm alternatives for the auth system"
# 指定角色查询
omx ask claude --agent-prompt executor "implement feature X with tests"
omx ask gemini --agent-prompt planner "draft a rollout plan for v0.9"
# 简写形式
omx ask claude -p "summarize the recent changes"
omx ask gemini --prompt "check this regex for errors"
8. 规划系统
8.1 plan — 交互式规划
# Codex CLI 内
plan the migration strategy
plan the auth system redesign
8.2 ralplan — 共识规划（RALPLAN-DR）
流程：Planner → Architect → Critic → 结构化共识总结
# Codex CLI 内
$ralplan the API redesign
$ralplan database migration to PostgreSQL
# 等同于
$plan --consensus
# 高风险工作使用 --deliberate 模式
$plan --consensus --deliberate # 安全迁移、破坏性操作、公共 API 变更
9. Hooks & 扩展
# 初始化 hook 插件
omx hooks init
# 查看已安装 hook 状态
omx hooks status
# 验证 hook 插件实现
omx hooks validate
# 初始化 tmux prompt 注入 workaround
omx tmux-hook init
启用插件： export OMX_HOOK_PLUGINS=1
10. 通知系统（Notifications）
10.1 快速配置
# Telegram
export OMX_TELEGRAM_BOT_TOKEN=xxx
export OMX_TELEGRAM_CHAT_ID=xxx
# Discord（Webhook）
export OMX_DISCORD_WEBHOOK_URL=xxx
# Slack
export OMX_SLACK_WEBHOOK_URL=xxx
# 写入配置文件
omx setup
10.2 支持平台
| 平台 | 配置方式 | 特点 |
|---|---|---|
| Telegram | botToken + chatId | 支持 Markdown/HTML 解析，支持回复注入 |
| Discord Webhook | webhookUrl | 单向告警，支持自定义用户名和 @提及 |
| Discord Bot API | botToken + channelId | 双向通信，需 bot 权限 |
| Slack | webhookUrl | 支持自定义频道和 @提及 |
| 通用 Webhook | url | POST/PUT JSON，支持自定义 headers |
| OpenClaw | openclaw.enabled: true | 生产级网关，可编程 hook 编排 |
10.3 事件类型
| 事件 | 触发时机 |
|---|---|
session-start | Codex 会话启动 |
session-stop | 会话停止（完成或用户中断） |
session-end | 会话退出 |
session-idle | 会话空闲（等待输入） |
ask-user-question | Agent 向用户提问 |
10.4 通知详细度
| 级别 | 行为 |
|---|---|
verbose | 所有文本和工具调用输出 |
agent | 每次 agent 调用事件 |
session | 启动/空闲/停止/结束（默认） |
minimal | 仅启动/停止/结束 |
10.5 回复注入（Reply Injection）
从 Telegram/Discord/Slack 直接回复消息，注入文本到 Codex 会话。需要 tmux 和授权用户 ID。
配置项：enabled、pollIntervalMs、maxMessageLength、rateLimitPerMinute
11. 推荐工作流（4 大经典模式）
11.1 🏗️ Full-Auto from PRD — 大功能开发
流程： $ralplan → $team → $ralph
# 1. 共识规划：收集需求，Planner+Architect+Critic 三方共识
$ralplan implement user dashboard with analytics
# 2. Team 并行构建
$team 4:executor "implement the dashboard plan"
# 3. Ralph 持久执行直到全部验证通过
ralph finish and verify all dashboard features
适用场景： 需要先规划再实施的大型功能
11.2 ⚡ No-Brainer — 任务明确直接干
流程： $autopilot → $ultrawork → $ralph
# 1. Autopilot 全自动接管
autopilot build a user settings page
# 2. Ultrawork 并行化子任务（autopilot 内部自动触发）
# 3. Ralph 持久直到验证通过（autopilot 内部自动触发）
适用场景： 需求清晰、不需要额外规划的任务
11.3 🐛 Fix / Debugging — 修 Bug
流程： $plan → $ralph → $ultraqa
# 1. Plan 调查问题，制定修复策略
plan investigate the login timeout issue
# 2. Ralph 实施修复，持续直到完成
ralph fix the login timeout bug
# 3. UltraQA 循环测试→验证→修复，直到全部通过
$ultraqa
适用场景： Bug 修复、错误排查
11.4 🔀 Parallel Issues — 并行处理多个 Issue
流程： omx team (architect) → omx team (workers) → $ralplan → $ralph + $ultrawork → $ultraqa
# 1. Architect worker 分析所有 issue，起草总体计划
omx team 2:architect "analyze issues #12 #15 #18 and draft unified plan"
# 2. Worker 在独立 worktree 并行执行，各自提交 PR
omx team 3:executor "implement fixes per plan" --worktree=fix-batch
# 3. 合并 PR 后，用 ralplan 解决冲突
$ralplan resolve merge conflicts safely
# 4. Ralph + Ultrawork 收尾
ralph finish remaining work
# 5. UltraQA 确保全部测试通过
$ultraqa
适用场景： 同时处理多个 issue/ticket
12. MCP 工具一览
状态与运行时
state_read/state_write/state_clear— 管理执行模式状态
记事本（Notepad）
notepad_read— 读取记事本notepad_write_priority— 优先级内容（始终注入上下文）notepad_write_working— 工作内容（7 天后自动清理）notepad_write_manual— 手动内容（永不清理）
代码智能（LSP）
lsp_hover/lsp_goto_definition/lsp_find_references/lsp_diagnostics/lsp_rename
AST 结构化操作
ast_grep_search/ast_grep_replace— 结构化搜索与重构
其他
python_repl— 持久化 Python REPL 环境
MCP 安全加固
# 限制 workingDirectory 白名单
export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another"
13. 状态与记忆系统
记事本（.omx/notepad.md）
| 类型 | 行为 | 用途 |
|---|---|---|
| Priority | 始终注入上下文 | 关键信息、决策记录 |
| Working | 7 天后自动清理 | 当前任务临时笔记 |
| Manual | 永不清理 | 长期参考资料 |
项目记忆（.omx/project-memory.json）
存储技术栈、编码规范、架构指令等项目级知识。
状态文件
.omx/state/— 模式状态文件.omx/logs/— 审计日志.omx/plans/— 规划文档
14. 模型路由策略
| 复杂度 | 模型 | 适用场景 |
|---|---|---|
| 简单 | Spark | 查询、格式化、简单文档 |
| 标准 | Default | 实现、测试、重构 |
| 复杂 | xhigh reasoning | 架构设计、深度调试、规划 |
15. 关键环境变量速查
| 变量 | 用途 |
|---|---|
OMX_TEAM_WORKER_CLI | Worker CLI 类型：auto/codex/claude/gemini |
OMX_TEAM_WORKER_CLI_MAP | 逐 worker 指定 CLI（如 codex,claude,gemini） |
OMX_TEAM_WORKER_LAUNCH_ARGS | Worker 启动参数（如指定模型） |
OMX_TEAM_SCALING_ENABLED | 启用动态扩缩容（设为 1） |
OMX_OPENCLAW | 启用 OpenClaw（设为 1） |
OMX_OPENCLAW_COMMAND | 启用 OpenClaw 命令网关（设为 1） |
OMX_MCP_WORKDIR_ROOTS | MCP workingDirectory 白名单 |
OMX_HOOK_PLUGINS | 启用 hook 插件（设为 1） |
OMX_TELEGRAM_BOT_TOKEN | Telegram Bot Token |
OMX_TELEGRAM_CHAT_ID | Telegram Chat ID |
OMX_DISCORD_WEBHOOK_URL | Discord Webhook URL |
OMX_DISCORD_NOTIFIER_BOT_TOKEN | Discord Bot Token |
OMX_DISCORD_NOTIFIER_CHANNEL | Discord 频道 ID |
OMX_DISCORD_MENTION | Discord @提及目标 |
OMX_SLACK_WEBHOOK_URL | Slack Webhook URL |
OMX_SLACK_MENTION | Slack @提及目标 |
