多Agent协作配置引导

总体流程

严格按顺序执行7个阶段，不得跳过或并行：

Phase 0 环境检测 → Phase 1 规划 → Phase 2 确认 → Phase 3 备份 → Phase 4 实施 → Phase 5 测试 → Phase 6 委派逻辑

核心原则：不检测不动手，不确认不动手，不备份不改配置。

Phase 0：环境检测

这是所有后续步骤的前提。不检测就直接改配置，可能覆盖用户已有设置。

0.1 运行环境检测脚本

用 exec 工具执行以下 Python 代码：

import json
import os
import sys
import shutil
from pathlib import Path

def load_config(path=None):
    if path is None:
        path = str(Path.home() / '.qclaw' / 'openclaw.json')
    if not os.path.exists(path):
        print(f"FATAL: openclaw.json not found at {path}")
        print("HINT: Use --config to specify the correct path")
        sys.exit(1)
    with open(path, 'r', encoding='utf-8') as f:
        return json.load(f), path

def check_python():
    ver = sys.version_info
    return f"{ver.major}.{ver.minor}.{ver.micro}"

def check_disk(config_path):
    try:
        target = os.path.dirname(config_path) or os.getcwd()
        usage = shutil.disk_usage(target)
        return f"{usage.free // (1024*1024)}MB free on {target}"
    except Exception as e:
        return f"Could not check: {e}"

def check_write_permission(path):
    test_file = os.path.join(os.path.dirname(path), '.write_test_tmp')
    try:
        with open(test_file, 'w') as f:
            f.write('test')
        os.remove(test_file)
        return True
    except Exception:
        return False

def analyze_config(cfg):
    issues = []
    warnings = []
    info = {}

    agents_list = cfg.get('agents', {}).get('list', [])
    info['agent_count'] = len(agents_list)
    info['agents'] = []
    
    for agent in agents_list:
        agent_info = {
            'id': agent.get('id', 'UNKNOWN'),
            'name': agent.get('name', ''),
        }
        subagents = agent.get('subagents', {})
        allow = subagents.get('allowAgents', None)
        if allow is not None:
            agent_info['allowAgents'] = allow
            if agent.get('id') == 'main':
                issues.append({
                    'level': 'INFO',
                    'field': 'agents.list[main].subagents.allowAgents',
                    'current': allow,
                    'msg': f'main already has allowAgents set: {allow}. Will MERGE new IDs into this list, not replace.'
                })
        else:
            if agent.get('id') == 'main':
                agent_info['allowAgents'] = None

        skills = agent.get('skills', None)
        if skills:
            agent_info['skills_count'] = len(skills)

        info['agents'].append(agent_info)

    if len(agents_list) == 1:
        warnings.append({
            'field': 'agents.list',
            'msg': 'Only 1 agent found (main). User needs to create sub-agents in UI first before this skill can proceed.'
        })

    visibility = cfg.get('tools', {}).get('sessions', {}).get('visibility', None)
    info['sessions_visibility'] = visibility
    if visibility == 'all':
        issues.append({
            'level': 'INFO',
            'field': 'tools.sessions.visibility',
            'current': 'all',
            'msg': 'Already set to "all". No change needed.'
        })
    elif visibility is not None and visibility != 'tree':
        issues.append({
            'level': 'WARN',
            'field': 'tools.sessions.visibility',
            'current': visibility,
            'msg': f'Currently set to "{visibility}", not default "tree". User may have set this intentionally. Changing to "all" may broaden access further.'
        })

    a2a = cfg.get('tools', {}).get('agentToAgent', {}).get('enabled', None)
    info['agentToAgent_enabled'] = a2a
    if a2a is True:
        issues.append({
            'level': 'INFO',
            'field': 'tools.agentToAgent.enabled',
            'current': True,
            'msg': 'Already enabled. No change needed.'
        })

    providers = cfg.get('providers', [])
    if isinstance(providers, list):
        api_key_map = {}
        for p in providers:
            key = p.get('apiKey', '')
            if key:
                k = key[-6:]
                if k not in api_key_map:
                    api_key_map[k] = []
                api_key_map[k].append(p.get('id', 'unknown'))
        for k, ids in api_key_map.items():
            if len(ids) > 1:
                warnings.append({
                    'field': 'providers',
                    'msg': f'Duplicate provider entries detected (IDs: {ids}) sharing same API key suffix ...{k}.'
                })

    channels = cfg.get('channels', [])
    info['channels'] = []
    if isinstance(channels, list):
        for ch in channels:
            ch_name = ch.get('type', ch.get('id', 'unknown'))
            info['channels'].append(ch_name)
    
    channel_types = []
    if isinstance(channels, list):
        for ch in channels:
            channel_types.append(ch.get('type', ''))
    if not channel_types or all(c in ['webchat', ''] for c in channel_types):
        warnings.append({
            'field': 'channels',
            'msg': 'Only webchat channel detected. sessions_spawn mode=session with thread=true is unsupported. Must use sessions_send approach.'
        })

    return info, issues, warnings

cfg, cfg_path = load_config()
print("=" * 50)
print("  Multi-Agent Setup - Environment Check")
print("=" * 50)
print(f"\n[ENV]")
print(f"  Python: {check_python()}")
print(f"  Config: {cfg_path}")
print(f"  Disk: {check_disk(cfg_path)}")
print(f"  Write permission: {'OK' if check_write_permission(cfg_path) else 'DENIED'}")

info, issues, warnings = analyze_config(cfg)

print(f"\n[AGENTS] Count: {info['agent_count']}")
for a in info.get('agents', []):
    extras = []
    if a.get('allowAgents') is not None:
        extras.append(f"allowAgents={a['allowAgents']}")
    if a.get('skills_count'):
        extras.append(f"skills={a['skills_count']} items")
    print(f"  - {a['id']} ({a.get('name', 'unnamed')}) {' | '.join(extras) if extras else ''}")

print(f"\n[CONFIG STATE]")
print(f"  sessions.visibility: {info.get('sessions_visibility', '(default: tree)')}")
print(f"  agentToAgent.enabled: {info.get('agentToAgent_enabled', '(default: false)')}")
print(f"  channels: {info.get('channels', 'none')}")

if issues:
    print(f"\n[ISSUES] ({len(issues)})")
    for i in issues:
        print(f"  [{i['level']}] {i['field']}")
        print(f"    Current: {i.get('current', 'N/A')}")
        print(f"    {i['msg']}")

if warnings:
    print(f"\n[WARNINGS] ({len(warnings)})")
    for w in warnings:
        print(f"  [!] {w['field']}")
        print(f"    {w['msg']}")

if not issues and not warnings:
    print("\n[ISSUES] None - clean environment, ready to proceed")

print("\n" + "=" * 50)

脚本检测项：

• Python 版本
• openclaw.json 路径（是否在默认位置）
• 磁盘剩余空间
• 配置目录写权限
• 当前 Agent 列表及配置（ID、名称、已有 allowAgents、已有 skills）
• 当前 sessions.visibility 值
• 当前 agentToAgent.enabled 值
• 已配置的 channel 类型（影响会话方案选择）
• 重复 provider 条目

0.2 分析检测结果，识别冲突与不确定性

根据脚本输出，逐条检查以下场景并向用户如实报告：

场景A：已有 allowAgents 配置

| 情况 | 处理 |

|---|---|

| allowAgents 已包含目标子Agent | 告知用户无需重复添加 |

| allowAgents 包含其他非目标Agent | 必须告知用户：patch 将合并（MERGE）而非替换，已有条目不受影响 |

| allowAgents 为空/未设置 | 正常新增 |

处理方式：patch 时使用合并策略，只添加新 ID，不删除已有 ID。

场景B：visibility 或 agentToAgent 已被修改

| 当前值 | 处理 |

|---|---|

| visibility=“all”, agentToAgent=true | 告知用户已满足，无需修改 |

| visibility=“agent” 或其他非默认值 | 必须向用户确认：这个值可能是刻意设置的，改为“all”会扩大访问范围，确认是否接受 |

| visibility 未设置（默认 tree） | 正常修改 |

场景C：仅 webchat channel

告知用户：webchat 不支持 sessions_spawn mode="session"，只能用 sessions_send + UI 手动创建会话的方案。如果用户后续接入 Discord/Telegram，可重新评估方案。

场景D：子Agent已有 skills 配置

如需调整，必须与用户确认是追加还是替换。默认追加，不删除已有技能。

场景E：非标准安装路径

如果 openclaw.json 不在默认位置（Windows 通常为 %USERPROFILE%/.qclaw/openclaw.json，Linux 通常为 ~/.qclaw/openclaw.json），需在 env_check 代码中修改 path 变量为正确路径。备份操作同理。

场景F：磁盘空间不足或无写权限

直接中止，告知用户必须先解决环境问题。

0.3 输出检测报告

将检测结果整理为报告，包含：

1. 环境状态（通过/异常）
2. 需要用户决策的问题列表（每个问题附建议方案）
3. 已满足的配置项（无需修改的部分）
4. 需要修改的配置项（附当前值→目标值）

所有不确定的问题必须等用户决策后才能进入 Phase 1。

Phase 1：规划

逐项向用户提问，每项确认后再进入下一项。不要一次性抛出所有问题。

1.1 Agent 清单

逐个询问：

1. 你已经创建了哪些 Agent？每个叫什么名字？
2. 每个 Agent 的职能是什么？（一句话描述）
3. 记录每个 Agent 的 ID（用 sessions_list 或让用户从 UI 设置页获取）

输出一份 Agent 清单表。

1.2 任务流转与委派模式

询问用户：

1. 委派路径：主Agent可以委派给哪些子Agent？（通常全部，也可限制）
2. 结果回传：用户需要在哪里看到结果？主Agent侧、子Agent侧、还是两边都要？
3. 当前仅支持主→子单向委派（子Agent之间暂不能直接互通），确认用户是否接受

当前架构限制（如实告知用户）：

• webchat 不支持 subagent_spawning hooks，无法用 sessions_spawn mode="session" 创建持久可见的子Agent会话
• 唯一可行方案：主Agent通过 sessions_send 向用户在UI上预先创建的持久会话发消息
• 子Agent之间不能直接通信，必须由主Agent中转

根据任务类型选择委派模式，两种模式共存，但跨Agent任务默认优先使用异步轮询，只有极轻量、一次性、无二次回复价值的任务才使用直接等待。

| 模式 | 适用任务 | 机制 | 优点 | 风险级别 |

|------|---------|------|------|------|

| 直接等待 | 即时问答、翻译、摘要等极轻量任务 | sessions_send(timeoutSeconds=60 或 120，按任务复杂度调整)，等返回 | 简单，token 少 | 中高 |

| 异步轮询 | 跨Agent大多数任务，尤其是文件生成、复杂任务 | sessions_send(timeoutSeconds=10) + cron 轮询文件 | 不阻塞，零回环风险 | 低 |

选择规则： 主Agent在委派时自动判断任务类型，跨Agent任务默认用异步轮询；只有极轻量任务才允许直接等待。

异步轮询标准流程：

1. sessions_send(timeoutSeconds=10)，task 中约定结果文件路径
2. 创建 cron 每 3min 检查文件，最多 5 次
3. FOUND → 读文件 → 转发用户；NOT_FOUND×5 → sessions_history 兜底

输出一份流转规则。

1.3 技能分配

询问用户：

1. 每个子Agent需要哪些技能？
2. 技能是完全共享还是按职能分配？

技能分配注意事项（向用户说明）：

• 所有 Agent 默认共享同一套内置技能（bundled skills）
• 自定义技能（user skills）需在各 Agent 的 skills 配置中单独指定
• 如用户不确定具体选型，可参考文末附录 A：技能分类参考与协作注意事项

输出一份技能分配表。

1.4 模型与特殊需求

询问：

1. 是否某些Agent需要不同模型？（如主用强模型，子用快模型）
2. 是否有Agent需要看图片？（需多模态模型支持）

Phase 2：确认

输出完整实施清单，等用户明确回复"确认执行"后才进入Phase 3。

实施清单建议包含：Agent清单与职能、任务流转规则、技能分配、环境检测结果、配置变更清单、委派会话规划、风险提示、测试计划、委派逻辑规划。

完整模板及三项关键配置参考信息见文末附录 B：实施清单模板。

Phase 3：备份

用户确认后、修改配置前，必须先备份。

操作步骤

用 exec 工具执行以下 Python 代码：

import shutil
import os
from datetime import datetime
from pathlib import Path

path = str(Path.home() / '.qclaw' / 'openclaw.json')
if not os.path.exists(path):
    print(f"ERROR: {path} not found")
    exit(1)

ts = datetime.now().strftime('%Y%m%d%H%M%S')
backup_path = f"{path}.bak.{ts}"

shutil.copy2(path, backup_path)

size = os.path.getsize(backup_path)
if size == 0:
    print(f"ERROR: Backup file is empty! Removing.")
    os.remove(backup_path)
    exit(1)

print(f"OK: Backup created at {backup_path} ({size} bytes)")

执行后：

1. 确认输出包含 "OK: Backup created"
2. 将备份路径写入当前会话的 TOOLS.md 或 memory 文件

异常处理

• 备份失败 → 中止实施，告知用户原因
• 备份文件大小为0 → 中止实施
• 恢复方式：用备份文件覆盖 openclaw.json，重启 gateway

Phase 4：实施

Step 1：Patch 关键配置

⚠️ 合并策略：必须先读取当前 allowAgents 值，将新 ID 合并进去，绝不能覆盖已有条目。

直接修改 openclaw.json（或用 Control UI 的 Raw JSON）。以下 JSON 仅包含需要变更的项（Phase 0 已检测已满足的跳过）：

// 示例：当前 allowAgents=["agent-existing"], 需要新增 agent-new
// patch 值为合并后的完整列表，不是只有新增的
{
  "agents": {
    "list": [
      {
        "id": "main",
        "subagents": {
          "allowAgents": ["agent-existing", "agent-new"]
        }
      }
    ]
  },
  "tools": {
    "sessions": {
      "visibility": "all"
    },
    "agentToAgent": {
      "enabled": true
    }
  }
}

如果 Phase 0 检测某项已满足（如 visibility 已是 all），则从这份变更 JSON 中移除该项，不要重复设置。

Step 2：验证配置生效

如未自动生效则重启后查询三项配置值，确认与目标一致。

Step 3：配置子Agent技能（如需）

在 agents.list 中为对应子 Agent 添加 skills 数组。

Step 4：引导用户创建委派会话

这一步需要用户在 UI 上手动操作，告知用户：

请按以下步骤创建委派会话：
1. 在UI左侧切换到 [子Agent名称]
2. 点击"新建对话"
3. 命名为"委派给[名称]的任务记录"
4. 发一条初始消息（如"你好，这是委派任务专用对话"）
5. 完成后告诉我，我来获取 sessionKey

用户完成后，用 sessions_list 查找该会话的 sessionKey。

⚠️ 关键区分：

• ✅ 持久会话 key 格式：agent:agent-xxxx:session-xxxxxxxx-xxxxxx（UI可见）
• ❌ 临时 subagent key 格式：agent:agent-xxxx:subagent:xxxxxxxx-xxxx-...（UI不可见，绝不能用）

Step 5：记录委派会话信息

将每个子Agent的 sessionKey 记录到主Agent的 TOOLS.md：

### [子Agent名称] 委派会话
- sessionKey: agent:agent-xxxx:session-xxxxxxxx-xxxxxx
- 职能: [描述]
- 技能: [列表]

Phase 5：测试

对每个子Agent执行端到端测试，并向用户输出测试报告。

5.1 逐个Agent测试

对每个配置了委派会话的子Agent，执行一个与其职能匹配的简单任务：

让 [Agent名称] [与其职能匹配的简单任务]

测试任务建议（按Agent职能选择）：

| 职能类型 | 建议测试任务 |

|---|---|

| 写作/文案 | 写一句话的产品slogan |

| 编程/技术 | 算一个简单的数学结果 |

| 设计/视觉 | 描述一个配色方案的名称 |

| 搜索/研究 | 查一个简单事实 |

| 通用 | 自我介绍一句话 |

5.2 验证清单

对每个子Agent检查：

• [ ] sessions_send 成功送达
• [ ] 子Agent正确执行任务
• [ ] 结果回传给主Agent（tool response 中获取）
• [ ] UI子Agent侧可见完整对话
• [ ] UI主Agent侧可见委派结果

5.3 文件类任务测试与回环防护

对于文件生成类测试任务（PPT、报告、代码等），以及其他存在回环风险的跨Agent任务，推荐使用短超时 + 轮询。

sessions_send(timeoutSeconds=10) — 发送时约定结果文件路径
  ↓
子Agent后台执行，10s后主Agent超时（预期行为）
  ↓
创建 cron：每 3min 检查约定路径文件是否存在
  ↓
FOUND → 读文件确认完成 → 进入 5.3.2 规则
NOT_FOUND × 5 → sessions_history 兜底

委派消息模板：

任务：{具体描述}
完成后将结果写入：{workspace}/_delegation_result/result.txt
格式：第一行 SUCCESS 或 ERROR，第二行简要说明。
写入后回复 REPLY_SKIP；如进入 announce 步骤，再回复 ANNOUNCE_SKIP。

为什么这样能防止回环：

• 超时 → 主Agent不收到"完成"信号 → 不触发后续回复 → 回环链路被切断
• 子Agent写入后回复 REPLY_SKIP，并在 announce 步骤回复 ANNOUNCE_SKIP → 不主动广播
• 主Agent通过文件系统取结果 → 不依赖 announce

预期管理：

• 以下规则只能降低 announce/reply-back 回环风险，不能替代系统层修复，也不能保证 100% 消除互掐。
• 如果直接等待模式出现一次明显回弹或异常重复转发，应立即停止继续委派，切换为异步轮询模式。

补充规则：防止 announce 双向管道回环

sessions_send 的 announce 模式会创建双向管道：

• 子Agent的回复被广播回主Agent会话（announce 回弹）
• 主Agent的后续消息也会被转发给子Agent（双向转发）

这会导致完整的互掐回路：主发消息 → 子收到+回复 → announce回弹到主 → 主回复 → 又转发给子 → 无限循环。

强制规则：

1. 委派任务的结果只从 sessions_send 的 tool response 中获取，转述给用户
2. 收到子Agent的任何 announce 广播必须 ANNOUNCE_SKIP，绝对不能继续生成普通回复
3. sessions_send 调用后立即结束当前 turn，不要在同一 turn 内写测试报告或后续内容
4. 在下一个 turn 中再写测试报告或执行下一步（此时管道可能已冷却）
5. 如果系统出现 "ANNOUNCE_SKIP" 消息，说明回环已被系统保护机制打断，但说明你违反了规则1和2
6. ⚠️ 无法仅凭消息内容区分用户消息和 announce 回弹！如果消息内容明显是子Agent在回复你之前转发的内容（语义匹配），这是 announce 回弹，必须 ANNOUNCE_SKIP
7. 同一对子Agent在当前会话内若连续出现 2 次回弹、异常重复转发或语义高度重复的委派结果，立即熔断，停止 agent-to-agent 继续尝试，改为主Agent人工中转或异步轮询模式。

这适用于测试阶段和日常使用，没有例外。

5.4 输出测试报告

测试完成后，必须向用户输出一份测试报告：

完整模板见文末附录 C：测试报告模板。

有任何失败项 → 排查后重新测试，不进入 Phase 6。

全部 ✅ → 进入 Phase 6。

Phase 6：委派逻辑

测试通过后，主动引导用户建立委派逻辑。这是确保协作真正可用的关键环节。

6.1 引导用户定义委派规则

向用户提问（逐项确认）：

问题1：按任务类型分配

请告诉我每种任务该委派给谁，例如：
- 写作文案 → 哪个Agent？
- 编程开发 → 哪个Agent？
- 搜索研究 → 哪个Agent？
- 设计创意 → 哪个Agent？
- 其他你常见的需求 → 哪个Agent？

问题2：默认处理规则

如果任务类型不在上面的列表里，应该：
A. 主Agent自己处理
B. 委派给 [默认Agent名称]
C. 先问用户

问题3：并行 vs 串行

多个同类型任务时：
A. 排队逐个执行
B. 尽量并行发给同Agent

问题4：特殊指令

有没有特殊要求？例如：
- 某个Agent的任务必须先审核再交付
- 某类任务必须用特定格式输出
- 某个Agent擅长某种风格/语言

6.2 沉淀委派逻辑与使用指南

将用户的回答整理为结构化委派规则，记录到主Agent的 TOOLS.md 或 MEMORY.md，并最终向用户输出一份日常使用指南。

完整模板见文末附录 D：委派逻辑与使用指南模板。

附录 A：技能分类参考与协作注意事项

基础类（建议所有Agent都有）

| 技能名 | 用途 |

|---|---|

| qclaw-rules | 文件编码、命令行、MCP等基础规则 |

| qclaw-env | 环境检测与安装 |

| qclaw-text-file | 跨平台文本文件写入（防乱码） |

| qclaw-cron-skill | 定时任务/提醒 |

搜索类

| 技能名 | 用途 |

|---|---|

| online-search | 腾讯元宝联网搜索 |

| tavily | AI优化网页搜索 |

| multi-search-engine | 17引擎聚合搜索 |

| tinyfish-search | TinyFish AI搜索 |

文档类

| 技能名 | 用途 |

|---|---|

| docx | Word文档创建/编辑 |

| pdf | PDF阅读/合并/拆分/OCR |

| pptx | PowerPoint创建/编辑 |

| xlsx | Excel表格创建/编辑 |

| nano-pdf | PDF自然语言编辑 |

创作类

| 技能名 | 用途 |

|---|---|

| frontend-design | 前端界面设计 |

| content-factory | 多代理内容生产线 |

| canvas-design | 视觉设计/海报 |

| html-ppt | HTML演示文稿 |

| frontend-slides | 动画丰富的HTML演示 |

通信类

| 技能名 | 用途 |

|---|---|

| imap-smtp-email | 个人邮箱收发 |

| public-skill | 公邮推送（零配置） |

| tencent-meeting-mcp | 腾讯会议管理 |

| wecomcli-setup | 企业微信CLI |

知识库/云文档类

| 技能名 | 用途 |

|---|---|

| ima | IMA知识库/笔记 |

| kdocs | 金山文档 |

| tencent-docs | 腾讯文档 |

| youdaonote | 有道云笔记 |

| weiyun | 微云网盘 |

信息类

| 技能名 | 用途 |

|---|---|

| news-summary | 新闻摘要 |

| tech-news-digest | 科技新闻聚合 |

| weather-advisor | 天气查询 |

| neodata-financial-search | 金融数据搜索 |

工具类

| 技能名 | 用途 |

|---|---|

| self-improving | 自我纠错学习 |

| skill-vetter | 技能安全审查 |

| qclaw-skill-creator | 创建新技能 |

| healthcheck | 安全检查 |

| fireworks-tech-graph | 技术架构图 |

协作注意事项

技能相关

| 场景 | 说明 | 建议 |

|---|---|---|

| 子Agent缺少某个技能 | 任务失败或降级执行 | 委派前确认目标Agent有对应技能 |

| 多Agent有同一技能 | 无冲突，各自独立执行 | 正常，不影响 |

| 技能依赖特定环境 | 如ffmpeg需独立安装 | 在各Agent的TOOLS.md中记录环境差异 |

| 技能不在Agent白名单 | 调用失败 | 在agent配置的skills数组中添加 |

会话相关

| 场景 | 说明 | 建议 |

|---|---|---|

| 用了错误的sessionKey | 任务跑了但UI看不到 | 只用UI创建的持久会话key |

| sessions_send超时 | 子Agent处理慢 | 加大timeoutSeconds参数 |

| 子Agent正在处理旧任务 | 新任务排队或冲突 | 确认子Agent空闲后再委派 |

配置相关

| 场景 | 说明 | 建议 |

|---|---|---|

| 重启期间服务不可用 | 修改配置后热重载或重启 | 告知用户短暂等待 |

| visibility=all的安全影响 | 所有Agent互相可见会话 | 如有敏感内容需考虑 |

| 后续新增Agent | 需重新patch allowAgents | 记录操作步骤便于重复 |

模型相关

| 场景 | 说明 | 建议 |

|---|---|---|

| 默认模型不支持图片 | 如GLM-5.1纯文本 | 需看图的Agent需配置多模态模型 |

| 不同模型能力差异 | 强弱模型回答质量不同 | 按任务复杂度分配模型 |

| 模型调用失败 | API额度/网络问题 | 确认provider配置正确 |

附录 B：实施清单模板

═══════════════════════════════════
  多Agent协作 实施清单
═══════════════════════════════════

【A. Agent清单与职能】
  主Agent（main）: [名称]
  子Agent: [名称] (ID: [id]) - [职能]
  ...

【B. 任务流转规则】
  [按1.2输出]

【C. 技能分配】
  [按1.3输出]

【D. 环境检测结果】
  Python: [版本]
  配置路径: [实际路径]
  写权限: [OK/DENIED]
  Channels: [列表及影响]
  已满足配置: [列出无需修改的项]
  冲突/待决策项: [列出需要用户确认的问题]

【E. 配置变更清单】
  变更1: agents.list[main].subagents.allowAgents
    当前值: [Phase 0 检测获取，精确到实际值]
    目标值: [合并后的值，明确标注MERGE而非REPLACE]
  变更2: tools.sessions.visibility
    当前值: [Phase 0 检测获取]
    目标值: "all"（如已为all则标注"无需修改"）
  变更3: tools.agentToAgent.enabled
    当前值: [Phase 0 检测获取]
    目标值: true（如已为true则标注"无需修改"）

【F. 委派会话规划】
  [子Agent名称] → 会话名: "委派给[名称]的任务记录"

【G. 风险提示】
  - 配置修改需重启，期间短暂不可用
  - visibility=all 意味所有Agent互相可见会话
  - 后续新增Agent需更新allowAgents列表

【H. 测试计划】
  [子Agent名称] → 测试任务: "[与其职能匹配的简单任务]"

【I. 委派逻辑规划】(Phase 6 详细确认)
  配置完成并测试通过后，将引导你定义任务委派规则

═══════════════════════════════════
  请确认无误后回复"确认执行"
═══════════════════════════════════

> 以下为三项关键配置的参考信息，用于填充清单中的当前值：

>

> 1. agents.list[main].subagents.allowAgents — 类型: string数组，默认: 无

> 作用: 允许主Agent spawn/委派的子Agent ID白名单

> 失败症状: forbidden - agentId is not allowed for sessions_spawn (allowed: none)

>

> 2. tools.sessions.visibility — 类型: string enum (tree|self|agent|all)，默认: tree

> 作用: 会话可见性范围。多Agent协作必须设为 all

> 失败症状: forbidden - Session history visibility is restricted

>

> 3. tools.agentToAgent.enabled — 类型: boolean，默认: false

> 作用: 是否允许Agent间通过sessions_send互相发消息。多Agent协作必须设为 true

> 失败症状: forbidden - Agent-to-agent messaging is disabled

>

> SessionKey区分:

> - ✅ 持久会话: agent:agent-xxxx:session-xxxxxxxx-xxxxxx — UI可见

> - ❌ 临时会话: agent:agent-xxxx:subagent:... — UI不可见，不要使用

附录 C：测试报告模板

═══════════════════════════════════
  委派测试报告
═══════════════════════════════════

  [Agent名称] ✓/✗
    测试任务: [任务描述]
    结果: [成功/失败，附简要说明]
    sessions_send: [OK/FAIL]
    子Agent执行: [OK/FAIL]
    结果回传: [OK/FAIL]
    UI子Agent侧可见: [OK/FAIL]
    UI主Agent侧可见: [OK/FAIL]

  总计: [N]/[M] 通过
═══════════════════════════════════

附录 D：委派逻辑与使用指南模板

委派逻辑表

═══════════════════════════════════
  委派逻辑表
═══════════════════════════════════

  任务类型          | 目标Agent    | 说明
  ─────────────────────────────────
  写作/文案         | [Agent名称]  | [特殊指令]
  编程/技术         | [Agent名称]  | [特殊指令]
  搜索/研究         | [Agent名称]  | [特殊指令]
  设计/创意         | [Agent名称]  | [特殊指令]
  [其他]            | [Agent名称]  | [特殊指令]
  ─────────────────────────────────
  未匹配任务        | [默认行为]    |
  多任务策略        | [并行/串行]   |

═══════════════════════════════════

记录格式

### 委派逻辑
| 任务类型 | 目标Agent | sessionKey | 特殊指令 |
|---|---|---|---|
| 写作/文案 | [名称] | agent:... | [指令] |
| 编程/技术 | [名称] | agent:... | [指令] |
| 默认 | [Agent或主Agent自己] | - | [行为] |

日常使用指南模板

═══════════════════════════════════
  多Agent协作 使用指南
═══════════════════════════════════

  📌 委派任务
     直接告诉我做什么，我会自动路由：
     "帮我写一篇关于XX的文章" → [写作Agent]
     "查一下XX的最新数据"     → [搜索Agent]
     "写个XX功能的代码"       → [编程Agent]

  📌 指定Agent
     "让[Agent名]做XX" → 直接委派给指定Agent

  📌 委派逻辑一览
     [插入委派逻辑表]

  📌 注意事项
     - 委派后我会转述结果，不需要切换页面
     - 可在子Agent的对话页面查看完整执行过程
     - 新增Agent后需重新配置允许列表

  📌 新增子Agent流程
     1. UI创建新Agent
     2. 更新 allowAgents（我来操作）
     3. UI创建委派会话
     4. 测试
     5. 更新委派逻辑表

═══════════════════════════════════

附录 E：故障排查

| 错误信息 | 原因 | 解法 |

|---|---|---|

| forbidden - agentId is not allowed | allowAgents未配置 | 添加 subagents.allowAgents 数组 |

| forbidden - Session history visibility is restricted | visibility未改为all | 设置 tools.sessions.visibility = "all" |

| forbidden - Agent-to-agent messaging is disabled | agentToAgent未启用 | 设置 tools.agentToAgent.enabled = true |

| thread=true is unavailable... | webchat不支持sessions_spawn mode=session | 改用sessions_send方案 |

| 任务执行了但UI看不到 | sessionKey用了subagent临时key | 用UI创建的持久会话key |

| sessions_send超时 | 子Agent处理慢 | 加大timeoutSeconds参数 |

| 子Agent报"技能不存在" | skills数组缺少该技能 | 补充skills配置 |

| 修改配置后服务无响应 | 正在热重载或重启 | 等待10-20秒 |

| 子Agent返回乱码文件 | 工作区编码差异 | 统一用qclaw-text-file技能 |

| sessions_send 10s超时 | 短超时模式下的预期行为 | 正常，创建 cron 轮询即可 |

| 轮询 5 次仍未找到文件 | 子Agent可能遇到不可恢复错误 | sessions_history 检查 + 通知用户 |

| 文件存在但大小为0 | 子Agent正在写入中 | 等待下一次轮询 |

| cron轮询消耗过多token | prompt不够简洁 | 精简为"检查文件，输出FOUND/NOT_FOUND" |

恢复流程

如果配置修改导致问题：

1. 找到备份文件：openclaw.json.bak.YYYYMMDDHHmmss
2. 用备份覆盖：Windows copy openclaw.json.bak.xxxxxx openclaw.json；Linux cp openclaw.json.bak.xxxxxx openclaw.json
3. 重启gateway：openclaw gateway restart
4. 确认恢复正常

强制约束

1. 必须先执行 Phase 0 环境检测，任何配置修改前必须了解当前状态；未经用户确认不得修改配置。
2. 绝不跳过备份步骤：备份失败则中止整个实施。
3. 引导而非假设：不要替用户决定Agent角色、职能或非默认配置意图，逐项询问。
4. 如实告知限制：webchat 不支持 sessions_spawn mode="session"，不要回避这个限制。
5. 合并而非替换：更新 allowAgents 时必须合并新 ID 到已有列表，绝不能覆盖用户已有配置。
6. 测试与委派逻辑不可跳过：Phase 5 必须输出测试报告，测试通过后必须进入 Phase 6 建立委派规则。
7. 绝不回复 announce 广播：sessions_send 的子Agent回复会广播回主会话，必须 ANNOUNCE_SKIP，只从 tool response 取结果，否则触发 agent-to-agent 回环。
8. sessions_send 后立即结束 turn：announce 创建双向管道，同一 turn 内继续写内容会被转发给子Agent，必须下一 turn 再处理结果。
9. 异步轮询优先：跨Agent任务默认优先使用异步轮询；文件生成任务必须使用 timeoutSeconds=10 + cron 轮询模式，不得使用 timeoutSeconds=300 直接等待。
10. 发现异常立即熔断：若出现明显回弹、异常重复转发，或同一对子Agent连续 2 次异常，立即停止继续委派，改为主Agent人工中转或异步轮询模式。
11. 预期管理：本 skill 只能降低回环风险，不能替代系统层修复，也不能保证 100% 消除互掐。