Orchestrix Guide — OpenClaw 操作手册

本文档是 OpenClaw 操控 Orchestrix Agent 的唯一操作手册。 严格按照本文档的阶段和协议执行，不得跳步。

---

一、架构与原理

CODEBLOCK0

关键约束：Claude Code (cc) 只接受终端标准输入。OpenClaw 唯一的操控方式是 tmux send-keys。

---

二、tmux 操作协议（铁律）

2.1 指令发送三步模式（MANDATORY）

向 Claude Code 发送任何内容时，必须严格执行三步。违反此规则会导致内容卡在输入框中不被提交。

CODEBLOCK1

绝对禁止：tmux send-keys -t $WIN "内容" Enter（合并写法）。Claude Code 的 TUI 需要 1 秒来处理粘贴文本，如果 Enter 到达时 TUI 还没准备好，内容会卡在输入框里。

多行内容发送

CODEBLOCK2

2.2 /clear 使用规则

不要每次切换 Agent 都 /clear。只在以下场景使用：

场景	是否需要 /clear
同一 Agent 连续对话中追加指令	❌ 不需要
切换到新 Agent（跨阶段重新激活）

✅ 需要 |
| Agent 加载失败，需要重试 | ✅ 需要 |
| Agent 卡住超过 5 分钟无输出 | ✅ 需要 |
| 错误恢复 | ✅ 需要 |

执行 /clear 的三步模式：
CODEBLOCK3

2.3 Agent 激活序列

当需要切换到新 Agent 时的完整流程：

CODEBLOCK4

2.4 等待时间参考

操作	等待时间	原因
INLINECODE4 启动后	12s	等待 Claude Code 初始化 + 信任对话框
INLINECODE5 后

2s | 等待上下文清空 | | /o {agent} 后 | 10-15s | 等待 Agent 通过 MCP 加载配置 | | *command 后 | 按完成检测 | 见下方 §2.5 |

2.5 任务完成检测（四级优先级）

Agent 任务执行时间不确定。按优先级依次尝试：

P1：检测完成消息（最高优先级）

CODEBLOCK5

这是最可靠的完成信号。

P2：检测预期输出文件

CODEBLOCK6

适用于有文件产出的任务（*create-doc *、*draft、*shard、*develop-story）。

P3：检测审批提示（自动处理）

CODEBLOCK7

检测到时自动发送 y + Enter：
CODEBLOCK8

P4：终端内容稳定性（兜底）

CODEBLOCK9

连续 3 次 hash 不变即判定完成（轮询间隔 30 秒，总计 90 秒稳定期）。

使用 monitor-agent.sh 脚本

项目内置了完成检测脚本，封装了以上 4 级检测：

CODEBLOCK10

参数：INLINECODE13

检测优先级总结

优先级	方法	模式	可靠性
P1	完成消息 INLINECODE14	所有场景	最高
P2

预期输出文件存在 | 有文件产出的任务 | 高 | | P3 | 审批提示 ◐ → 自动 y | 权限请求 | 高 | | P4 | 内容 hash 稳定（3×30s） | 兜底 | 中 |

建议组合：规划阶段用 P1 + P2 双重确认（或 monitor-agent.sh）；开发阶段由 handoff-detector.sh 自动处理。

2.6 信任对话框处理

Claude Code 在进入新项目目录时会弹出 "Do you trust this folder?" 确认框。

INLINECODE19 和 ensure-session.sh 已内置自动检测和接受逻辑：在 Claude Code 启动倒计时期间，每 2 秒扫描 pane 输出，检测到 "trust this folder" 或 "safety check" 时自动发送 Enter 接受。

---

三、全局流程总览

CODEBLOCK11

---

四、Phase A：规划阶段（单窗口模式）

规划阶段在一个 tmux 窗口中完成，通过逐个切换 Agent 生成全套规划文档。

4.0 启动 tmux 会话

CODEBLOCK12

4.1 Step 0: Analyst — 深化项目简报（可选）

此步骤可选。 docs/project-brief.md 已由 /create-project 生成初版。

CODEBLOCK13

预期产出：docs/project-brief.md（深化版）

4.2 Step 1: PM — 生成 PRD

这是规划阶段的必要起点。

CODEBLOCK14

预期产出：INLINECODE26

4.3 Step 2: UX Expert — 前端规格（可选）

仅当项目有前端需求时执行。 纯后端/CLI 项目跳过此步。

CODEBLOCK15

预期产出：INLINECODE27

4.4 Step 3: Architect — 架构文档

CODEBLOCK16

预期产出：INLINECODE28

4.5 Step 4: PO — 验证一致性 + 分片

规划阶段的最后一步。PO 需要连续执行两个命令。

CODEBLOCK17

预期产出：验证报告 + 分片后的上下文文件

4.6 规划完成

PO *shard 执行完毕后，规划阶段结束。销毁规划会话：

CODEBLOCK18

此时项目 docs/ 目录应包含：

• - project-brief.md — 深化后的项目简报
• INLINECODE32 — 产品需求文档
• INLINECODE33 — 前端规格（如适用）
• INLINECODE34 — 架构文档
• 分片上下文文件

✅ 规划完成。可以进入 Phase B 开发阶段。

4.7 OpenClaw 完整执行脚本（规划阶段）

CODEBLOCK19

---

五、Phase B：开发阶段（多窗口自动化）

开发阶段通过 tmux 多窗口模式运行，4 个 Agent 通过 HANDOFF 自动协作，无需人工切换。

5.1 前提条件

• - Phase A 规划阶段已完成（PO *shard 已执行）
• INLINECODE36 目录下有完整的规划文档

5.2 启动

CODEBLOCK20

脚本自动完成：

1. 1. 创建 tmux session：INLINECODE37
2. 创建 4 个窗口，每个窗口启动 INLINECODE38
3. 自动处理信任对话框（倒计时期间检测并接受）
4. 在每个窗口激活对应 Agent
5. 在 SM 窗口自动执行 *draft 开始第一个 Story

5.3 窗口布局

窗口	Agent	职责
INLINECODE40	Architect	技术审查、架构守护
INLINECODE41

SM | Story 创建、流程编排 | | 2 | Dev | 代码实现 | | 3 | QA | 代码审查、质量验证 |

5.4 HANDOFF 自动协作流程

CODEBLOCK21

INLINECODE44 自动完成：

• - 扫描所有窗口终端输出，检测 INLINECODE45
• 将命令发送到目标 Agent 的 tmux 窗口（使用三步模式）
• 在源 Agent 窗口执行 /clear + 重新加载 Agent
• Hash 去重 + 原子锁防止重复处理

5.5 监控

CODEBLOCK22

5.6 异常处理

情况	操作
Agent 卡住不输出 HANDOFF	三步清空重载：send-keys "/clear" → sleep 1 → Enter → sleep 2 → send-keys "/o {agent}" → sleep 1 → INLINECODE53
HANDOFF 没被检测到

tail -20 /tmp/orchestrix-{repo-id}-handoff.log 排查 | | 需要暂停 | tmux send-keys -t {session}:{window} C-c | | 需要恢复 | 三步发送：send-keys "*draft --continue" → sleep 1 → Enter | | 需要完全停止 | tmux kill-session -t orchestrix-{repo-id} |

5.7 并行扩展窗口（可选）

CODEBLOCK23

注意：动态窗口不参与 HANDOFF 自动协作，需 OpenClaw 自行管理生命周期。

---

六、Phase C：测试阶段

开发阶段所有 Story 完成后，逐个 Epic 进行冒烟测试。

6.1 冒烟测试流程

FOR EACH EPIC_ID in the epic list:

CODEBLOCK24

6.2 测试失败处理（最多 3 轮）

CODEBLOCK25

每个 Epic 最多 3 轮 fix-retest。仍失败则标记为 failed 并继续下一个 Epic。

---

七、补充流程

7.1 Solo 开发模式

跳过 Story/QA 关卡，适用于小型独立项目或快速原型。

CODEBLOCK26

7.2 Bug 修复

轻量修复（不需要 Story）：
CODEBLOCK27

正式修复（需要追踪）：
CODEBLOCK28

7.3 新迭代（Iteration）

MVP 完成后，基于反馈启动新一轮迭代。

CODEBLOCK29

7.4 需求变更管理

CODEBLOCK30

PO 根据变更类型自动路由：

• - 需求/范围变更 → PM (*revise-prd)
• 技术/架构变更 → Architect (*resolve-change)
• 两者都涉及 → 先 PM 再 Architect

7.5 Brownfield（已有项目增强）

变更规模	推荐方式
< 1h 快速修复	INLINECODE63 → INLINECODE64
< 4h 单功能

/o sm → *draft | | 4h-2d 小型增强 | /o sm → *draft（brownfield epic） | | > 2d 大型增强 | 走完整 Phase A → Phase B → Phase C 流程 |

对不熟悉的项目先摸底：/o architect → *document-project

---

八、Agent 命令速查表

规划阶段 Agent

Agent	ID	核心命令	产出
Analyst	INLINECODE71	INLINECODE72	INLINECODE73
PM

pm | *create-doc prd, *revise-prd, *start-iteration | docs/prd/*.md | | UX Expert | ux-expert | *create-doc front-end-spec | docs/front-end-spec*.md | | Architect | architect | *create-doc fullstack-architecture, *document-project | docs/architecture*.md | | PO | po | *execute-checklist po-master-validation, *shard | 验证报告 + 分片文件 |

开发阶段 Agent

Agent	ID	核心命令	产出
SM	INLINECODE89	INLINECODE90, INLINECODE91	INLINECODE92
Architect

architect | *review {story_id} | 技术审查意见 | | Dev | dev | *develop-story {story_id}, *solo "{desc}", *quick-fix "{desc}" | 代码 + git commit | | QA | qa | *review {story_id}, *smoke-test {epic_id} | 审查报告 |

管理 Agent

Agent	ID	核心命令
PO	INLINECODE102	INLINECODE103
Orchestrator

orchestrix-orchestrator | *status, *workflow-guidance |

---

九、Helper 脚本参考

项目创建后，以下脚本位于 .orchestrix-core/scripts/：

脚本	用途	用法
INLINECODE108	创建 4-window dev tmux session	INLINECODE109
INLINECODE110

懒创建 tmux session（已存在则复用） | SESSION=$(bash .../ensure-session.sh planning "$PROJECT_DIR") |
| monitor-agent.sh | 轮询 tmux pane 检测 agent 完成 | RESULT=$(bash .../monitor-agent.sh "$SESSION" 0 "docs/file.md" 30 30) |
| handoff-detector.sh | Claude Code Stop hook，自动路由 HANDOFF | 由 settings.local.json 自动触发 |

---

十、前置依赖

依赖	用途	安装
INLINECODE116 (Claude Code)	AI 编码环境	https://claude.ai/download
INLINECODE117

多窗口终端复用（必须） | brew install tmux |
| git | 版本控制 | 系统自带 |
| jq | JSON 处理（可选） | brew install jq |

别名配置（start-orchestrix.sh 依赖）：
CODEBLOCK31