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

📝

一、项目简介ohmycodex（OMX）是一个构建在 OpenAI Codex CLI1 之上的工一、项目简介 ohmycodex（OMX）是一个构建在 OpenAI Codex CLI1 之上的工作流编排层（Workflow Orchestratio

原文链接：https://mp.weixin.qq.com/s/ADA6_xuWcttrauEdK0UBMA

一、项目简介oh-my-codex（OMX）是一个构建在 OpenAI Codex CLI[1] 之上的工

一、项目简介

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 负责提供更好的任务路由、工作流和运行时管理。

二、解决什么问题

痛点

OMX 的解法

每次使用 Codex 都要手动写大量 prompt

提供标准化的技能库（40个技能），通过 $skill-name 一键触发

复杂任务没有标准化流程

提供从需求澄清 → 计划 → 执行 → 验证的完整工作流

多智能体并行协作复杂
$team
模式一键启动 tmux 多 Agent 并行工作流

会话间上下文丢失
.omx/
目录持久化计划、日志、内存、状态

Codex 角色不明确，执行质量不稳定

提供 30 个专业角色 prompt（architect、debugger、executor 等）

大任务执行到一半就停止
$ralph
持久化完成循环，强制推进到真正完成

三、环境要求

依赖

版本要求

备注

Node.js

= 20

必须

OpenAI Codex CLI

最新
npm install -g @openai/codex
OpenAI API Key

—

需要配置认证

tmux

任意版本

macOS/Linux 下 Team 模式必须

psmux

任意版本

Windows 原生 Team 模式

四、安装与初始化

方式一：推荐（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 的推荐工作流分为四步：

1	`$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）关键字一览

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

触发关键字

技能

用途
$ralph
/ "don't stop"
$ralph
持久完成循环，强制推进到验证完成
$deep-interview
/ "interview me"
$deep-interview
Socratic 需求澄清，Ouroboros 模式
$ralplan
/ "consensus plan"
$ralplan
共识规划，结构化 deliberation
$team
/ "swarm"
$team
多 Agent 协同并行执行
$autopilot
/ "build me"
$autopilot
全自动流水��：需求 → 设计 → 实现 → QA
$ultrawork
/ "parallel"
$ultrawork
并行多 Agent 执行
$ultraqa``$ultraqa
QA 循环工作流
$analyze
/ "investigate"
$analyze
深度代码分析
$tdd
/ "test first"
$tdd
测试驱动开发流程
$code-review``$code-review
代码审查
$security-review``$security-review
安全审计（OWASP Top 10）
$build-fix
/ "fix build"
$build-fix
修复构建/类型错误
$web-clone
/ "clone site"
$web-clone
网站克隆流水线
$ecomode
/ "budget"
$ecomode
节省 token 的精简模式

5.4 Agent 角色系统

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

复杂度

适用角色

低
explore
、style-reviewer、writer

中
executor
、debugger、test-engineer

高
architect
、critic

`# 在 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 流水线：

1	`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 迭代日志`

六、使用场景

场景

推荐做法

功能需求不清晰，想先澄清边界
$deep-interview "..."
需求清晰，想在实现前制定计划和权衡
$ralplan "..."
大型功能开发，多个子任务可并行
$team N:executor "..."
一个任务需要持续推进直到完成/验证通过
$ralph "..."
从零构建一个新功能/应用
$autopilot "build me ..."
代码审查
$code-review
安全审计
$security-review
修复 TypeScript 类型错误或构建失败
$build-fix
自动化研究/优化任务
omx autoresearch missions/<mission-dir>
只需查看仓库结构，不需要编辑
omx explore --prompt "..."

七、完整使用示例

示例 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：并行修复测试

1
2
3

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

示例 3：代码安全审查

1
2
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 演示

1 2	`chmod +x scripts/demo-team-e2e.sh ./scripts/demo-team-e2e.sh`

八、常见问题与解决方案

问题 1：Codex CLI not found

1	`Error: command not found: codex`

解决：

1	`npm install -g @openai/codex`

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

解决：

1	`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]

如果缺失，重新运行：

1	`omx setup`

问题 4：`omx doctor` 显示 warnings

1 2	`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：

平台

命令

macOS
brew install tmux
Ubuntu/Debian
sudo apt install tmux
Fedora
sudo dnf install tmux
Arch
sudo pacman -S tmux
Windows
winget install psmux
Windows (WSL2)
sudo apt install tmux

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

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

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

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

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

1 2	`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 结果：

场景

基线

最优结果

提升

Kaggle 表格 ML (AUC)

0.9458

0.9977

+0.0519

高维 Bayes 优化

2.833

4.760

+1.927

自适应排序优化

2.120

9.411

+7.291

潜在子空间发现

3.702

4.176

+0.474

十一、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

本文转载自微信公众号，如有侵权请联系删除。