OMC/OMX 异步任务派发（v3 — 重启安全）

前置条件

• claude -p 需要 ANTHROPIC_API_KEY：Claude Code 的 -p/--print 管道模式依赖 API Key 认证，不支持 OAuth 交互登录。设置：export ANTHROPIC_API_KEY="sk-ant-..."
• claude CLI 已安装
• omx CLI 已安装
• Python 3.9+

⚡ 快捷指令

匹配规则：消息匹配到 OMC/OMX 关键词即加载本技能，后续内容直接作为任务描述。 复杂任务自动写入 spec.md，简单任务直接嵌入命令行。

核心原则

1. 预检先行：派发前必须验证工作目录存在、CLI 工具可用、OMX git repo 检查
2. 所有输出写文件：claude -p 和 omx exec 的 stdout/stderr 全部重定向到任务目录下的文件，不依赖主 Agent 的 stdout PIPE
3. 进程独立存活：os.setsid 创建独立进程组，主 Agent 死亡不影响子进程
4. task.json 是单一真相源：任务元数据、状态、PID 全在一个 JSON 文件里，完成回调必须更新 status
5. 重启可恢复：Agent 重启后运行 task-recovery.py recover 还原状态

目录结构

~/.openclaw/workspace/tasks/
├── 2026-04-27-120000-fix-auth/       # 任务ID = 时间戳 + slug
│   ├── task.json                     # 元数据 + 状态（轻量，只有索引信息）
│   ├── spec.md                       # 完整任务描述（目标、上下文、约束、验收标准）
│   ├── result.txt                    # stdout 重定向（最终回答）
│   ├── log.txt                       # stderr 日志（hook 日志等）
│   └── exit_code                     # 完成时写入退出码
├── 2026-04-27-130000-add-tests/
│   └── ...

task.json Schema（轻量，不含任务细节）

核心字段：id、engine、status、command、cwd、pid、started_at

状态流转：pending → running → completed / failed

重要约束：

• cwd 必须是已验证存在的绝对路径，禁止 ~ 简写
• preflight_ok 标记 Step 0 预检结果
• sandbox_args 存储 OMX 额外参数

详细字段定义和 autopilot 扩展字段见 references/task-schema.md

spec.md 模板

基础结构：# 任务 → ## 目标 → ## 项目上下文 → ## 详细需求 → ## 约束条件 → ## 验收标准

关键生成规则：

• 保持用户原文，不做删减
• 所有路径使用 Step 0 预检通过的绝对路径
• 验收标准必须可验证
• 技术栈从项目文件推断

完整模板和复杂任务示例见 references/spec-template.md

编排器派发流程

Step 0: 预检（Pre-flight Check）⚠️ 必须通过才能派发

在创建任何文件之前，必须验证以下 3 项：

import os, subprocess

cwd = os.path.expanduser(cwd_raw)  # 展开 ~

# 检查 1：cwd 必须是存在的目录
if not os.path.isdir(cwd):
    # ❌ 直接拒绝，不要猜路径，不要降级到 ~
    raise PreflightError(
        f"工作目录不存在: {cwd}\n"
        f"请用 -d 指定正确路径。常见路径：\n"
        f"  ~/.openclaw/workspace  (工作目录)\n"
        f"  项目目录\n"
        f"  当前目录: {os.getcwd()}"
    )

# 检查 2：CLI 工具必须可用
if engine == "omc":
    result = subprocess.run(["which", "claude"], capture_output=True, text=True)
    if result.returncode != 0:
        raise PreflightError("claude 命令不可用，请检查 PATH")
elif engine == "omx":
    result = subprocess.run(["which", "omx"], capture_output=True, text=True)
    if result.returncode != 0:
        raise PreflightError("omx 命令不可用，请检查 PATH")

# 检查 3：OMX 需要 git repo 或 --skip-git-repo-check
needs_skip_git = False
if engine == "omx":
    git_dir = subprocess.run(
        ["git", "-C", cwd, "rev-parse", "--git-dir"],
        capture_output=True, text=True
    )
    if git_dir.returncode != 0:
        needs_skip_git = True  # 自动追加 --skip-git-repo-check

预检失败 → 立即告知用户具体原因，不创建任务目录。

Step 1: 创建任务目录 + task.json

生成 task_id（时间戳+slug），创建目录，初始化 task.json（status=pending）。

Step 2: 写入 spec.md（完整任务描述）

使用模板生成完整任务描述，包含目标、上下文、需求、约束、验收标准。

Step 3: 构建命令（从 spec.md 读取任务，输出重定向到文件）

统一模式：cat spec.md | claude -p - 或 cat spec.md | omx exec ... -

OMC（Claude Code 系）— stream-json 双向流模式

核心思路：不再用 cat spec.md | claude -p - 裸文本管道，改用 Claude 原生 stream-json 协议——相当于 Chrome CDP 对 Chrome 的关系。

复杂任务：python3 -c "生成JSONL" | claude -p --input-format stream-json --output-format stream-json --verbose --tools default - > result.txt 2> log.txt ; echo $? > exit_code

简单任务：直接内嵌任务描述到 JSONL 命令行。

stream-json 协议说明：

• stdin：JSONL 格式，每行一个 {"type":"user","message":{"role":"user","content":"..."}}
• stdout：JSONL 事件流（system → assistant → ... → result），最终结果取最后一个 type:"result" 的 .result 字段
• --include-partial-messages：实时输出 partial 块，用于进度追踪
• --verbose：触发完整 OMC 编排加载（agents/skills/hooks/MCP）

解析 OMC JSONL 输出的正确方法：result.txt 是多行 JSONL，不要直接当纯文本读。提取最终结果的代码：

import json
with open("result.txt") as f:
    for line in f:
        event = json.loads(line.strip())
        if event.get("type") == "result":
            final = event.get("result", "")
            break
# final 是纯文本结果（去掉 JSONL 包装）

⚠️ 常见错误：cat spec.md | claude -p - < /dev/null 会冲突——两个输入源（stdin 管道 + 重定向）。正确做法是用 python3 生成 JSONL 再管道给 claude（见上面命令模板），或用 cat spec.md | claude -p -（不用 stream-json 时）。

OMX（Codex CLI 系）

# OMX 支持 -C 参数指定工作目录
# ⚠️ 不用 --full-auto（sandbox 会阻止文件写入和 CLI 调用）
# 用 --dangerously-bypass-approvals-and-sandbox 或 --madmax 关闭沙箱
# 自动追加 --skip-git-repo-check（如果非 git repo）
cat ~/.openclaw/workspace/tasks/TASK_ID/spec.md | \
  omx exec --dangerously-bypass-approvals-and-sandbox \
  -o ~/.openclaw/workspace/tasks/TASK_ID/result.txt \
  -C /absolute/path/to/project \
  {sandbox_args} - \
  # 注意：不要加 -m 指定模型，OMX 默认使用 GPT 最新模型
  2> ~/.openclaw/workspace/tasks/TASK_ID/log.txt ; \
  OMX_EXIT=$? ; \
  echo $OMX_EXIT > ~/.openclaw/workspace/tasks/TASK_ID/exit_code ; \
  # 清理 OMX 遗留的 tmux session（防止进程泄漏） \
  tmux ls 2>/dev/null | grep 'omx-.*-detached-' | cut -d: -f1 | xargs -r tmux kill-session -t 2>/dev/null ; \
  exit $OMX_EXIT

沙箱策略：OMX 不使用 --full-auto（sandbox 模式会阻止实际操作本机文件和 CLI）。始终使用 --dangerously-bypass-approvals-and-sandbox（别名 --madmax）关闭沙箱，因为任务由用户明确派发，在用户本机执行。 sandbox_args：非 git 目录自动追加 --skip-git-repo-check。

简单任务（一句话描述 < 200 字符）可以直接写命令参数，不需要 spec.md。 复杂任务（多行需求、有约束/验收标准）必须用 spec.md。

可用参数：

• OMC: --input-format stream-json --output-format stream-json --verbose（双向流模式，必须） --include-partial-messages（复杂任务推荐） --tools default --model claude-opus-4-6 --max-turns N --max-budget-usd X --effort high（提高推理深度） --agent <name>（指定角色 agent）
• OMX: --dangerously-bypass-approvals-and-sandbox（必须，关闭沙箱） --skip-git-repo-check（非 git 目录） -c key=value（覆盖配置，如 -c model="gpt-5.5"） --json（JSONL 输出） --ephemeral（不持久化会话）

⚠️ OMX 不要指定 -m 模型参数！ Codex 默认使用 GPT 最新模型，无需也不应覆盖。指定外部模型名（如 -m o3、-m claude-sonnet-4）会报 400：The 'xxx' model is not supported when using Codex with a ChatGPT account.

Step 4: 更新 task.json + 后台启动

更新 task.json（status=running，记录 command），启动后台进程，记录 PID。

Step 5: 通知用户

通知任务已派发，包含引擎、ID、描述、工作目录、预计耗时。

Step 6: 完成回调（notify_on_complete 触发）

1. 读取 exit_code 文件，更新 task.json 状态
2. 解析 result.txt：OMC 提取 JSONL 的 result 事件，OMX 直接读取
3. 格式化通知用户

重启恢复

快速恢复：python3 ~/.openclaw/workspace/skills/omc-omx-orchestrator/scripts/task-recovery.py recover

恢复逻辑：检查 exit_code 文件 → 检查 PID 存活 → 更新状态

建议 cron 每 5 分钟执行，修复 notify 丢失问题。

详细恢复算法、手动操作和自动化部署见 references/recovery-guide.md

进度查询

用户问 "任务进展如何？" 时：

# 方法1：读 task.json
cat ~/.openclaw/workspace/tasks/TASK_ID/task.json

# 方法2：检查 exit_code
cat ~/.openclaw/workspace/tasks/TASK_ID/exit_code 2>/dev/null || echo "still running"

# 方法3：读 result.txt 的已有内容（可能还在写）
tail -20 ~/.openclaw/workspace/tasks/TASK_ID/result.txt

# 方法4：检查 PID
kill -0 PID 2>/dev/null && echo "alive" || echo "dead"

两阶段审计-重构模式

对于复杂系统重构任务，使用 OMC（审计）→ 数据收集 → OMX（重构）的两阶段模式：

Phase 1: OMC 审计

1. 收集上下文：先在编排器中运行数据探查（统计、分布、边界情况），把结果写进 spec.md
2. 写审计 spec：spec 中列出具体文件、行号、已知问题、审计维度。审计 spec 中必须包含已收集的数据，不要让审计 agent 自己去跑数据探查
3. 派发 OMC：claude -p 审计任务，获取结构化报告

Phase 2: 数据收集 + OMX 重构

1. 提炼审计结论：从 OMC 报告中提取需修复的问题清单，按优先级排序
2. 写重构 spec：把审计结论、修复方案、验收标准写进新 spec.md。必须包含所有上下文（数据分布、文件结构、约束条件），OMX agent 没有任何历史会话上下文
3. 派发 OMX：omx exec 直接修改文件
4. 验证：回编排器中 dry-run 验证修改结果

关键经验

• OMC 擅长阅读和分析，适合审计、评审、设计
• OMX 擅长写代码和修改文件，适合执行重构
• 两个 agent 之间没有共享上下文——所有信息必须通过 spec.md 传递
• spec 写得越详细（行号、数据、约束），结果越准确
• 8KB+ 的 spec 很正常，不要压缩关键上下文

引擎选择

OMX 进阶子命令

• omx ask: 轻量问答，调用本地 claude 或 gemini CLI，输出 artifact 文件。适合非代码类任务（分析、总结、翻译）

  omx ask "分析这段代码的性能瓶颈" -o analysis.md
  

• omx team: 在 tmux 中并行派发多个 worker pane。每个 worker 独立执行，适合可以拆分的并行任务
  • 需要 tmux 环境，不适合非交互式 shell
  • omx team --yolo 启动 yolo 模式并行执行
• omx explore: 只读探索模式，适合代码库浏览和理解
• omx resume: 恢复之前的交互式会话

多轮审计-重构模式 (OMC Audit → OMX Refactor)

适用于复杂的代码审计+重构任务（如系统重构、多文件联动修改）：

Round 1: OMC 审计（只读）

• spec 重点：描述问题维度、验收标准，明确标注"不修改文件"
• OMC 擅长深度分析和代码审查，输出结构化问题列表

Round 2（可选）: OMC 补充审计

• 基于 Round 1 的发现，深入特定问题（如元数据分布、边界情况）
• 在 spec 中注入实际数据（用 Python 片段提前收集：分布统计、配置快照、行号引用）
• spec 里传数据比让 agent 自己发现数据可靠 10 倍

Round 3: OMX 重构（写入）

• spec 必须包含：前序审计的完整结论、逐行级修改要求、约束条件、验收标准
• 用 --skip-git-repo-check（当前目录不是 git repo）
• 验证由编排器完成（OMX 验证不充分）

关键经验：

• spec 里传数据 > 让 agent 自己发现数据
• 审计和重构用不同引擎：OMC 读+分析，OMX 写+修改
• 复杂任务拆成多轮比一轮塞所有指令效果好
• 每轮完成后编排器侧验证，确认后再进下一轮

OMC 上下文管理（防止 context window overflow）

OMC 在分析复杂任务时会大量调用 tool call 读文件，容易导致上下文窗口爆满。

症状：API Error: The model has reached its context window limit.

JSONL（stream-json）vs 纯文本（text）管道模式

为什么 stream-json 更容易爆？JSONL 的每条事件都带 type、message wrapper、tool_use/tool_result 结构，同样 25 轮 tool call 下，stream-json 的元数据可能占总上下文的 15-25%。text 模式只传文本本身，没有结构化包装。

关键踩坑（实战验证）

• --output-format stream-json 必须同时加 --verbose，否则静默失败无输出
• --input-format stream-json 必须配合 --output-format stream-json，不能混用
• stream-json 模式下 --max-turns N 每轮 tool call 算 1 turn，30-50 轮适合轻中型任务；复杂任务应切换 text 模式（不设 max-turns）
• text 模式失败时 result.txt 只有 "Error: Reached max turns (N)" 这一行，log.txt 为空
• OMX 的 o3 模型通过中转站可能 503（No available channel for model o3），备选方案：不指定 -m 或用 OMC (claude) 替代

两种管道模式（按任务复杂度选择）

stream-json 模式（轻中型任务 + 需要结构化输出）

JSONL 元数据会加速上下文消耗，必须设 --max-turns 30-50 防爆。必须同时加 --verbose 否则静默失败。适合：需要结构化 JSONL 输出、进度追踪、中等复杂度任务。

text 模式（复杂任务）

纯文本无 JSONL 膨胀，上下文不会轻易爆掉，不需要设 --max-turns，让 agent 跑完为止。适合：需要大量思考和工具调用的复杂任务。⚠️ 注意：--max-turns 1-3 的 text 模式是坑——OMC 内部 prompt 处理也消耗轮次，3 轮以内根本来不及输出。

预收集数据（两种模式通用，最推荐的优化）

编排器先读相关文件，把关键信息嵌入 spec.md，减少 agent 自己读文件的需求。spec 里传数据比让 agent 自己发现数据可靠 10 倍。实测：3.2KB spec → 5.1KB 结构化审计报告。

⚠️ OMC 插件模式下：数据嵌入是必须项，非可选。oh-my-claudecode 的 hooks/plugins 会限制 claude -p 的工具权限，导致 agent 只有 MCP 认证工具和 Context7，无法调用 Read/Bash 读取本地文件。在这种场景下，spec.md 必须自包含所有数据。可以用 --bare 参数绕过 OMC 限制获得完整工具集，但会丢失 OMC 的全部 agent 编排、skills、hooks 能力，需要按场景权衡。

命令模板

# 轻中型任务（stream-json + max-turns 限制）
python3 -c "import json; print(json.dumps({'type':'user','message':{'role':'user','content':open('spec.md').read()}}))" | \
claude -p --input-format stream-json --output-format stream-json --verbose \
  --model claude-opus-4-6 --tools default --max-turns 30 - \
  > result.txt 2> log.txt ; echo $? > exit_code

# 复杂任务（text 模式，不设 max-turns）
cat spec.md | claude -p --output-format text --model claude-sonnet-4-20250514 -

选择指南

OMC Magic Keywords

OMC/OMX 交互式会话中可通过 $keyword 触发内置 skill：

Tier-0 工作流（OMX 官方推荐链路）：

执行辅助：

• ultrawork / ulw / uw — 并行执行引擎
• ultrathink / think — 深度推理
• ultraqa — QA 循环修复
• cancelomc — 取消当前执行模式

⚠️ $keyword 仅在交互式会话中可用。omx exec 非交互管道模式下，keyword 不触发 skill 系统。如需在 omx exec 中使用，需将 keyword 作为 prompt 内容传入，但效果不如交互式会话。

# 交互式：keyword 直接生效
omx --madmax --high
# 会话内输入: $autopilot "构建 REST API"

# 非交互：keyword 作为 prompt 传入（效果受限）
echo '$autopilot 构建REST API' | omx exec --dangerously-bypass-approvals-and-sandbox -C . -

OMX 内置 Skill 目录（本机 42 个 skill，27 active）：autopilot、ralph、ultrawork、team、plan、ralplan、deep-interview、autoresearch、pipeline、ultraqa、code-review、security-review 等。通过 omx list 查看。

OMC Agent 角色

--agent <name> 可选值（核心角色）：

executor（通用执行）| architect（架构设计）| debugger（调试排查）| code-reviewer（代码审查）| planner（任务规划）| test-engineer（测试编写）| security-reviewer（安全审计）| analyst（分析评估）| critic（批判审查）| designer（UI/前端设计）| writer（文档编写）| verifier（验证确认）| build-fixer（构建修复）| git-master（Git 操作）| researcher（研究调研）

本机安装 219 个 agent（含学术/设计/工程/金融/法务等领域），完整列表见 ~/.claude/agents/。 --effort 控制推理深度：low/medium/high/max。未指定时继承父会话设置。

故障处理

Plan→Build→Verify 循环编排

独立技能 autopilot 实现了完整的 PBV 循环编排（最多 5 轮自动收敛）。 触发：autopilot <描述> 依赖：本技能提供 OMC/OMX 派发能力，autopilot 负责循环控制和验证。 autopilot 定义了 plan.md 和 verify_report.md 的完整格式（详见其 references/）。

以下是 PBV 循环的核心格式摘要（完整版见 autopilot 技能）：

plan.md 核心结构（OMC 输出）：

# Plan: {task description}
> Round: {round} | Task: {task_id}
## 任务概述 / ## 执行步骤 / ## 文件清单 / ## 风险点 / ## 完成标准

verify_report.md 核心结构（编排器输出）：

# Verify Report - Round {round}
> Task: {task_id} | Status: PASSED/FAILED
## 总结 / ## 验证详情 / ## 问题汇总（P0/P1） / ## 建议修复方向

退出条件：✅ 通过 / 🛑 5轮上限 / 🛑 连续2轮同错 / 🛑 连续2轮无进展

定期清理与自动恢复

推荐 cron 配置：

• 每 5 分钟：task-recovery.py recover（修复状态不一致）
• 每小时：清理 OMX tmux session
• 每周：task-recovery.py cleanup --days 7（清理过期任务）

完整 cron 配置和清理策略见 references/recovery-guide.md

快捷指令解析规则

格式：用 OMC <描述> [-d <目录>] [-m <模型>] 或 用 OMX <描述> [-d <目录>]

解析步骤：引擎 → 工作目录(-d) → 模型(-m) → 任务描述 → 创建 task.json → 后台执行

任务查询：task-recovery.py list 列表，查询任务 <id> 详情

重要提醒

• 不要用 ralphthon / team 模式——强制依赖 tmux，非交互式 shell 无法使用
• 不要用 stdout PIPE 接收结果——Agent 重启会断管导致 SIGPIPE 杀死子进程
• 所有输出必须重定向到文件——> result.txt 2> log.txt ; echo $? > exit_code
• 必须加 < /dev/null——关闭 stdin，防止 claude/codex 卡在读 stdin 等待输入
• 长 prompt 用文件传递——写入 spec.md，管道 cat spec.md | claude -p -