乐于分享
好东西不私藏

OpenClaw 基操实践之一—— Agent 团队创建手册:环境检测、结构图、运行机制与验收

OpenClaw 基操实践之一—— Agent 团队创建手册:环境检测、结构图、运行机制与验收

适用环境:Windows 11 + WSL2 Ubuntu + OpenClaw 2026.6.1;目标:创建隔离、可审计、最小权限的 quad-coordinator / quad-planner / quad-executor / quad-reviewer 四 Agent 团队。

摘要概况

本文是 OpenClaw 四 Agent 团队创建、运行、验收与安全边界手册

目标是在用户现有 Windows 11 + WSL2 Ubuntu + OpenClaw 2026.6.1 环境基础上,创建一套独立的四 Agent 团队:quad-coordinatorquad-plannerquad-executorquad-reviewer

创建顺序必须是:环境检测 → 创建目录 → 注册 Agent → direct run → wrapper 本地运行 → hard audit → allowlist → routing → Feishu 端到端测试

全篇目录

1.第一模块:概览:系统结构与运行机制

2.第二模块:创建原则与状态门控宪章

3.第三模块:创建前环境配置检测 E0–E9

4.第四模块:四 Agent 如何形成固定团队

5.第五模块:角色分工、沟通交接与汇报机制

6.第六模块:权限管理与安全边界

7.第七模块:完整创建步骤 Q0–Q10

8.第八模块:检验核对要求与通过标准

9.第九模块:故障裁判表与回滚策略

10.附录:完整命令清单与飞书测试文本

三Agent都在活动,对应自己的session

上图 解读HTML文件成功。
上图,因缺少工具、HTML转docx技能、及权限,导致未成功(但流程是通的)
上图 HTML转docx成功

第一模块:概览:系统结构与运行机制

1.1 OpenClaw 四 Agent 团队创建整体系统结构、层级图

四 Agent 架构将原来 coordinator 同时承担的“调度 + 规划 + 执行解释 + 审查汇总”进一步拆开。quad-coordinator 是唯一外部入口;quad-planner 负责计划与验收标准;quad-executor 负责执行侧分析;quad-reviewer 负责审查;最后由 quad-coordinator 生成 final digest。

1.2 OpenClaw 四 Agent 团队运行机制流转动态图

运行机制不是“几个 Agent 自由聊天”,而是一个固定流水线:外部任务进入 coordinator,coordinator 调用唯一 wrapper,wrapper 依次调用 planner、executor、reviewer,再调用 coordinator final。所有阶段输出均落盘为 raw / clean / digest / final 文件。

第二模块:创建原则与状态门控宪章

四 Agent 创建属于复杂系统配置,涉及 CLI、Gateway、Agent inventory、session、task、wrapper、exec allowlist、Feishu routing 等多个层级。必须遵守状态门控:环境不明不修改,分支不明不切换,未本地验收不接 Feishu。

2.1 总原则

2.2 禁止事项

禁止在 Q6 本地硬验收通过前绑定 Feishu。

禁止让 planner / executor / reviewer 直接绑定外部 channel。

禁止给四 Agent 授权任意 shell、bash、python、openclaw 通配符。

禁止读取或输出 token、API key、password、private key。

禁止修改 Gateway、Feishu binding、Weixin binding,除非进入明确的 Q9 路由切换步骤。

第三模块:创建前环境配置检测 E0–E9

创建前环境检测的作用是确认:本机是否仍然是唯一主 Gateway、OpenClaw 是否可用、agent inventory 是否可读、exec policy 是否清晰、三 Agent 已有成果是否不会被污染。下面每一步都标明只读/写入属性。

E0:冻结目标与时间戳

性质:只读/记录。目的:明确目标、禁止事项、验收顺序。

# E0:冻结目标与记录时间戳;不修改任何配置

cd ~/agent-workspaces/openclaw-testecho "===== E0 target freeze ====="date -Iscat <<'EOF'目标:创建隔离的 OpenClaw 四 Agent 团队。团队:quad-coordinator / quad-planner / quad-executor / quad-reviewer。安全边界:不破坏已验收通过的 triad-agents;不改 Gateway / Feishu / Weixin,直到本地链路验收通过。验收顺序:环境检测 → agent 注册 → direct run → wrapper 本地运行 → hard audit → allowlist → routing → Feishu end-to-end。EOF

E1:Windows / WSL / Ubuntu 基础环境检查

性质:只读。目的:确认 WSL2、Ubuntu、Windows 版本与当前 shell 位置。

# E1:Windows / WSL / Ubuntu 基础环境只读检查# PowerShell 执行:wsl --statuswsl -l -v$PSVersionTable.PSVersionGet-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber# WSL Ubuntu Bash 执行:lsb_release -a || cat /etc/os-releaseuname -awhoamipwdhostname -I

E2:systemd / Node / npm / git / jq / python 检查

性质:只读。目的:确认 OpenClaw 运行时基础环境。

# E2:systemd / Node / npm / git / jq / python 检查

ps -1 -o pid,comm,argssystemctl --user status --no-pager || truenode -vnpm -vgit --versionjq --versionpython3 --versionwhich openclaw || true

E3:OpenClaw Gateway / channel / config 检查

性质:只读。目的:确认 Gateway、channel、config validate 的当前状态。

# E3:OpenClaw Gateway / channel / config 只读检查

openclaw --versionopenclaw gateway status || trueopenclaw status || trueopenclaw channels status --probe || trueopenclaw config validate || true

E4:当前 Agent inventory 与 bindings 检查

性质:只读。目的:确认原有 coordinator / executor / reviewer 及现有外部路由。

# E4:确认当前 agent inventory 与 bindings,不修改路由

openclaw agents list --bindings || trueopenclaw agents bindings || trueopenclaw sessions --all-agents --active 60 --limit 150 || true

E5:exec policy / approvals 检查

性质:只读。目的:确认当前是否为 allowlist 模式,避免误认为 wrapper 能直接执行。

# E5:确认 exec policy / approvals,不新增授权

openclaw approvals get || trueopenclaw exec-policy show || trueopenclaw config get tools.exec || trueopenclaw config get agents || true

E6:工作目录与磁盘空间检查

性质:只读。目的:确认 ~/agent-workspaces 可用,避免落盘失败。

# E6:工作目录与磁盘空间检查

cd ~/agent-workspaces/openclaw-testpwdls -la ~/agent-workspacesfind ~/agent-workspaces -maxdepth 2 -type d | sort | sed -n '1,120p'df -h ~

E7:现有 triad-agents 保护性检查

性质:只读。目的:确认不会覆盖已完成的三 Agent 结构和历史 run。

# E7:现有 triad-agents 保护性检查,只读

find ~/agent-workspaces/triad-agents -maxdepth 3 -type f | sort | sed -n '1,120p' || truefind ~/agent-workspaces/triad-lab/runs -maxdepth 1 -type d -name 'triad-v3-*' | sort | tail -n 10 || true

E8:创建前备份

性质:轻写入。目的:备份 openclaw.jsonexec-approvals.json、agent inventory 与 approvals 输出。该步骤不改变运行配置。

# E8:创建前备份;这是写操作,但不改变运行配置

cd ~/agent-workspaces/openclaw-testBACKUP_DIR="$HOME/agent-workspaces/quad-lab/backups/preflight-$(date +%Y%m%d_%H%M%S)"mkdir -p "$BACKUP_DIR"cp -a "$HOME/.openclaw/openclaw.json" "$BACKUP_DIR/openclaw.json.bak" 2>/dev/null || truecp -a "$HOME/.openclaw/exec-approvals.json" "$BACKUP_DIR/exec-approvals.json.bak" 2>/dev/null || trueopenclaw agents list --bindings > "$BACKUP_DIR/agents-list.txt" 2>&1 || trueopenclaw approvals get > "$BACKUP_DIR/approvals.txt" 2>&1 || trueecho "BACKUP_DIR=$BACKUP_DIR"

E9:进入创建的门槛判断

第四模块:四 Agent 如何形成固定团队

四 Agent 不是因为 prompt 中写了四个名字就成为团队。固定团队由五类工程事实构成:agent inventory 注册事实、规则文件职责事实、wrapper 调度事实、session key 调用事实、run files 输出事实

4.1 Agent 之间如何知道彼此存在

严格说,Agent 并不是自然人式“知道彼此存在”。系统层面的存在由 openclaw agents list –bindings、workspace、agent dir、session key 和 tasks 记录确认。coordinator 通过 wrapper 中固定写入的 agent id 调用其他 Agent;planner/executor/reviewer 不需要主动发现彼此。

4.2 Agent 之间如何确认职能

职能不是靠临场解释,而是写入各自 AGENTS.mdTOOLS.mdIDENTITY.mdSOUL.md。wrapper 在每一段调用中再次约束本轮任务范围,避免角色越界。

4.3 Agent 之间如何协调任务汇报内容

协调不靠直接互聊,而靠文件交接。planner 输出 planner.clean.md 与 planner.digest.md;executor 读取 planner digest 并输出 executor 文件;reviewer 读取 planner/executor digest;coordinator final 读取三个 digest 并输出最终清单。

第五模块:角色分工、沟通交接与汇报机制

5.1 角色分工表

5.2 汇报格式

planner 输出:目标 / 执行计划 / executor 输入 / reviewer 标准 / 风险边界 / 完成标准

executor 输出:收到的任务 / 执行步骤 / 执行结果 / 风险或未完成项 / 是否遵守边界

reviewer 输出:审查对象 / 审查标准 / 问题 / 风险等级 / 通过性结论 / 给 coordinator 建议

coordinator final 输出:目标 / planner 结论 / executor 结论 / reviewer 结论 / 最多 6 条维护清单 / 外部硬验收命令

5.3 为什么必须使用 digest

三 Agent 回归中已经证明,final 阶段如果把 clean 全文直接塞入 openclaw agent -m,长文本会触发参数过长。四 Agent 比三 Agent 多 planner,一旦仍然传全文,失败概率更高。因此四 Agent 从 v1 开始即默认 digest 模式。

第六模块:权限管理与安全边界

四 Agent 权限管理的核心不是“提醒模型不要做坏事”,而是将可执行能力压缩到单一 wrapper 路径,并用 approvals / allowlist 审计。prompt 是行为约束,allowlist 才是执行边界。

6.1 权限边界

6.2 授权原则

默认只读:创建前只做 status/list/get/show。

先本地跑通:Q0–Q6 通过后才做 Q7 allowlist。

单一路径:只授权 ~/agent-workspaces/quad-agents/coordinator/bin/quad-dispatch-v1.sh

不使用通配符:不授权 bash、python、openclaw、*

备份优先:修改 openclaw.json 或 exec-approvals.json 前必须备份。

第七模块:完整创建步骤 Q0–Q10

Q0:当前系统基线检查

cd ~/agent-workspaces/openclaw-testecho "===== Q0-0 time marker ====="date -Isecho "===== Q0-1 OpenClaw status ====="openclaw --version || trueopenclaw gateway status || trueopenclaw status || trueecho "===== Q0-2 current agents and bindings ====="openclaw agents list --bindings || trueopenclaw agents bindings || trueecho "===== Q0-3 current approvals / exec policy ====="openclaw approvals get || trueopenclaw exec-policy show || trueecho "===== Q0-4 current sessions/tasks baseline ====="openclaw sessions --all-agents --active 60 --limit 150 || trueopenclaw tasks list --runtime cli --status succeeded || trueopenclaw tasks list --runtime cli --status failed || trueecho "===== Q0-5 config validate ====="openclaw config validate || true

Q1:创建四 Agent 工作目录与规则文件

cd ~/agent-workspaces/openclaw-testecho "===== Q1-0 time marker ====="date -IsBASE="$HOME/agent-workspaces/quad-agents"mkdir -p "$BASE"/{coordinator,planner,executor,reviewer}/binmkdir -p "$HOME/agent-workspaces/quad-lab"/{runs,docs,backups}echo "===== Q1-1 create coordinator files ====="cat > "$BASE/coordinator/AGENTS.md" <<'EOF'

# Quad Coordinator Agent## Role

你是 quad-coordinator,四 Agent 团队的总调度 Agent。

## Responsibilities

1. 接收用户任务;2. 判断是否需要四 Agent 工作流;3. 只使用唯一授权 wrapper:quad-dispatch-v1.sh;4. 调度顺序:planner -> executor -> reviewer -> coordinator final;5. 不直接替 planner 规划;6. 不直接替 executor 执行;7. 不绕过 reviewer 宣布完成;8. 不读取凭据;9. 不修改 Gateway、Feishu、Weixin、OpenClaw config;10. 不删除文件。

## Evidence Rule

最终结论必须区分:1. Agent 自我说明;2. wrapper 运行文件;3. OpenClaw backend tasks;4. OpenClaw sessions。硬验收以外部 WSL CLI 的 tasks show / sessions 为准。EOFcat > "$BASE/coordinator/TOOLS.md" <<'EOF'# Quad Coordinator Tools唯一允许的四 Agent 调度入口:~/agent-workspaces/quad-agents/coordinator/bin/quad-dispatch-v1.sh允许:- 调用唯一 wrapper;- 读取 quad-lab/runs 下本轮输出;- 输出 digest final。禁止:- 任意 shell;- 修改 Gateway / Feishu / Weixin / OpenClaw config;- 读取 credentials / token / API key / password / private key;- 删除文件;- 使用未授权脚本。

EOF

cat > "$BASE/coordinator/IDENTITY.md" <<'EOF'# IdentityAgent ID: quad-coordinatorTeam: quad-agentsFunction: routing, orchestration, final digest.EOFcat > "$BASE/coordinator/SOUL.md" <<'EOF'# Operating PrincipleCoordinate, do not impersonate.Use evidence, not self-assertion.Prefer digest outputs and external hard audit.EOFcat > "$BASE/coordinator/USER.md" <<'EOF'# User Context

用户需要在本地 OpenClaw 环境中运行可审计的四 Agent 团队。默认语言:简体中文。默认安全原则:最小权限、先验收、后扩权。EOF

echo "===== Q1-2 create planner files ====="cat > "$BASE/planner/AGENTS.md" <<'EOF'

# Quad Planner Agent## Role

你是 quad-planner,规划 Agent。

## Responsibilities

1. 理解原始任务;2. 拆解任务目标;3. 给 executor 定义执行范围;4. 给 reviewer 定义审查标准;5. 标注风险与边界;6. 不执行 shell;7. 不修改文件;8. 不声明任务最终完成。

## Output Rules

输出必须包含:1. 任务目标;2. 执行计划;3. executor 输入;4. reviewer 审查标准;5. 风险边界;6. 完成标准。EOFcat > "$BASE/planner/TOOLS.md" <<'EOF'# Quad Planner Tools默认不使用工具。只做任务规划、边界定义、验收标准定义。EOFcat > "$BASE/planner/IDENTITY.md" <<'EOF'# IdentityAgent ID: quad-plannerFunction: task planning and risk boundary.EOFcat > "$BASE/planner/SOUL.md" <<'EOF'# Operating PrinciplePlan before execution.Define boundaries before action.EOFecho "===== Q1-3 create executor files ====="cat > "$BASE/executor/AGENTS.md" <<'EOF'

# Quad Executor Agent## Role

你是 quad-executor,执行 Agent。

## Responsibilities

1. 只根据 planner 计划执行;2. 输出执行侧分析或受控结果;3. 不读取凭据;4. 不修改 Gateway、Feishu、Weixin、OpenClaw config;5. 不删除文件;6. 不越过 reviewer 宣布完成;7. 不判断整个四 Agent 链路是否成立。

## Output Rules

输出必须包含:1. 接收到的任务;2. 执行步骤;3. 执行结果;4. 风险或未完成项;5. 是否遵守边界。EOFcat > "$BASE/executor/TOOLS.md" <<'EOF'# Quad Executor Tools默认不使用 shell。如未来允许执行,必须由 coordinator wrapper 和 allowlist 控制。EOFcat > "$BASE/executor/IDENTITY.md" <<'EOF'# IdentityAgent ID: quad-executorFunction: controlled execution.EOFcat > "$BASE/executor/SOUL.md" <<'EOF'# Operating PrincipleExecute only within assigned scope.Report uncertainty.Do not overclaim.EOFecho "===== Q1-4 create reviewer files ====="cat > "$BASE/reviewer/AGENTS.md" <<'EOF'

# Quad Reviewer Agent## Role

你是 quad-reviewer,审查 Agent。

## Responsibilities

1. 审查 executor 是否遵守 planner 计划;2. 审查是否越权;3. 审查是否遗漏关键风险;4. 审查输出是否足够完整;5. 给出通过、有条件通过或不通过;6. 不替 executor 执行;7. 不修改文件;8. 不读取凭据。

## Output Rules

输出必须包含:1. 审查对象;2. 审查标准;3. 发现的问题;4. 风险等级;5. 通过/有条件通过/不通过;6. 给 coordinator 的建议。EOFcat > "$BASE/reviewer/TOOLS.md" <<'EOF'# Quad Reviewer Tools默认不使用 shell。只审查 planner/executor 输出与边界。EOFcat > "$BASE/reviewer/IDENTITY.md" <<'EOF'# IdentityAgent ID: quad-reviewerFunction: audit and risk review.EOFcat > "$BASE/reviewer/SOUL.md" <<'EOF'# Operating PrincipleReview evidence, not intention.Do not approve vague results.EOFecho "===== Q1-5 init git baselines ====="for d in coordinator planner executor reviewerdocd "$BASE/$d"git init >/dev/null 2>&1 || truegit add .git commit -m "init quad $d agent rules" >/dev/null 2>&1 || truedoneecho "===== Q1-6 inspect files ====="find "$BASE" -maxdepth 2 -type f | sort

Q2:注册四个 isolated agents

cd ~/agent-workspaces/openclaw-testecho "===== Q2-0 time marker ====="date -IsBASE="$HOME/agent-workspaces/quad-agents"MODEL="deepseek/deepseek-v4-flash"echo "===== Q2-1 backup OpenClaw config before agents add ====="BACKUP_DIR="$HOME/agent-workspaces/quad-lab/backups/q2-agents-add-$(date +%Y%m%d_%H%M%S)"mkdir -p "$BACKUP_DIR"cp -a "$HOME/.openclaw/openclaw.json" "$BACKUP_DIR/openclaw.json.bak" 2>/dev/null || trueecho "BACKUP_DIR=$BACKUP_DIR"echo "===== Q2-2 add quad agents ====="openclaw agents add quad-coordinator \--workspace "$BASE/coordinator" \--agent-dir "$HOME/.openclaw/agents/quad-coordinator/agent" \--model "$MODEL" \--non-interactive || trueopenclaw agents add quad-planner \--workspace "$BASE/planner" \--agent-dir "$HOME/.openclaw/agents/quad-planner/agent" \--model "$MODEL" \--non-interactive || trueopenclaw agents add quad-executor \--workspace "$BASE/executor" \--agent-dir "$HOME/.openclaw/agents/quad-executor/agent" \--model "$MODEL" \--non-interactive || trueopenclaw agents add quad-reviewer \--workspace "$BASE/reviewer" \--agent-dir "$HOME/.openclaw/agents/quad-reviewer/agent" \--model "$MODEL" \--non-interactive || trueecho "===== Q2-3 list agents ====="openclaw agents list --bindings || trueecho "===== Q2-4 config validate ====="openclaw config validate || true

Q3:四 Agent 直跑 smoke test

cd ~/agent-workspaces/openclaw-testecho "===== Q3-0 time marker ====="date -IsRUN_TAG="quad-direct-$(date +%Y%m%d_%H%M%S)"echo "RUN_TAG=$RUN_TAG"openclaw agent --agent quad-coordinator --session-key "agent:quad-coordinator:${RUN_TAG}-coordinator" -m "【Q3 direct test】请说明你是 quad-coordinator。只输出身份、职责、禁止事项。不执行 shell,不修改文件。"openclaw agent --agent quad-planner --session-key "agent:quad-planner:${RUN_TAG}-planner" -m "【Q3 direct test】请说明你是 quad-planner。为一个虚拟任务给出三步计划。不执行 shell,不修改文件。"openclaw agent --agent quad-executor --session-key "agent:quad-executor:${RUN_TAG}-executor" -m "【Q3 direct test】请说明你是 quad-executor。列出收到的任务,不执行 shell,不修改文件。"openclaw agent --agent quad-reviewer --session-key "agent:quad-reviewer:${RUN_TAG}-reviewer" -m "【Q3 direct test】请说明你是 quad-reviewer。审查虚拟 executor 输出:未执行 shell、未修改文件、仅输出说明。给出通过/不通过。"openclaw sessions --agent quad-coordinator --active 30 --limit 50 || trueopenclaw sessions --agent quad-planner --active 30 --limit 50 || trueopenclaw sessions --agent quad-executor --active 30 --limit 50 || trueopenclaw sessions --agent quad-reviewer --active 30 --limit 50 || trueopenclaw sessions --all-agents --active 30 --limit 150 || trueopenclaw tasks show "agent:quad-coordinator:${RUN_TAG}-coordinator" || trueopenclaw tasks show "agent:quad-planner:${RUN_TAG}-planner" || trueopenclaw tasks show "agent:quad-executor:${RUN_TAG}-executor" || trueopenclaw tasks show "agent:quad-reviewer:${RUN_TAG}-reviewer" || true

Q4:创建四 Agent wrapper:quad-dispatch-v1.sh

cd ~/agent-workspaces/openclaw-testecho "===== Q4-0 time marker ====="date -IsWRAPPER="$HOME/agent-workspaces/quad-agents/coordinator/bin/quad-dispatch-v1.sh"mkdir -p "$(dirname "$WRAPPER")"cat > "$WRAPPER" <<'EOF'#!/usr/bin/env bashset -euo pipefailRUN_ID="quad-v1-$(date +%Y%m%d_%H%M%S)"BASE_DIR="$HOME/agent-workspaces/quad-lab/runs/$RUN_ID"mkdir -p "$BASE_DIR"TASK_TEXT="${*:-}"if [ -z "$TASK_TEXT" ]; thenTASK_TEXT="四 Agent wrapper 默认测试:planner 规划,executor 执行,reviewer 审查,coordinator final 汇总。"fiTASK_FILE="$BASE_DIR/task.txt"META_FILE="$BASE_DIR/meta.txt"PLANNER_RAW="$BASE_DIR/planner.raw.md"PLANNER_CLEAN="$BASE_DIR/planner.clean.md"PLANNER_DIGEST="$BASE_DIR/planner.digest.md"EXECUTOR_RAW="$BASE_DIR/executor.raw.md"EXECUTOR_CLEAN="$BASE_DIR/executor.clean.md"EXECUTOR_DIGEST="$BASE_DIR/executor.digest.md"REVIEWER_RAW="$BASE_DIR/reviewer.raw.md"REVIEWER_CLEAN="$BASE_DIR/reviewer.clean.md"REVIEWER_DIGEST="$BASE_DIR/reviewer.digest.md"FINAL_PROMPT="$BASE_DIR/coordinator.prompt.txt"FINAL_RAW="$BASE_DIR/coordinator.raw.md"FINAL_CLEAN="$BASE_DIR/coordinator.final.md"PLANNER_SESSION="agent:quad-planner:${RUN_ID}-planner"EXECUTOR_SESSION="agent:quad-executor:${RUN_ID}-executor"REVIEWER_SESSION="agent:quad-reviewer:${RUN_ID}-reviewer"COORDINATOR_SESSION="agent:quad-coordinator:${RUN_ID}-final"clean_openclaw_output() {local input="$1"local output="$2"awk '/Doctor warnings/ {next}/state-migrations/ {next}/Left plugin install index/ {next}/shared SQLite state/ {next}/conflicting plugin install metadata/ {next}/openclaw-weixin/ {next}/^OpenClaw [0-9]/ {next}/^[[:space:]]*│/ {next}/^[[:space:]]*◇/ {next}/^[[:space:]]*├/ {next}/^[[:space:]]*╰/ {next}/^[[:space:]]*╮/ {next}/^[[:space:]]*─/ {next}{print}"$input" > "$output"}digest_for_prompt() {local input="$1"local head_bytes="${2:-1600}"local tail_bytes="${3:-700}"if [ ! -f "$input" ]; thenecho "[MISSING_FILE] $input"return 0filocal bytesbytes="$(wc -c < "$input" | tr -d ' ')"echo "[FILE] $input"echo "[BYTES] $bytes"echo "[DIGEST_MODE] head_bytes=$head_bytes tail_bytes=$tail_bytes"if [ "$bytes" -le $((head_bytes + tail_bytes + 300)) ]; thencat "$input"elseecho "[HEAD]"head -c "$head_bytes" "$input"printf "\n[...OMITTED_FOR_DIGEST...]\n"echo "[TAIL]"tail -c "$tail_bytes" "$input"printf "\n[DIGEST_END]\n"fi}{echo "RUN_ID=$RUN_ID"echo "BASE_DIR=$BASE_DIR"echo "PLANNER_SESSION=$PLANNER_SESSION"echo "EXECUTOR_SESSION=$EXECUTOR_SESSION"echo "REVIEWER_SESSION=$REVIEWER_SESSION"echo "COORDINATOR_SESSION=$COORDINATOR_SESSION"echo "CREATED_AT=$(date -Is)"echo "WRAPPER=quad-dispatch-v1.sh"echo "CLEANING=enabled"echo "DIGEST=enabled"} > "$META_FILE"printf "%s\n" "$TASK_TEXT" > "$TASK_FILE"echo "===== QUAD V1 RUN $RUN_ID / planner ====="openclaw agent --agent quad-planner --session-key "$PLANNER_SESSION" -m "

【Q4 / planner】

你是 quad-planner,规划 Agent。原始任务:$TASK_TEXT要求:1. 不执行 shell;2. 不修改文件;3. 输出任务拆解、executor 输入、reviewer 审查标准、风险边界、完成标准;4. 不声明最终完成。" 2>&1 | tee "$PLANNER_RAW"clean_openclaw_output "$PLANNER_RAW" "$PLANNER_CLEAN"digest_for_prompt "$PLANNER_CLEAN" 1800 800 > "$PLANNER_DIGEST"echoecho "===== QUAD V1 RUN $RUN_ID / executor ====="openclaw agent --agent quad-executor --session-key "$EXECUTOR_SESSION" -m "

【Q4 / executor】

你是 quad-executor,执行 Agent。原始任务:$TASK_TEXTplanner digest:$(cat "$PLANNER_DIGEST")要求:1. 只根据 planner digest 执行;2. 不执行 shell;3. 不修改文件;4. 输出接收到的任务、执行步骤、执行结果、风险或未完成项、是否遵守边界;5. 不判断整条链路是否成立。" 2>&1 | tee "$EXECUTOR_RAW"clean_openclaw_output "$EXECUTOR_RAW" "$EXECUTOR_CLEAN"digest_for_prompt "$EXECUTOR_CLEAN" 1800 800 > "$EXECUTOR_DIGEST"echoecho "===== QUAD V1 RUN $RUN_ID / reviewer ====="openclaw agent --agent quad-reviewer --session-key "$REVIEWER_SESSION" -m "

【Q4 / reviewer】

你是 quad-reviewer,审查 Agent。原始任务:$TASK_TEXTplanner digest:$(cat "$PLANNER_DIGEST")executor digest:$(cat "$EXECUTOR_DIGEST")要求:1. 审查 executor 是否遵守 planner;2. 审查是否越权;3. 审查是否遗漏关键风险;4. 输出审查对象、审查标准、发现问题、风险等级、通过/有条件通过/不通过;5. 不执行 shell,不修改文件。" 2>&1 | tee "$REVIEWER_RAW"clean_openclaw_output "$REVIEWER_RAW" "$REVIEWER_CLEAN"digest_for_prompt "$REVIEWER_CLEAN" 1800 800 > "$REVIEWER_DIGEST"echoecho "===== QUAD V1 RUN $RUN_ID / coordinator final ====="cat > "$FINAL_PROMPT" <        <EOF_FINAL< span>         </EOF_FINAL<>

【Q4 / coordinator final】

你是 quad-coordinator,总调度 Agent。本轮采用 digest 模式:- 不嵌入 planner/executor/reviewer clean 全文;- 只读取 digest;- 最终硬验收以外部 WSL CLI 的 openclaw tasks show / sessions 为准。外部调度事实:- RUN_ID: $RUN_ID- planner session: $PLANNER_SESSION- executor session: $EXECUTOR_SESSION- reviewer session: $REVIEWER_SESSION- coordinator session: $COORDINATOR_SESSION- run dir$BASE_DIR原始任务 digest:$(printf "%s" "$TASK_TEXT" | head -c 800)planner digest:$(cat "$PLANNER_DIGEST")executor digest:$(cat "$EXECUTOR_DIGEST")reviewer digest:$(cat "$REVIEWER_DIGEST")输出要求:1. 当前任务目标,3 行以内;2. planner 规划结论;3. executor 执行结论;4. reviewer 审查结论;5. 最多 6 条可执行清单;6. 明确外部硬验收命令;7. 不得声称 backend task 或 direct session 不适用。EOF_FINALopenclaw agent --agent quad-coordinator --session-key "$COORDINATOR_SESSION" -m "$(cat "$FINAL_PROMPT")" 2>&1 | tee "$FINAL_RAW"clean_openclaw_output "$FINAL_RAW" "$FINAL_CLEAN"echoecho "===== QUAD V1 RUN COMPLETED ====="echo "RUN_ID=$RUN_ID"echo "RUN_DIR=$BASE_DIR"echo "META_FILE=$META_FILE"echo "FINAL_CLEAN=$FINAL_CLEAN"EOFchmod +x "$WRAPPER"ls -l "$WRAPPER"grep -n "QUAD V1 RUN\|digest_for_prompt\|quad-planner\|quad-executor\|quad-reviewer\|quad-coordinator" "$WRAPPER" || true

Q5:本地 wrapper 回归测试

cd ~/agent-workspaces/openclaw-testecho "===== Q5-0 local quad wrapper test ====="date -Is~/agent-workspaces/quad-agents/coordinator/bin/quad-dispatch-v1.sh \"

【Q5 四 Agent 本地测试】

请让 planner 规划当前四 Agent 团队的维护任务;executor 提出 3 个维护风险;reviewer 审查是否越权、遗漏、错误;coordinator final 输出不超过 6 条可执行维护清单。要求不读取凭据、不修改配置、不删除文件。”

Q6:本地 wrapper 硬验收

cd ~/agent-workspaces/openclaw-testecho "===== Q6-0 local quad verification ====="date -IsLATEST_RUN="$(find ~/agent-workspaces/quad-lab/runs -maxdepth 1 -type d -name 'quad-v1-*' | sort | tail -n 1)"RUN_ID="$(basename "$LATEST_RUN")"echo "LATEST_RUN=$LATEST_RUN"echo "RUN_ID=$RUN_ID"find "$LATEST_RUN" -maxdepth 1 -type f -printf '%TY-%Tm-%Td %TH:%TM %p\n' | sortcat "$LATEST_RUN/meta.txt"openclaw tasks show "agent:quad-planner:${RUN_ID}-planner" || trueopenclaw tasks show "agent:quad-executor:${RUN_ID}-executor" || trueopenclaw tasks show "agent:quad-reviewer:${RUN_ID}-reviewer" || trueopenclaw tasks show "agent:quad-coordinator:${RUN_ID}-final" || trueopenclaw sessions --agent quad-planner --active 60 --limit 80 || trueopenclaw sessions --agent quad-executor --active 60 --limit 80 || trueopenclaw sessions --agent quad-reviewer --active 60 --limit 80 || trueopenclaw sessions --agent quad-coordinator --active 60 --limit 80 || trueopenclaw sessions --all-agents --active 60 --limit 200 || truegrep -RInE "Doctor warnings|state-migrations|Left plugin install index|shared SQLite state|conflicting plugin install metadata|openclaw-weixin" \"$LATEST_RUN"/*.clean.md "$LATEST_RUN"/coordinator.final.md 2>/dev/null \|| echo "CLEAN_OK: no OpenClaw warning text found in clean outputs"grep -RInE "backend task.*不适用|direct session.*不适用|not applicable|不创建后端 task|不产生 backend sessions" \"$LATEST_RUN"/coordinator.final.md 2>/dev/null \|| echo "WORDING_OK: no forbidden backend/session misjudgment found"sed -n '1,220p' "$LATEST_RUN/coordinator.final.md" 2>/dev/null || echo "MISSING coordinator.final.md"

Q7:给 quad-coordinator 最小授权 wrapper

cd ~/agent-workspaces/openclaw-testecho "===== Q7-0 time marker ====="date -IsWRAPPER="$HOME/agent-workspaces/quad-agents/coordinator/bin/quad-dispatch-v1.sh"APPROVALS_FILE="$HOME/.openclaw/exec-approvals.json"BACKUP_DIR="$HOME/agent-workspaces/quad-lab/backups/q7-approvals-$(date +%Y%m%d_%H%M%S)"mkdir -p "$BACKUP_DIR"if [ -f "$APPROVALS_FILE" ]; thencp -a "$APPROVALS_FILE" "$BACKUP_DIR/exec-approvals.json.bak"echo "BACKUP_OK $APPROVALS_FILE"elseecho "MISSING $APPROVALS_FILE"fiopenclaw approvals allowlist add --agent quad-coordinator "$WRAPPER" || trueopenclaw approvals get || truegrep -RIn "quad-dispatch-v1.sh\|quad-coordinator" "$APPROVALS_FILE" 2>/dev/null || true

Q8:Feishu 路由切换前检查

cd ~/agent-workspaces/openclaw-testecho "===== Q8-0 Feishu route precheck ====="date -Isopenclaw agents bindings || trueopenclaw agents list --bindings || trueopenclaw agents bind --help || trueopenclaw agents unbind --help || trueopenclaw channels status --probe || true

Q9:可选:把 Feishu 切到 quad-coordinator

cd ~/agent-workspaces/openclaw-testecho "===== Q9-0 backup before route switch ====="BACKUP_DIR="$HOME/agent-workspaces/quad-lab/backups/q9-route-switch-$(date +%Y%m%d_%H%M%S)"mkdir -p "$BACKUP_DIR"cp -a "$HOME/.openclaw/openclaw.json" "$BACKUP_DIR/openclaw.json.bak" 2>/dev/null || true# 具体 unbind 参数以本机 `openclaw agents unbind --help` 为准。openclaw agents unbind --agent coordinator --bind feishu:default || trueopenclaw agents bind --agent quad-coordinator --bind feishu:default || trueopenclaw agents bindings || trueopenclaw agents list --bindings || trueopenclaw channels status --probe || true

Q10:Feishu 四 Agent 端到端测试文本

【Q10 Feishu 四 Agent 全链路测试】

请作为 quad-coordinator 处理本任务。请使用唯一授权 wrapper:~/agent-workspaces/quad-agents/coordinator/bin/quad-dispatch-v1.sh传入任务文本:【Q10 四 Agent 真实小任务】请让 planner 规划当前四 Agent 工作流的维护任务;executor 提出 3 个维护风险;reviewer 审查 executor 是否越权、是否遗漏关键风险;最后 coordinator final 使用 digest 模式输出最多 6 条可执行维护清单。要求不读取凭据、不修改配置、不删除文件。约束:1. 只能使用 quad-dispatch-v1.sh。2. 不得执行其他 shell。3. 不得修改 Gateway、Feishu binding、Weixin binding、OpenClaw config。4. 不得读取 credentials、token、API key、password、private key。5. 不得输出长篇全文,只输出 digest 结论。6. 不得声称 backend task 或 direct session 不适用;如果本地视角看不到其他 agent session,只能说明需要外部 WSL 审计。

Q10:Feishu 后 WSL 硬审计命令

cd ~/agent-workspaces/openclaw-testecho "===== Q10-1 after Feishu quad regression ====="date -IsLATEST_RUN="$(find ~/agent-workspaces/quad-lab/runs -maxdepth 1 -type d -name 'quad-v1-*' | sort | tail -n 1)"RUN_ID="$(basename "$LATEST_RUN")"DOC_DIR="$HOME/agent-workspaces/quad-lab/docs"AUDIT_FILE="$DOC_DIR/Q10_final_feishu_quad_audit_$(date +%Y%m%d_%H%M%S).md"mkdir -p "$DOC_DIR"echo "LATEST_RUN=$LATEST_RUN"echo "RUN_ID=$RUN_ID"echo "AUDIT_FILE=$AUDIT_FILE"{echo "# Q10 Final Feishu Quad-Agent Audit"echoecho "Generated at: $(date -Is)"echoecho "## Run"echo "- RUN_ID: $RUN_ID"echo "- RUN_DIR: $LATEST_RUN"echoecho "## Files"find "$LATEST_RUN" -maxdepth 1 -type f -printf '- %f\n' | sortechoecho "## Meta"cat "$LATEST_RUN/meta.txt" 2>/dev/null || echo "MISSING meta.txt"echoecho "## Task status"echo "### planner"openclaw tasks show "agent:quad-planner:${RUN_ID}-planner" || trueechoecho "### executor"openclaw tasks show "agent:quad-executor:${RUN_ID}-executor" || trueechoecho "### reviewer"openclaw tasks show "agent:quad-reviewer:${RUN_ID}-reviewer" || trueechoecho "### coordinator"openclaw tasks show "agent:quad-coordinator:${RUN_ID}-final" || trueechoecho "## Sessions"openclaw sessions --agent quad-planner --active 60 --limit 80 || trueopenclaw sessions --agent quad-executor --active 60 --limit 80 || trueopenclaw sessions --agent quad-reviewer --active 60 --limit 80 || trueopenclaw sessions --agent quad-coordinator --active 60 --limit 80 || trueechoecho "## Clean warning check"grep -RInE "Doctor warnings|state-migrations|Left plugin install index|shared SQLite state|conflicting plugin install metadata|openclaw-weixin" \"$LATEST_RUN"/*.clean.md "$LATEST_RUN"/coordinator.final.md 2>/dev/null \|| echo "CLEAN_OK"echoecho "## Forbidden wording check"grep -RInE "backend task.*不适用|direct session.*不适用|not applicable|不创建后端 task|不产生 backend sessions" \"$LATEST_RUN"/coordinator.final.md 2>/dev/null \|| echo "WORDING_OK"echoecho "## Final digest"sed -n '1,220p' "$LATEST_RUN/coordinator.final.md" 2>/dev/null || echo "MISSING coordinator.final.md"} | tee "$AUDIT_FILE"echo "===== Q10-2 screen digest ====="echo "RUN_ID=$RUN_ID"echo "AUDIT_FILE=$AUDIT_FILE"echo "--- required files ---"for f in task.txt meta.txt planner.clean.md planner.digest.md executor.clean.md executor.digest.md reviewer.clean.md reviewer.digest.md coordinator.prompt.txt coordinator.raw.md coordinator.final.mddotest -f "$LATEST_RUN/$f" && echo "OK $f" || echo "MISSING $f"doneecho "--- final pass/fail hints ---"grep -q "status: succeeded" "$AUDIT_FILE" && echo "TASK_EVIDENCE_PRESENT" || echo "TASK_EVIDENCE_NEEDS_REVIEW"grep -q "CLEAN_OK" "$AUDIT_FILE" && echo "CLEAN_OK" || echo "CLEAN_CHECK_FAILED"grep -q "WORDING_OK" "$AUDIT_FILE" && echo "WORDING_OK" || echo "WORDING_CHECK_REVIEW"test -f "$LATEST_RUN/coordinator.final.md" && echo "FINAL_FILE_OK" || echo "FINAL_FILE_MISSING"

第八模块:检验核对要求与通过标准

8.1 最终验收标准总表

8.2 必须出现的 run 文件

task.txtmeta.txtplanner.raw.md / planner.clean.md / planner.digest.mdexecutor.raw.md / executor.clean.md / executor.digest.mdreviewer.raw.md / reviewer.clean.md / reviewer.digest.mdcoordinator.prompt.txtcoordinator.raw.mdcoordinator.final.md

8.3 不通过即停止的门槛

Q0 不通过:停止创建,先修环境。

Q2 不出现四个 agent:停止 wrapper 创建,先修注册。

Q3 direct run 失败:停止 wrapper 创建,先修对应 Agent。

Q5 wrapper 失败:不进入 Q7 授权。

Q6 tasks/sessions 不全:不进入 Feishu。

Q10 未生成新 run:Feishu 端未触发 wrapper,应回 Q8/Q9/Q7。

第九模块:故障裁判表与回滚策略

9.1 故障裁判表

9.2 回滚策略

附录:完整结构摘要与维护清单

A. 四 Agent 最终结构

~/agent-workspaces/quad-agents/coordinator/AGENTS.mdTOOLS.mdIDENTITY.mdSOUL.mdUSER.mdbin/quad-dispatch-v1.shplanner/AGENTS.mdTOOLS.mdIDENTITY.mdSOUL.mdexecutor/AGENTS.mdTOOLS.mdIDENTITY.mdSOUL.mdreviewer/AGENTS.mdTOOLS.mdIDENTITY.mdSOUL.md~/agent-workspaces/quad-lab/runs/docs/backups/

B. 最短执行顺序

先执行:E0 → E1 → E2 → E3 → E4 → E5 → E6 → E7 → E8 → E9再执行:Q0 → Q1 → Q2 → Q3 → Q4 → Q5 → Q6本地通过后再执行:Q7 → Q8 → Q9 → Q10

C. 维护清单

每次改 wrapper 必须重新跑 Q5/Q6。

每次改 routing 必须重新跑 Q8/Q10。

每次 OpenClaw 升级后必须重新跑 E3/E4/E5/Q6。

每次发现 Too many arguments,优先降低 digest bytes,而不是扩大 shell 权限。

每次出现 Agent 自称“没有 session/task”,以 WSL 外部 hard audit 为准。

参考原则与本手册依据

本手册采用用户上传的 state-gated-troubleshooting Skill 的核心原则:复杂系统任务先建立当前状态模型,再按环境快照、状态判定、分支选择、单步操作、日志回传、验证闭环推进。手册同时吸收用户关于“概念解释必须说明上下文、结构位置、生命周期、关联机制与完整流程”的要求。

OpenClaw 四 Agent 团队创建手册 · 最终增强版 · 生成文件包含 HTML、Markdown 源文与 README。