OMX使用

OMX 从入门到进阶：Codex 用户实战指南

适用读者：已经会使用 Codex CLI，希望借助 OMX 获得更稳定的规划、执行、多 Agent 协作和任务恢复能力。

验证基线：oh-my-codex v0.18.6，macOS，2026-07-16。OMX 更新较快；执行关键操作前，请用 omx version、omx help 和 omx list 核对当前版本。

1. 十分钟快速上手
2. OMX 到底是什么
3. 安装、升级与健康检查
4. 新项目如何使用 OMX
5. 已有项目如何接入 OMX
6. 推荐的日常工作流
7. 如何选择普通 Codex、Skill、子 Agent 和 Team
8. 四个完整实战案例
9. 权限、安全和停止条件
10. 会话、状态和任务恢复
11. 常见问题与排错
12. 高频命令速查
13. 可复制的提示词模板
14. 推荐习惯与反模式

1. 十分钟快速上手

如果你已经安装并登录过 Codex，第一次使用 OMX 可以按下面做。

1.1 检查现有环境

codex --version
codex login status
node --version
omx version

OMX v0.18.6 要求 Node.js 20+。Codex 可以由 Homebrew、npm 或其他受支持方式安装；只要同一终端里的 codex 可用且已认证即可。

1.2 安装或更新 OMX

npm install -g oh-my-codex
omx setup
omx doctor

如果已经安装 OMX，希望检查新版本并刷新配置：

omx update

1.3 做一次真实调用测试

omx doctor 只检查本地安装形态，不能证明模型认证和网络一定可用。进入准备使用的项目目录后运行：

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

预期最终回复为：

OMX-EXEC-OK

1.4 启动 OMX

安全、稳妥的首次启动方式：

omx --high

如果不希望 OMX 管理 tmux/HUD：

omx --direct --high

进入会话后，可先输入：

$deep-interview "我要为现有 Web 项目增加用户登录功能。请先澄清目标、范围、兼容要求和验收标准，不要立即修改代码。"

需求明确后：

$ralplan "基于已经确认的需求，制定可实施、可验证的方案，并明确风险和取舍。"

批准计划后：

$ultragoal "将已批准的计划转换成持久目标，逐项实施；每项目标必须有验证证据，所有要求满足后再结束。"

这就是当前版本推荐的主线：

$deep-interview -> $ralplan -> $ultragoal

2. OMX 到底是什么

OMX 不会替代 Codex。可以把它理解成包在 Codex 外面的工作流和运行时增强层：

Codex：理解需求、读写代码、运行命令和测试。
OMX Skill：把常见工作方式封装成可复用流程，例如规划、持续执行、代码审查。
Agent：针对探索、架构、调试、测试、设计等任务的专业角色。
AGENTS.md：告诉 Codex 在当前目录及子目录中应遵循哪些项目规则。
.omx/：保存计划、日志、状态、记忆和持久任务数据。
tmux/worktree：为长时间运行和多 Agent 团队提供可恢复、相互隔离的执行环境。

2.1 你得到的主要提升

与“打开 Codex 后一个功能一个功能地做”相比，OMX 主要改善：

先澄清再实现：减少需求没说清就改代码。
计划可审批：先确定接口、边界、测试和迁移方案。
长任务可持续：任务状态不只存在于一轮对话中。
并行工作有边界：大任务可以交给多个隔离 worker。
完成必须有证据：强调测试、构建、审查和验收结果。
项目规则可复用：不用每次重新解释目录结构和开发约定。

2.2 OMX 不适合什么

以下情况通常不需要启动重型工作流：

解释一小段代码。
查找一个符号或配置位置。
修改一处明确的文案。
回答不需要改仓库的简单技术问题。
无法安全拆分、强依赖同一文件的小任务。

这些情况直接在 Codex 中描述任务即可。不要为了“用了 OMX”而强行启动 Team。

3. 安装、升级与健康检查

3.1 前置要求

Node.js 20+
已安装且可登录的 Codex CLI
macOS/Linux 上如需推荐的 Team 运行时，应安装 tmux
Windows 推荐 WSL2 + tmux；原生 Windows 的 Team 路径支持程度相对较低

macOS 安装 tmux：

brew install tmux

Ubuntu/Debian：

sudo apt install tmux

3.2 已经安装 Codex 的用户

先确定 Codex 来源：

command -v codex
codex --version

然后只安装 OMX：

npm install -g oh-my-codex
omx setup

注意： 如果 codex 由 Homebrew 管理，不要再执行组合安装 npm install -g @openai/codex oh-my-codex。两个包可能争用同一个 codex 可执行文件并产生 EEXIST。

3.3 尚未安装 Codex 的用户

如果决定全部由 npm 管理，请分开安装：

npm install -g @openai/codex
npm install -g oh-my-codex
omx setup
codex login

3.4 `omx setup` 的作用

omx setup 用于安装或刷新 OMX 需要的 skills、prompts、配置、hooks 和作用域内的 AGENTS.md 规则。

常见形式：

# 交互式设置
omx setup

# 用户级设置
omx setup --scope user

# 项目级设置
omx setup --scope project

# 保留已有 AGENTS.md 内容，同时合并 OMX 管理段
omx setup --scope user --merge-agents

只在诊断明确建议且你了解覆盖影响时使用：

omx setup --force

3.5 为仓库生成轻量 AGENTS.md

进入仓库后，先预览：

omx agents-init . --dry-run

确认结果后执行：

omx agents-init .

它会为目标目录和直接子目录生成轻量 AGENTS.md。如果仓库已经有人工维护的 AGENTS.md，先阅读并备份，不要直接加 --force。

3.6 plugin 与 legacy 怎么选

初学者通常让 omx setup 交互选择即可：

plugin 模式：依赖 Codex 插件发现 bundled skills，减少旧式文件影子冲突。
legacy 模式：显式安装传统 prompts/native-agent 文件，适合兼容旧环境。

不要同时手工维护两套同名 skill/agent。出现“调用的行为与当前版本不一致”时，优先运行 omx doctor 检查陈旧文件。

3.7 每次升级后的检查

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

4. 新项目如何使用 OMX

4.1 推荐流程

mkdir my-web-app
cd my-web-app
git init
omx agents-init . --dry-run
omx agents-init .
omx --high

然后按四个阶段推进。

阶段 A：明确需求

$deep-interview "我要创建一个 Web 应用，首个版本支持邮箱注册、登录和退出。请逐项确认用户、范围、技术约束、安全要求、非目标和验收标准。不要写代码。"

应得到的结果：

谁使用系统；
本期做什么、不做什么；
技术栈和部署约束；
API、数据和兼容要求；
测试与验收标准。

阶段 B：审批计划

$ralplan "根据已确认的登录需求，检查仓库现状并制定决策完整的实施计划。必须覆盖数据模型、接口、错误处理、安全、测试、迁移和回滚；等待我批准后再执行。"

审计划时重点检查：

是否无意扩大范围；
是否复用了现有架构；
公共接口是否明确；
数据迁移是否可回退；
是否包含失败路径测试；
完成标准能否通过命令证明。

阶段 C：持久执行

$ultragoal "执行已批准的登录功能计划。按依赖顺序建立目标；每个目标完成前运行相应测试并保存证据。遇到需要产品决策、权限或外部凭据时停止并明确说明，不得猜测。"

阶段 D：最终验收

请对照原始需求逐项验收：运行完整测试和构建，检查未提交差异，执行代码审查，列出每条验收标准对应的证据。存在失败或未验证项时不要宣称完成。

4.2 新项目的 AGENTS.md 应写什么

建议只写稳定、长期有效的项目规则：

# Project Instructions

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Architecture
- `apps/web`: frontend
- `apps/api`: backend
- `packages/shared`: shared types

## Rules
- Public API changes require tests and documentation.
- Never edit generated files directly.
- Do not commit secrets or `.env` files.
- Run affected tests before claiming completion.

不要在 AGENTS.md 中塞入一次性需求、临时聊天记录或真实密钥。

5. 已有项目如何接入 OMX

已有项目最重要的原则是：先建立事实基线，再允许修改。

5.1 接入前检查

cd existing-project
git status --short
find .. -name AGENTS.md -print
omx doctor
omx agents-init . --dry-run

如果工作区已经有未提交改动：

先确认改动是谁产生的；
不要让 Agent 自动覆盖、restore 或 reset；
必要时由你自己提交或 stash；
在提示词中明确“保留现有未提交改动”。

5.2 先让 Codex 只读理解项目

请只读检查当前仓库，不要修改文件。说明：
1. 主要模块和入口；
2. 构建、测试、lint 命令；
3. 与用户认证相关的代码路径；
4. 当前 git 状态和潜在风险；
5. 实现“密码重置”前仍需确认的问题。
结论必须引用具体文件路径或命令证据。

当前版本不应把 omx explore 当作新仓库查找的推荐入口。它是弃用兼容命令。仓库理解应直接交给 Codex 的正常检查能力；明确需要 shell 原生的只读证据时可用：

omx sparkshell git status --short
omx sparkshell rg "password reset|forgot password" .

5.3 建立测试基线

在改代码前让 Agent：

找到仓库规定的测试命令；
运行与目标模块最相关的测试；
记录原本就失败的测试；
不把既有失败错误归因于本次改动。

示例提示词：

在修改任何文件前，请先读取项目规则和清单文件，确定正确的测试命令。运行认证模块的最小测试集并记录基线。若基线失败，先报告失败及证据，不要直接开始大范围修复。

5.4 保护已有 AGENTS.md

如果用户级 AGENTS.md 已有自己的规则，优先：

omx setup --scope user --merge-agents

如果项目文件已经由团队维护，先阅读内容和作用域。不要无条件使用 --force。OMX 管理区通常以明确的 START/END 标记存在；人工规则应保留在管理区之外。

5.5 小改动不必套完整流程

对于边界非常明确的小任务，可以直接说：

修复登录表单中错误提示未清除的问题。先复现并写失败测试，只修改必要文件；运行相关测试和 lint，最后给出差异摘要和验证证据。不要改动无关样式。

对于接口变更、跨模块改造、迁移或高风险安全功能，再使用完整的 interview/plan/goal 流程。

6. 推荐的日常工作流

6.1 `$deep-interview`：需求还不清楚

适用于：

用户只说“做个登录”；
多个团队对范围理解可能不同；
有安全、数据、兼容或上线约束；
你还说不清楚什么叫完成。

提示词模板：

$deep-interview "[需求]。请先检查可发现的仓库事实，再一次聚焦一个高影响问题。最终明确目标、用户、范围、非目标、约束、接口、失败场景和验收标准。不要实现。"

停止条件：形成可审批的需求说明，剩余未知项不会影响设计。

6.2 `$ralplan`：形成可实施计划

当前 catalog 中 ralplan 会路由到 planning surface。适用于跨文件、跨模块或存在权衡的任务。

$ralplan "基于已确认需求和仓库现状制定计划。明确接口、数据流、兼容策略、边界情况、测试、迁移、回滚和验收命令；计划批准前不得修改代码。"

停止条件：实现者不需要自行决定关键产品或架构问题。

6.3 `$ultragoal`：默认的持久完成路径

适用于：

已有批准计划；
任务由多个有依赖关系的故事组成；
希望跨会话保存目标和证据；
需要明确 ledger/checkpoint。

CLI 状态文件位于：

.omx/ultragoal/brief.md
.omx/ultragoal/goals.json
.omx/ultragoal/ledger.jsonl

查看状态：

omx ultragoal status
omx ultragoal status --json

停止条件：所有批准目标完成，最终测试、构建和审查通过，证据已记录；外部授权阻塞时停止等待用户决定，而不是循环重试。

6.4 `$ralph`：单责任人的持续完成循环

适用于：

目标明确；
一个持续 owner 推进更合适；
不需要多个 durable goal ledger；
例如持续修复一组失败测试。

交互会话内：

$ralph "修复认证模块所有失败测试。先确认根因，每次做最小修改并验证；全部相关测试、完整测试和代码审查通过后停止。"

CLI 启动：

omx ralph "修复认证模块的失败测试"
omx ralph --prd "交付发布检查自动化"

不要把“持续”理解成“永不停止”。提示词必须定义完成证据和阻塞退出条件。

6.5 `$team`：有价值的并行协作

适用于：

至少两个任务能独立推进；
并行收益大于协调成本；
可以用文件、模块或测试边界隔离；
需要 tmux、worktree 和持久团队状态。

CLI 示例：

omx team 3:executor "按已批准计划实现认证改造；拆分后端、前端和测试任务，最后集成验证"

常见管理命令：

omx team status <team-name>
omx team status <team-name> --json
omx team await <team-name>
omx team resume <team-name>
omx team shutdown <team-name>

Team worker 默认使用独立 worktree。不要让多个 worker 同时修改同一个核心文件，也不要用 Team 处理一个十分钟就能完成的小修复。

7. 如何选择普通 Codex、Skill、子 Agent 和 Team

场景	推荐方式	原因
解释代码、查位置	普通 Codex	开销最低
单文件小修复	普通 Codex + 明确验证	不需要复杂编排
需求含糊	`$deep-interview`	先消除产品歧义
跨模块功能	`$ralplan` 后执行	先锁定接口和依赖
多阶段、可跨会话任务	`$ultragoal`	有持久目标和 ledger
目标明确、单 owner 持续推进	`$ralph`	完成循环更简单
会话内 2–3 个短小独立调查	Codex 原生子 Agent	无需 tmux/worktree 的持久协调
大型并行实现	`$team` / `omx team`	隔离 worker、持久状态
代码质量审查	`$code-review`	使用统一审查流程
UI/UX 设计任务	`$design`	路由到设计专业面

简单判断：

任务是否含糊？
  是 -> deep-interview
  否 -> 是否跨模块/高风险？
         是 -> ralplan
         否 -> 普通 Codex

计划批准后是否需要跨会话的多个目标？
  是 -> ultragoal
  否 -> 是否需要单 owner 持续推进？
         是 -> ralph
         否 -> 普通执行

是否存在真正独立且耗时的并行子任务？
  短小、同会话 -> 原生子 Agent
  持久、需隔离 -> team

8. 四个完整实战案例

8.1 案例一：新项目实现用户登录

目标：新建通用 Web 项目，支持邮箱登录和退出。

准备

mkdir account-app
cd account-app
git init
omx agents-init .
omx --high

澄清需求

$deep-interview "为新 Web 应用设计邮箱登录和退出。请确认目标用户、会话方式、密码规则、失败提示、安全要求、部署约束和 v1 非目标。最终给出可测试的验收标准，不要写代码。"

审批计划

$ralplan "为已确认的登录需求制定实现计划。只选择项目所需的最小架构；明确目录、公共接口、数据模型、认证流程、错误响应、测试层级和验收命令。"

执行

$ultragoal "按批准计划实现登录。目标顺序为：项目骨架、认证数据和服务、API、前端交互、集成测试、最终审查。每项完成必须附命令输出证据。"

验收

正确账号可登录；
错误密码不会泄露账号是否存在；
退出后旧会话失效；
核心失败路径有自动测试；
完整测试和构建通过；
无 .env、token、cookie 或密码进入 Git 差异。

8.2 案例二：已有项目增加密码重置

目标：在已有认证系统中增加密码重置，保持现有登录兼容。

只读调查

只读检查仓库中的用户模型、认证服务、邮件设施、路由、前端页面和测试。给出相关路径、当前接口约定、可复用组件、未提交改动和风险。不要修改文件。

需求与计划

$deep-interview "在现有项目中增加密码重置。重点澄清 token 生命周期、一次性使用、防枚举、限流、邮件失败、旧会话处理、兼容要求和验收标准。"

$ralplan "基于调查结果设计最小兼容改动。明确 API、token 存储、过期与消费语义、迁移、邮件边界、前端状态、失败测试和回滚方案。"

执行约束

$ultragoal "执行批准的密码重置计划。保留已有未提交改动，不改变现有登录响应格式；先写失败测试，再做最小实现。需要邮件服务凭据时使用测试替身，不得索取或写入真实密钥。"

停止条件

token 过期、重复使用、篡改均被拒绝；
不暴露邮箱是否注册；
邮件失败有明确可恢复行为；
迁移可执行并有回退说明；
现有登录回归测试通过。

8.3 案例三：修复偶发测试失败

目标：定位 CI 中偶发失败，不做猜测式修改。

$ralph "定位并修复认证模块的偶发测试失败。流程必须是：稳定复现或收集足够失败证据；提出单一根因假设；用最小实验验证；先增加能捕获问题的回归测试；实现最小修复；重复运行目标测试并运行完整测试。连续无法复现时报告证据和下一步，不得靠增加 sleep 掩盖问题。"

建议的验收证据：

- 修复前的失败日志或稳定复现命令
- 回归测试在修复前失败、修复后通过
- 目标测试重复运行足够次数
- 完整测试通过
- 差异中没有无关重构

8.4 案例四：大型认证模块改造

目标：后端 token 轮换、前端会话恢复、测试和迁移可以部分并行。

先用 $ralplan 明确依赖图，再启动 Team：

omx team 3:executor "执行已批准的认证模块改造：worker 1 负责后端 token 轮换和单测；worker 2 负责前端会话恢复和组件测试；worker 3 负责迁移、兼容性测试和文档。禁止修改对方负责文件；先报告潜在共享文件冲突，最后由 leader 集成并运行完整验证。"

跟踪状态：

omx team status <team-name> --model-inspect --tail-lines 600
omx team await <team-name> --timeout-ms 600000

验收重点：

每个 worker 的所有权边界明确；
共享类型或 lockfile 由 leader 统一处理；
集成后重新运行测试，不能只相信 worker 报告；
Team 正常 shutdown 后再清理临时状态。

9. 权限、安全和停止条件

9.1 启动模式的风险层级

启动方式	含义	建议
`omx`	默认策略，支持环境时使用 OMX 管理的 tmux	日常推荐
`omx --high`	提高推理强度	复杂任务推荐
`omx --direct`	不让 OMX 管理 tmux/HUD	一次性、简单会话
`omx --yolo`	更少审批的快捷启动方式	仅在可信仓库和明确沙箱内使用
`omx --madmax`	绕过审批和沙箱	高风险，不作为默认做法

官方快速示例可能展示 --madmax --high，但这不表示它适合所有电脑和仓库。--madmax 允许 Agent 在缺少交互确认的情况下执行危险操作；只有当外层环境已经可靠隔离、仓库可恢复、凭据受控时才考虑。

9.2 提示词中应明确的安全边界

- 不读取或输出真实密钥、token、cookie 和个人数据。
- 不修改仓库外文件。
- 不执行 rm、git reset --hard、强推或生产数据库操作。
- 不覆盖用户已有未提交改动。
- 安装依赖、联网下载、迁移数据库和调用外部服务前需要批准。
- 外部权限不足时停止并报告，不得绕过。

9.3 好的停止条件

不要只说“做好为止”。应该定义：

仅当以下条件全部满足时结束：
1. 原始验收标准逐条满足；
2. 相关单元测试、集成测试、lint 和构建通过；
3. 代码审查没有阻断问题；
4. git diff 中没有无关修改和敏感信息；
5. 给出执行命令及结果摘要。

若连续三次遇到相同的外部权限/凭据阻塞，停止执行并请求用户决策；不要无限重试。

9.4 何时立即停止

发现生产凭据或真实用户数据；
计划外的大范围删除或迁移；
测试基线本身不可信；
多个 worker 修改同一核心文件；
需求需要产品或法律决定；
继续操作需要绕过安全控制；
验证连续失败且没有新的证据。

10. 会话、状态和任务恢复

10.1 查看 OMX 状态

omx status
omx hud
omx hud --watch
omx hud --json

HUD 是监控界面，不是主要工作流入口。

10.2 恢复 Codex 会话

omx resume
omx resume --last
omx resume --all

omx resume 最终进入 Codex 的会话恢复界面；默认选择器通常按当前目录过滤。

10.3 取消活动模式

omx cancel

取消前先确认是否仍有 Team worker 或关键验证在运行。

10.4 Team 恢复和关闭

omx team status <team-name>
omx team resume <team-name>
omx team shutdown <team-name>

仅在确认 Team 已死或明确放弃时使用强制关闭：

omx team shutdown <team-name> --force --confirm-issues
omx cancel
omx doctor --team

10.5 `.omx/` 是否应该提交

.omx/ 中既可能有有价值的计划/ledger，也可能有本地日志、PID 和临时运行状态。不要一刀切提交整个目录。

建议：

查看具体文件用途；
团队决定哪些计划或项目记忆应版本化；
本地 PID、会话缓存和日志通常加入 .gitignore；
提交前扫描敏感数据。

11. 常见问题与排错

11.1 `omx doctor` 绿色但真实任务失败

依次检查：

codex login status
echo "${CODEX_HOME:-$HOME/.codex}"
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

常见原因：

当前 shell 使用了不同的 HOME/CODEX_HOME；
登录信息不在 OMX 实际启动环境中；
自定义代理或 base URL 没有进入当前 profile；
API key 与目标 endpoint 不匹配。

不要把真实 key 粘贴到对话或日志中。

11.2 AGENTS.md 警告

如果 doctor 提示用户级 AGENTS.md 缺少 OMX 管理标记，同时你又有自己的规则，优先：

omx setup --scope user --merge-agents
omx doctor

只有在确定可以替换、且已备份时才考虑：

omx setup --scope user --force

11.3 hooks、prompts 或 skills 缺失

先运行：

omx doctor
omx list

如果 doctor 明确建议刷新：

omx setup --force
omx doctor

如果有自定义 AGENTS.md，先用 --merge-agents；如果有自定义 hooks，先检查 setup 是否会保留非 OMX 条目并备份配置。

11.4 当前电脑的示例诊断

在编写本指南时，本机 v0.18.6 的 omx doctor 显示：

Codex、Node.js、配置和基础 hook smoke test 正常；
用户级 native hooks、prompts、skills 数量和 AGENTS.md 管理段存在警告；
推荐优先使用 omx setup --scope user --merge-agents 保留已有规则，再复查 doctor；
只有警告明确要求完全替换时才考虑 omx setup --force。

这只是诊断解读示例，不代表其他电脑会出现同样结果。

11.5 Team 或 tmux 状态异常

omx doctor --team
omx team status <team-name> --json
tmux list-sessions

先判断 tmux 会话是否真实存在，再决定 resume 或 shutdown。不要看到状态文件就假定 worker 仍在运行。

11.6 Shift+Enter 在 tmux 中不能换行

当前 OMX 会在自身启动路径中配置 tmux 扩展按键转发。仍有问题时通常应检查：

tmux 版本；
终端是否支持扩展键；
是否从 OMX 管理的启动路径进入；
外部 tmux 配置是否覆盖相关设置。

可临时使用 omx --direct 判断问题是否仅发生于 tmux。

11.7 `omx explore` 怎么办

omx explore 在当前版本属于 DEPRECATED compatibility command。新仓库查找不要再依赖它。

推荐替代：

直接让 Codex 只读检查仓库；
shell 原生只读证据使用 omx sparkshell <command>；
tmux pane 摘要使用：

omx sparkshell --tmux-pane <pane-id> --tail-lines 400

11.8 如何查看当前真正可用的 Skill

omx list
omx list --json

以 active 项为准。deprecated、merged、alias 可能仍保留兼容入口，但新文档和新提示词优先使用其当前目标。

12. 高频命令速查

12.1 安装与检查

命令	用途
`omx version`	查看 OMX、Node 和平台版本
`omx setup`	安装/刷新 OMX 配置和工作流文件
`omx update`	检查 npm 新版、更新并刷新 setup
`omx doctor`	检查安装健康度
`omx doctor --team`	检查 Team/tmux 运行时
`omx list`	查看 skills 和 agents catalog
`omx agents-init . --dry-run`	预览项目 AGENTS.md 初始化
`omx agents-init .`	初始化轻量项目规则

12.2 启动与执行

命令	用途
`omx`	启动交互式 OMX/Codex
`omx --high`	使用 high 推理强度启动
`omx --xhigh`	使用 xhigh 推理强度启动
`omx --direct`	不使用 OMX tmux/HUD 管理
`omx exec "任务"`	非交互执行任务
`omx resume`	恢复历史会话
`omx status`	查看活动模式和状态
`omx cancel`	取消活动执行模式
`omx reasoning`	查看当前推理强度
`omx reasoning high`	设置推理强度

12.3 Team

命令	用途
`omx team 3:executor "任务"`	启动三个 executor worker
`omx team status <name>`	查看团队状态
`omx team await <name>`	等待团队事件/完成
`omx team resume <name>`	恢复团队
`omx team shutdown <name>`	关闭团队
`omx sidecar --watch`	只读查看 team/multi-agent 状态

12.4 常用 Skill

Skill	适用场景
`$deep-interview`	澄清需求、范围和验收标准
`$ralplan`	生成并审批实施计划
`$ultragoal`	持久、多目标执行
`$ralph`	单 owner 持续完成循环
`$team`	大型并行协作
`$code-review`	代码审查
`$design`	UI/UX 设计
`$ask`	调研、咨询或调用本地 provider
`$ai-slop-cleaner`	最终清理低质量生成痕迹

Skill catalog 会变化。以你当前执行 omx list 的输出为准。

12.5 Agent 管理

omx agents list
omx agents list --scope project
omx agents add <name> --scope project
omx agents edit <name> --scope project
omx agents remove <name> --scope project

大多数初学者不需要立即自定义 Agent。优先使用 bundled skills 和现有专业角色。

13. 可复制的提示词模板

13.1 新功能

目标：在 [项目/模块] 中实现 [功能]。

开始前：
1. 阅读适用的 AGENTS.md 和项目文档；
2. 检查 git 状态，保留已有未提交改动；
3. 只读定位相关入口、类型、测试和约定；
4. 如果需求存在高影响歧义，先询问，不要猜测。

约束：
- 复用现有架构，做最小必要修改；
- 不修改无关文件；
- 公共接口变化必须说明兼容影响；
- 不接触真实密钥或生产数据。

验证：
- 先建立测试基线；
- 为新行为和失败路径增加测试；
- 运行相关测试、lint、构建和最终代码审查；
- 用命令输出证明验收标准。

13.2 Bug 修复

修复：[可观察到的问题]。

必须先复现并定位根因，不要根据症状猜改。先写能捕获问题的回归测试，确认修复前失败，再做最小修复并确认通过。运行相关测试和完整回归；不要顺手重构无关代码。最终给出根因、差异、验证命令和结果。

13.3 重构

重构 [模块]，目标是 [可衡量目标]，外部行为保持不变。

先列出公共接口、调用者和现有测试；建立行为基线。分小步修改，每步运行目标测试。禁止同时引入新功能。完成时提供 API 兼容证据、测试结果和性能/复杂度对比（仅在目标要求时）。

13.4 测试修复

修复当前失败测试。先区分产品缺陷、测试缺陷、环境问题和偶发失败。不要为了变绿而删除断言、跳过测试或增加任意 sleep。每个修改必须对应已验证的根因。完成条件是目标测试稳定通过、完整测试无新增失败，并给出证据。

13.5 代码审查

$code-review "审查当前分支相对基线的差异。优先查找正确性、安全、数据丢失、兼容性、并发、性能和测试缺口。只报告可操作问题，按严重度排序，引用具体文件和行；没有问题时也说明残余风险和未验证项。"

13.6 UI 功能

$design "为 [页面/流程] 设计并实现 [目标]。先检查现有设计系统和组件，不要生成通用模板风格。覆盖桌面和移动布局、加载/空/错误/禁用状态、键盘操作和可访问性。最终运行前端测试并进行浏览器视觉验收。"

13.7 只读仓库分析

只读分析当前仓库，不得修改文件或安装依赖。回答 [问题]，并提供具体文件路径、符号、配置或命令输出作为证据。区分已确认事实、合理推断和仍需验证的信息。

13.8 大型任务交给 Team

$team "执行已批准的 [项目] 计划。先按模块和依赖拆分任务，声明每个 worker 的文件所有权、输入、输出和验证命令；共享文件只由 leader 修改。worker 完成后必须由 leader 检查实际 diff 并运行集成测试。出现冲突或产品歧义时停止并报告。"

14. 推荐习惯与反模式

14.1 推荐习惯

复杂任务先 interview/plan，批准后再执行。
每个任务写清楚验收证据和停止条件。
先读项目规则和 git 状态。
修改前建立测试基线。
让 Agent 区分事实、推断和未知。
小任务保持简单，大任务才使用持久编排。
Team 按文件/模块隔离，leader 负责最终集成验证。
升级后运行 doctor、list 和真实调用 smoke test。
保留人工决策权：权限、生产、迁移和破坏性操作必须确认。
完成前看真实 diff 和最新测试输出，不只看 Agent 的总结。

14.2 常见反模式

反模式	问题	改进
一上来就“全部做完”	范围和完成标准不清	先 interview 和 plan
所有任务都开 Team	协调成本高、容易冲突	只有独立耗时任务才并行
默认 `--madmax`	绕过审批和沙箱	优先普通/高推理启动
让多个 worker 改同一文件	合并冲突、责任不清	按模块分工，共享文件归 leader
测试失败就改断言	掩盖真实缺陷	先证明根因
只跑局部测试就称完成	可能引入回归	局部验证后跑项目规定的完整门禁
自动覆盖 AGENTS.md	丢失团队规则	dry-run、阅读、merge-agents
把 `.omx/` 全部提交	混入日志、PID 或敏感状态	按文件类型制定版本策略
继续使用 `omx explore`	已弃用，行为可能变化	正常仓库检查或 sparkshell
无限重试权限错误	浪费成本且无法解决	明确阻塞，等待用户决策

14.3 一套适合日常工作的固定流程

cd your-project
git status --short
omx doctor
omx --high

在会话中：

# 复杂/含糊需求
$deep-interview "澄清这个需求……"
$ralplan "根据确认结果制定计划……"
$ultragoal "执行已批准计划，按证据验收……"

# 明确的小 Bug
复现并修复这个问题；先写回归测试，最小修改，运行相关测试和完整门禁……

# 明确但需要持续推进的任务
$ralph "持续修复这些失败测试，满足验证条件后停止……"

# 真正可并行的大任务
$team "按模块拆分已批准计划，隔离修改并最终集成验证……"

结语

学习 OMX 的重点不是背下所有命令，而是形成四个习惯：

含糊需求先澄清；
高风险修改先审批计划；
长任务使用可恢复的目标和状态；
所有完成声明都必须有新鲜的验证证据。

需要核对当前环境时，从下面四条命令开始：

omx version
omx help
omx list
omx doctor

官方项目入口：https://github.com/Yeachan-Heo/oh-my-codex

posted @ 2026-07-16 17:17 前方、有光阅读(83) 评论(1) 收藏举报

刷新页面返回顶部

记录一些日常，自从有了AI。很少记录了。。

OMX使用

OMX 从入门到进阶：Codex 用户实战指南

目录

1. 十分钟快速上手

1.1 检查现有环境

1.2 安装或更新 OMX

1.3 做一次真实调用测试

1.4 启动 OMX

2. OMX 到底是什么

2.1 你得到的主要提升

2.2 OMX 不适合什么

3. 安装、升级与健康检查

3.1 前置要求

3.2 已经安装 Codex 的用户

3.3 尚未安装 Codex 的用户

3.4 omx setup 的作用

3.5 为仓库生成轻量 AGENTS.md

3.6 plugin 与 legacy 怎么选

3.7 每次升级后的检查

4. 新项目如何使用 OMX

4.1 推荐流程

阶段 A：明确需求

阶段 B：审批计划

阶段 C：持久执行

阶段 D：最终验收

4.2 新项目的 AGENTS.md 应写什么

5. 已有项目如何接入 OMX

5.1 接入前检查

5.2 先让 Codex 只读理解项目

5.3 建立测试基线

5.4 保护已有 AGENTS.md

5.5 小改动不必套完整流程

6. 推荐的日常工作流

6.1 $deep-interview：需求还不清楚

6.2 $ralplan：形成可实施计划

6.3 $ultragoal：默认的持久完成路径

6.4 $ralph：单责任人的持续完成循环

6.5 $team：有价值的并行协作

7. 如何选择普通 Codex、Skill、子 Agent 和 Team

8. 四个完整实战案例

8.1 案例一：新项目实现用户登录

准备

澄清需求

审批计划

执行

验收

8.2 案例二：已有项目增加密码重置

只读调查

需求与计划

执行约束

停止条件

8.3 案例三：修复偶发测试失败

8.4 案例四：大型认证模块改造

9. 权限、安全和停止条件

9.1 启动模式的风险层级

9.2 提示词中应明确的安全边界

9.3 好的停止条件

9.4 何时立即停止

10. 会话、状态和任务恢复

10.1 查看 OMX 状态

10.2 恢复 Codex 会话

10.3 取消活动模式

10.4 Team 恢复和关闭

10.5 .omx/ 是否应该提交

11. 常见问题与排错

11.1 omx doctor 绿色但真实任务失败

11.2 AGENTS.md 警告

11.3 hooks、prompts 或 skills 缺失

11.4 当前电脑的示例诊断

11.5 Team 或 tmux 状态异常

11.6 Shift+Enter 在 tmux 中不能换行

11.7 omx explore 怎么办

11.8 如何查看当前真正可用的 Skill

12. 高频命令速查

12.1 安装与检查

12.2 启动与执行

12.3 Team

12.4 常用 Skill

12.5 Agent 管理

3.4 `omx setup` 的作用

6.1 `$deep-interview`：需求还不清楚

6.2 `$ralplan`：形成可实施计划

6.3 `$ultragoal`：默认的持久完成路径

6.4 `$ralph`：单责任人的持续完成循环

6.5 `$team`：有价值的并行协作

10.5 `.omx/` 是否应该提交

11.1 `omx doctor` 绿色但真实任务失败

11.7 `omx explore` 怎么办