【omx】oh-my-codex 技术教程：构建多智能体协作工作流

用 oh-my-codex 构建多智能体协作工作流

让 Codex 不再孤单：用 oh-my-codex 打造你的 AI 智能体编排层

前言

如果你已经在使用 OpenAI Codex CLI，但感觉缺少一些东西------比如更好的工作流组织、可复用的智能体角色、或者持久化的项目状态管理------那么 oh-my-codex（简称 OMX）正是为你设计的。

OMX 不是要替换 Codex，而是在 Codex 之上构建一层更强大的工作流编排系统。它提供了 30+ 预定义智能体角色、40+ 技能模块、以及基于 tmux 的多智能体并行执行能力，让你能够像指挥一支工程师团队一样完成复杂项目。

本文将带你从零开始搭建 OMX 环境，并通过实战示例展示如何使用它的核心功能。

一、快速开始

1.1 环境要求

Node.js 20+
macOS 或 Linux（Windows 用户建议使用 WSL2）
tmux（用于多智能体并行执行）
OpenAI Codex CLI 已安装并配置好 API Key

1.2 安装步骤

bash 复制代码

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

# 2. 运行初始化设置
omx setup

omx setup 会自动完成以下工作：

创建 .omx/ 目录用于存储项目状态
安装 30 个智能体提示词到 ~/.codex/prompts/
安装 40 个技能模块到 ~/.codex/skills/
生成项目根目录的 AGENTS.md 编排指南
配置 Codex CLI 的 hooks 和 MCP 服务器

1.3 验证安装

bash 复制代码

omx doctor

预期输出应显示所有检查项通过：

复制代码

[OK] Codex CLI: installed
[OK] Node.js: v20+
[OK] Prompts: 30 agent prompts installed
[OK] Skills: 40 skills installed
[OK] AGENTS.md: found in project root

二、核心概念

2.1 智能体角色（Agents）

OMX 预定义了 30 种专业智能体角色，每种都有明确的职责边界。常用角色包括：

角色	用途
`$architect`	代码架构分析，提供文件级引用和权衡分析
`$security-reviewer`	OWASP Top 10 安全审查，提供修复代码示例
`$explore`	代码库结构搜索和模式发现
`$autopilot`	全自主开发流水线（需求→设计→实现→测试）
`$deep-interview`	需求澄清，明确边界和非目标
`$ralplan`	制定和评审实现计划
`$ralph`	持久化执行直到完成
`$team`	协调多智能体并行执行

2.2 技能（Skills）

40+ 预置技能模块，覆盖常见开发场景：

代码生成和重构
测试用例生成
文档编写
Git 工作流管理
依赖分析
性能优化

2.3 项目状态管理

OMX 在项目根目录创建 .omx/ 目录，存储：

plans/ - 实现计划
logs/ - 执行日志
memory/ - 项目记忆
wiki/ - 本地知识库
state/ - 运行时状态

2.4 AGENTS.md 编排文件

每个项目生成的 AGENTS.md 是智能体协作的"大脑"，包含：

智能体委派规则
模型路由策略
团队组合建议
验证协议

三、实战工作流

3.1 标准四步工作流

OMX 推荐的标准工作流包含四个阶段：

bash 复制代码

# 步骤 1: 需求澄清
$deep-interview "实现用户认证模块，支持 JWT 和 OAuth2"

# 步骤 2: 方案评审
$ralplan "评审认证方案，分析安全 tradeoffs"

# 步骤 3: 执行完成
$ralph "按照批准的方案实现认证模块"

# 步骤 4: 并行执行（可选，适用于大型任务）
$team 3:executor "并行实现登录、注册、令牌刷新三个子模块"

3.2 实战示例：构建 REST API

让我们通过一个完整示例展示 OMX 的能力。假设我们要构建一个任务管理 REST API。

第一步：启动 OMX 会话

bash 复制代码

cd ~/projects/task-api
omx --madmax --high

--madmax --high 启用高性能模式，适合复杂任务。

第二步：需求分析

复制代码

$architect "分析任务管理 API 的数据模型和端点设计"

智能体会返回：

数据模型设计（Task、User、Project 等）
REST 端点规划（CRUD 操作）
技术栈建议（Express + TypeScript + PostgreSQL）
文件结构和依赖关系

第三步：全自主开发

复制代码

$autopilot "构建任务管理 REST API，包含用户认证、任务 CRUD、项目协作功能"

$autopilot 会自动执行：

需求细化和验收标准定义
技术设计和 API 规范
并行代码实现
测试用例生成和执行
多轮验证和修复

第四步：代码审查

复制代码

$security-reviewer "审查所有 API 端点的安全漏洞"

输出包括：

SQL 注入风险评估
认证授权检查
输入验证建议
修复代码示例

3.3 多智能体团队协作

对于大型项目，OMX 支持启动多智能体团队并行工作：

bash 复制代码

# 启动 5 人团队
omx team 5:executor "实现任务管理系统的完整功能"

# 查看团队状态
omx team status "task-management-system"

# 恢复中断的团队
omx team resume "task-management-system"

# 关闭团队并清理资源
omx team shutdown "task-management-system"

团队架构：

复制代码

┌─────────────────────────────────────────────────────────┐
│ tmux Session "omx-team"                                 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│ │ Leader   │ │ Worker 1 │ │ Worker 2 │ │ Worker N │   │
│ │ (协调者)  │ │ (codex)  │ │ (codex)  │ │ (claude) │   │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘   │
│        │            │            │            │        │
│        └────────────┴────────────┴────────────┘        │
│                        │                                │
│            ┌───────────┴───────────┐                   │
│            │  共享任务队列          │                   │
│            │  (持久化状态)          │                   │
│            └───────────────────────┘                   │
└─────────────────────────────────────────────────────────┘

四、高级功能

4.1 MCP 服务器集成

OMX 配置了 4 个 MCP（Model Context Protocol）服务器，提供持久化存储和上下文管理：

toml 复制代码

# ~/.codex/config.toml
[mcp_servers.omx_state]
command = "omx"
args = ["mcp", "state"]

[mcp_servers.omx_memory]
command = "omx"
args = ["mcp", "memory"]

智能体可以通过 MCP 工具访问：

state_read - 读取当前模式状态
project_memory_read - 读取项目上下文
notepad_write_working - 保存进度笔记

4.2 Wiki 知识库

OMX 支持本地 Markdown 优先的知识库：

bash 复制代码

# 列出所有 wiki 条目
omx wiki list --json

# 查询相关知识
omx wiki query --input '{"query":"session lifecycle"}' --json

# 检查 wiki 健康度
omx wiki lint --json

4.3 探索模式

只读模式下的代码库探索：

bash 复制代码

# 查找特定模式
omx explore --prompt "找出所有数据库查询模式"

# 检查 Git 状态
omx sparkshell git status

# 查看 tmux 面板输出
omx sparkshell --tmux-pane %12 --tail-lines 400

4.4 监控和调试

bash 复制代码

# 查看当前模式
omx status

# 取消活跃模式
omx cancel

# 实时监控（HUD 模式）
omx hud --watch

# 健康检查
omx doctor

五、最佳实践

5.1 智能体选择指南

场景	推荐智能体
需求不明确	`$deep-interview`
技术方案设计	`$architect` + `$ralplan`
小型任务	`$ralph`
大型项目	`$team N:executor`
全自主开发	`$autopilot`
代码审查	`$security-reviewer`

5.2 项目组织建议

复制代码

project-root/
├── .omx/              # OMX 状态和配置
│   ├── plans/         # 实现计划
│   ├── logs/          # 执行日志
│   ├── memory/        # 项目记忆
│   └── wiki/          # 知识库
├── AGENTS.md          # 智能体编排指南（自动生成）
├── .codex/            # Codex CLI 配置
│   ├── hooks.json     # 原生 hooks
│   └── config.toml    # 配置文件
└── src/               # 项目代码

5.3 性能优化

使用 --madmax --high 启动复杂任务
避免在 Intel Mac 上同时启动过多并发进程（可能触发 Gatekeeper 验证）
WSL2 用户在 Windows 上获得更好的 tmux 体验
定期运行 omx wiki refresh 更新知识库索引

六、常见问题

Q1: Slash 命令不出现？

bash 复制代码

omx setup --force  # 重新安装提示词

Q2: MCP 服务器连接失败？

检查 ~/.codex/config.toml 中 [mcp_servers] 配置是否正确。

Q3: 团队模式在 Windows 上异常？

建议使用 WSL2 或降低并发数。

Q4: 如何自定义智能体？

编辑 ~/.codex/prompts/ 下的提示词文件，或创建新的技能模块。

七、总结

oh-my-codex 为 Codex CLI 用户提供了一个强大的编排层，核心价值在于：

可复用的工作流 - 30+ 智能体角色和 40+ 技能模块开箱即用
持久化状态 - .omx/ 目录保存计划、日志和记忆
并行执行 - tmux 支持的多智能体团队协作
项目感知 - AGENTS.md 提供上下文感知的智能体路由
生态集成 - MCP 服务器、Wiki 知识库、监控工具

如果你已经在使用 Codex 并想要更高效的工作流，OMX 值得尝试。