oh-my-codex (OMX) 项目完整使用指南

原创 Ranger 2026年4月8日 08:40

一、项目简介#

oh-my-codex（OMX） 是一个构建在 OpenAI Codex CLI ^[1] 之上的 工作流编排层（Workflow Orchestration Layer） 。

它的定位类似于 oh-my-zsh 之于 zsh ——不替换底层工具，而是在其上提供更强大的工作流、角色系统、技能库和状态管理能力，让 Codex CLI 更好用、更强大、更适合复杂的日常开发任务。

核心概念#

┌─────────────────────────────────────┐
│              你的项目               │
├─────────────────────────────────────┤
│        oh-my-codex (OMX)            │  ← 工作流层：角色 / 技能 / 状态 / 编排
├─────────────────────────────────────┤
│        OpenAI Codex CLI             │  ← 执行引擎（不被替换）
├─────────────────────────────────────┤
│        OpenAI API                   │
└─────────────────────────────────────┘

Codex 负责实际的 Agent 执行； OMX 负责提供更好的任务路由、工作流和运行时管理。

二、解决什么问题#

三、环境要求#

四、安装与初始化#

方式一：推荐（npm 全局安装）#

# 安装 Codex CLI 和 OMX
npm install -g @openai/codex oh-my-codex

# 初始化 OMX（安装 prompts、skills、配置 Codex CLI）
omx setup

# 验证安装是否成功
omx doctor

方式二：从源码安装#

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

# 初始化
omx setup

安装验证#

执行 omx doctor 后，正常输出应如下：

oh-my-codex doctor
==================

  [OK] Codex CLI: installed
  [OK] Node.js: v20+
  [OK] Codex home: ~/.codex
  [OK] Config: config.toml has OMX entries
  [OK] Prompts: 30 agent prompts installed
  [OK] Skills: 40 skills installed
  [OK] AGENTS.md: found in project root
  [OK] State dir: .omx/state
  [OK] MCP Servers: 4 servers configured (OMX present)

Results: 9 passed, 0 warnings, 0 failed

五、使用方式#

5.1 启动 OMX#

# 推荐方式：以最强配置启动
omx --madmax --high

# 普通启动
omx

--madmax 启用最大上下文和能力， --high 提升推理强度。

5.2 核心工作流（推荐路径）#

OMX 的推荐工作流分为四步：

$deep-interview → $ralplan → $ralph / $team

在 Codex 会话中依次执行：

# 第一步：澄清需求（当任务边界不清晰时）
$deep-interview "clarify the authentication change"

# 第二步：制定并审批计划
$ralplan "approve the auth plan and review tradeoffs"

# 第三步A：单 Agent 持久完成（适合中小任务）
$ralph "carry the approved plan to completion"

# 第三步B：多 Agent 并行执行（适合大型任务）
$team 3:executor "execute the approved plan in parallel"

5.3 技能（Skills）关键字一览#

技能通过关键字自动触发，无需额外确认：

5.4 Agent 角色系统#

30 个专业角色 prompt 内置安装按复杂度分类：

# 在 Codex 会话中直接调用
$architect "analyze the authentication module"
$debugger "root cause the memory leak in worker.ts"
$explore "find all database query patterns"
$security-reviewer "review the API endpoints"

5.5 Team 模式（多 Agent 并行）#

Team 模式通过 tmux 启动多个并行工作 Agent，适合大型任务：

# 启动 3 个 executor Agent 并行工作
omx team 3:executor "fix the failing tests with verification"

# 启动 6 个混合 Agent（Codex + Claude）
export OMX_TEAM_WORKER_CLI_MAP=codex,codex,codex,claude,claude,claude
omx team 6:executor "e2e team demo"

# Team 生命周期管理
omx team status <team-name>   # 查看状态
omx team resume <team-name>   # 恢复中断的 team
omx team shutdown <team-name> # 关闭 team

Team 流水线：

team-plan → team-prd → team-exec → team-verify → team-fix (loop)

5.6 常用 CLI 命令#

omx setup               # 安装/重新安装所有组件
omx setup --force       # 强制覆盖已有配置
omx doctor              # 检查安装状态
omx version             # 查看版本信息
omx status              # 查看当前活跃的模式
omx cancel              # 取消当前活跃模式
omx hud --watch         # 实时监控 HUD（状态面板）

# 只读仓库探查（不执行编辑操作）
omx explore --prompt "find where team state is written"

# 安全 shell 执行（有限白名单命令，适合验证/检查）
omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400

5.7 状态持久化（.omx/ 目录）#

OMX 在项目根目录下的 .omx/ 中保存所有运行时状态：

.omx/
├── state/               # 当前模式状态（ralph / team / autopilot 等）
├── notepad.md           # 会话笔记
├── project-memory.json  # 跨会话项目记忆
├── plans/               # PRD 和测试规格文档
│   ├── prd-*.md
│   └── test-spec-*.md
└── logs/                # 运行日志
    └── autoresearch/    # autoresearch 迭代日志

六、使用场景#

七、完整使用示例#

示例 1：全流程开发一个认证模块#

# 1. 启动 OMX
omx --madmax --high

# 在 Codex 会话中：

# 2. 澄清需求
$deep-interview "我想给 API 添加 JWT 认证，请帮我明确边界和非目标"

# 3. 审批计划
$ralplan "approve the safest JWT implementation path"

# 4. 执行（小任务用 ralph，大任务用 team）
$ralph "carry the approved plan to completion"

示例 2：并行修复测试#

omx --madmax --high
# 在会话中：
$team 3:executor "fix all failing tests with verification"

示例 3：代码安全审查#

omx
# 在会话中：
$security-review "review all API endpoints in src/routes/"

示例 4：Autoresearch 优化任务#

# 运行内置的 Bayesian 优化 showcase
omx autoresearch missions/noisy-bayesopt-highdim

# 查看结果
RUN_ID=$(find .omx/logs/autoresearch -maxdepth 1 -mindepth 1 -type d | sort | tail -1 | xargs basename)
cat .omx/logs/autoresearch/$RUN_ID/iteration-ledger.json

示例 5：一键运行 E2E Team 演示#

chmod +x scripts/demo-team-e2e.sh
./scripts/demo-team-e2e.sh

八、常见问题与解决方案#

问题 1：Codex CLI not found#

Error: command not found: codex

解决：

npm install -g @openai/codex

问题 2：技能/slash 命令没有出现#

解决：

omx setup --force   # 强制重新安装 prompts 和 skills

问题 3：MCP Servers 未连接#

解决： 检查 ~/.codex/config.toml 中是否包含以下四个 MCP server 条目：

• • [mcp_servers.omx_state]
• • [mcp_servers.omx_memory]
• • [mcp_servers.omx_code_intel]
• • [mcp_servers.omx_trace]

如果缺失，重新运行：

omx setup

问题 4：omx doctor 显示 warnings#

omx setup   # 安装缺失的组件
omx doctor  # 再次检查

问题 5：Intel Mac 启动时 CPU 飙升（syspolicyd / trustd）#

启动 omx --madmax --high 时，macOS Gatekeeper 会对大量并发进程进行验证，导致 CPU 占用高。

解决方案（任选一种）：

# 方法 1：移除隔离属性
xattr -dr com.apple.quarantine $(which omx)

# 方法 2：在 macOS 安全设置中将终端 App 加入 Developer Tools 白名单

# 方法 3：降低并发（不使用 --madmax --high）
omx

问题 6：Team 模式无法启动（找不到 tmux）#

解决： 安装对应平台的 tmux：

问题 7：$ralph 执行前 OMX 要求先生成计划#

OMX 有一个 ralplan-first 执行门：当 ralph 模式激活时，需要先存在 .omx/plans/prd-*.md 和 .omx/plans/test-spec-*.md 才能开始实现。

解决： 先运行 $ralplan "..." 完成计划，再运行 $ralph 。

问题 8：会话中断后 Team 状态丢失#

Team 的状态保存在 .omx/ 目录中，可以恢复：

omx team status <team-name>   # 查看状态
omx team resume <team-name>   # 恢复中断的 team

九、项目架构概览#

oh-my-codex/
├── src/              # TypeScript 核心源码
│   ├── cli/          # CLI 命令实现（omx 入口）
│   ├── team/         # Team 模式运行时
│   ├── state/        # 状态管理
│   ├── hooks/        # Notify-hook / explore / sparkshell
│   └── runtime/      # 与 Rust 运行时的 bridge
├── crates/           # Rust 核心组件（omx-runtime, omx-explore-harness）
├── prompts/          # 30 个 Agent 角色 prompt
├── skills/           # 40 个 workflow 技能
├── templates/        # AGENTS.md 模板
├── missions/         # Autoresearch 任务定义
├── playground/       # Autoresearch 演示场景
├── docs/             # 文档
└── .omx/             # (运行时生成) 状态、计划、日志

十、进阶功能：Autoresearch#

OMX 内置了一个 自动化研究/优化引擎 ，可以对指定任务进行多轮迭代优化：

# 列出所有内置任务
./scripts/run-autoresearch-showcase.sh --list

# 运行单个任务
./scripts/run-autoresearch-showcase.sh bayesopt

已验证的 Autoresearch 结果：

十一、Lore Commit 协议#

OMX 推荐一套结构化的 commit message 格式，用于记录决策而非变更：

<意图行：为什么改，而不是改了什么>

<背景说明：约束条件、方案选择理由>

Constraint: <影响决策的外部约束>
Rejected: <被否定的方案> | <否定原因>
Confidence: <low|medium|high>
Scope-risk: <narrow|moderate|broad>
Directive: <对未来修改者的前瞻性警告>
Tested: <验证了什么>
Not-tested: <已知的验证空白>

十二、相关资源#

• • 📖 官方网站 ^[2]
• • 📦 npm 包 ^[3]
• • 💬 Discord 社区 ^[4]
• • 🐛 问题反馈 ^[5]
• • 🤝 贡献指南 ^[6]
• • 📋 更新日志 ^[7]

引用链接

[1] OpenAI Codex CLI: https://github.com/openai/codex
[2] 官方网站: https://yeachan-heo.github.io/oh-my-codex-website/
[3] npm 包: https://www.npmjs.com/package/oh-my-codex
[4] Discord 社区: https://discord.gg/PUwSMR9XNk
[5] 问题反馈: https://github.com/Yeachan-Heo/oh-my-codex/issues
[6] 贡献指南: https://github.com/Yeachan-Heo/oh-my-codex/blob/main/CONTRIBUTING.md
[7] 更新日志: https://github.com/Yeachan-Heo/oh-my-codex/blob/main/CHANGELOG.md

继续滑动看下一个

Ranger Ramblings

向上滑动看下一个

闪记

复制 LaTeX 公式