OpenClaw Multi-Agent 超时与挂起问题

OpenClaw 多 Agent 系统中最常见的可靠性问题：主 Agent 挂起、超时、或子 Agent 完成后主 Agent 仍报错。

三类核心问题

1. 主 Agent 等待超时（委托模式）

现象：主 Agent 委托给次级 Agent，次级 Agent 已完成，但主 Agent 仍超时并回退自执行，导致重复工作。

根因：

• 默认超时 300s 对复杂任务太短，形成竞态条件
• 未定义 on_complete 回调 → 次级 Agent 存储结果但不通知主 Agent
• 双方同时消耗 context window，内存压力破坏通信通道
• 无心跳机制，主 Agent 无法区分”仍在工作”与”已崩溃”

修复：

# openclaw.yaml
delegation:
  default_timeout_seconds: 900    # 至少 2x 实测时长
  heartbeat_enabled: true
  heartbeat_interval_seconds: 30
  heartbeat_timeout_seconds: 120
 
agents:
  worker:
    on_complete:
      action: notify_delegator
      include_result: true
      cleanup_context: true
    context_management:
      max_tokens: 8000
      warning_threshold: 0.75
      on_overflow:
        action: compact_history

2. 主循环被长时操作阻塞（ACP 模式）

现象：Agent 调用 Azure/Terraform 等长时 CLI 命令，整个主循环无响应，无法取消，无法并发。

根因：OpenClaw 主 Agent 循环是串行的，inline 执行长时操作会阻塞整个 loop。

修复：使用 ACP 协议 将高风险操作隔离到子进程。

3. 子 Agent 完成消息泄漏到用户频道

现象：子 Agent 完成消息（”✅ Subagent finished…“）被转发到 Telegram/Discord 等用户频道，造成消息泄漏。

根因：src/agents/subagent-announce-dispatch.ts 中 expectsCompletionMessage 默认为 true，且未暴露配置项。

状态：GitHub Issue #32124 提议增加 completionDelivery: internal | user 配置，但已被关闭为 not planned。

临时规避：目前无官方配置项可用，需在代码层面处理。

诊断步骤

1. 开启 debug 日志：logging: level: debug
2. 确认次级 Agent 是否真正完成（看日志中 task completed, result stored）
3. 检查主 Agent 是否收到完成信号（看是否有 received result from 日志）
4. 测量实际任务耗时，设置超时为 2x
5. 确认 on_complete 回调已定义

相关概念

• openclaw-acp-protocol — 用进程隔离彻底解决主循环阻塞问题
• awesome-openclaw-skills — OpenClaw skill 生态