OpenClaw 多 Agent 协作实战：3 个 sessions_spawn 常见翻车场景和修复方法

折腾多 Agent 协作的人，大概都经历过这种崩溃：调了一整天配置，sessions_spawn 终于不报错了——结果子 Agent 加载的是父 Agent 的 SOUL.md，输出一坨乱七八糟的东西。

我是窝子，前腾讯算法工程师，现在在 xiawo.net 写 OpenClaw 实战踩坑记录。我自己的多 Agent 流水线跑了大半年（Scout → Reviewer → Reporter），sessions_spawn 的坑基本踩了一遍。这篇文章就讲 3 个最常见的翻车场景，每个都有报错信息、根因分析和修复步骤。

翻车场景 1：sessions_spawn 报 "agentId is not allowed"

报错信息

Error: agentId "scout" is not allowed

这是最常见的报错，也是最容易解决的——但你可能要查半天文档才能找到原因。

根因

sessions_spawn 默认只允许 spawn 当前 agent 自己的 subagent。跨 agent spawn 需要显式配置白名单。

很多人以为配置了 agents 下面有 scout、hunter 这些 agent 就能互相调用了，其实不是。OpenClaw 的安全模型默认禁止跨 agent spawn，除非你在 agents.defaults.subagents.allowAgents 里明确列出。

修复步骤

第一步：检查配置文件

打开 openclaw.yaml，确认有这个配置：

agents:
  defaults:
    subagents:
      allowAgents:
        - scout
        - hunter
        - reporter

注意：allowAgents 里填的是 agentId，不是 agent 的显示名称。如果你定义的 agent 是：

agents:
  scout:
    model: primary

那 allowAgents 里就填 scout。

第二步：确认调用参数

sessions_spawn 调用时：

sessions_spawn({
  agentId: "scout",  // 必须与 allowAgents 列表中的值完全一致
  task: "..."
})

第三步：重启 Gateway

修改 openclaw.yaml 后必须重启 gateway：

openclaw gateway restart

相关 GitHub Issue

• #47862：9 个 sessions_spawn 常见问题排障指南
• #9857：Subagents spawned via sessions_spawn cannot invoke tools

---

翻车场景 2：子 Agent 加载了错误的 SOUL.md/workspace

现象

这个坑最阴险——sessions_spawn 不报错，子 Agent 也"正常"运行，但输出完全不对。

典型表现：

• 子 Agent 的回复风格跟父 Agent 一样
• 子 Agent 不认识自己应该知道的东西
• 明明定义了 Reporter 的 SOUL.md，输出却像是 Coordinator 写的

根因（GitHub issue #45868）

这是 OpenClaw 2026.3.12 引入的 regression。

具体来说：sessions_spawn 在解析 spawned agent 的 workspace 时，错误地从 requester (parent) session key 解析，而不是从 target agentId 解析。

结果是：子 Agent 加载了父 Agent 的 SOUL.md 和 workspace，完全不知道自己是哪个 agent。

这个 bug 在后续版本已修复，但如果你恰好用的是 2026.3.12，就会遇到。

修复方法

方案一：升级 OpenClaw

升级到 2026.3.13 或更高版本。

方案二：临时 workaround

在 sessions_spawn 调用时显式指定 cwd 参数：

sessions_spawn({
  agentId: "reporter",
  cwd: "/path/to/reporter/workspace",  // 显式指定子 agent 的工作目录
  task: "..."
})

相关资源

• GitHub issue #45868：官方 issue 记录
• stepcodex.com 有详细的修复步骤指南

---

翻车场景 3：子 Agent 超时未返回结果

现象

sessions_spawn 调用后，等了很久，最后报：

Error: Subagent timed out after 300 seconds

或者更诡异的情况：子 Agent 明明执行完了，但结果没返回。

根因

这里有两个容易混淆的超时概念：

类型	含义	配置项
run timeout	sub-agent 执行超时，被系统中止	runTimeoutSeconds
settle timeout	等待结果返回超时	yieldMs / timeoutSeconds

常见的坑：

1. runTimeoutSeconds 配置太小：子 Agent 还没执行完就被杀掉了
2. 本地模型冷启动慢：模型加载就要 30-60 秒，还没开始干活就超时
3. settle timeout 和 run timeout 冲突：父 Agent 等待结果的超时比子 Agent 执行超时还短

修复方法

第一步：配置默认超时

在 openclaw.yaml 中：

agents:
  defaults:
    subagents:
      runTimeoutSeconds: 600  # 10 分钟，根据你的任务复杂度调整
    llm:
      idleTimeoutSeconds: 300  # 本地模型冷启动等待 5 分钟

第二步：本地模型冷启动优化

如果你用 Ollama 跑本地模型，冷启动可能要 30-60 秒。解决方案：

agents:
  defaults:
    llm:
      idleTimeoutSeconds: 300  # 等模型启动

或者预热模型：在 spawn 子 Agent 之前先发一个简单请求让模型加载到内存。

第三步：调整调用参数

sessions_spawn({
  agentId: "hunter",
  task: "...",
  timeoutSeconds: 600,  // 执行超时
  yieldMs: 500          // 返回前等待时间（可选）
})

相关 GitHub Issue

• #19288：Feature request for runTimeoutSeconds default config
• #25810：LLMs 忽略 prompt 指令传入过低的 runTimeoutSeconds
• #33408：最大 900s 不够用的场景

---

最小可跑通配置模板

折腾了这么多配置，到底什么才是"能跑"的最小配置？

这是我当前在用的多 Agent 流水线配置，亲测可跑通：

agents:
  coordinator:
    model: primary
    subagents:
      allowAgents:
        - scout
        - hunter
        - reporter
      runTimeoutSeconds: 600
      maxConcurrent: 8
      maxSpawnDepth: 3

  scout:
    model: primary

  hunter:
    model: primary

  reporter:
    model: primary

关键点：

• allowAgents 列出所有需要跨 agent spawn 的 agentId
• runTimeoutSeconds 根据任务复杂度设置，一般 300-600 秒够用
• maxConcurrent 控制并发，别设太大，本地机器扛不住

---

适合谁 / 不适合谁

适合：

• 已经跑通单 Agent，想折腾多 Agent 协作的人
• 有基本的 YAML 配置能力
• 愿意看 GitHub issue 排坑的人

不适合：

• OpenClaw 新手（先把单 Agent 跑通再折腾多 Agent）
• 没有明确的多 Agent 需求（为了用而用会很痛苦）
• 不想踩坑的人（多 Agent 协作现阶段坑还很多）

---

下一步

如果你正在搭建自己的多 Agent 系统，建议：

1. 先用上面的最小配置跑通：一个 Coordinator + 一个 Worker
2. 逐步加 agent：先 Scout，再加 Hunter、Reporter
3. 遇到问题查 issue：OpenClaw 的 issue 质量不错，大部分坑都有人踩过

下一篇文章我会讲多 Agent 协作的进阶玩法：bindings 路由绑定和 agentToAgent 通信。这两个功能可以让你的多 Agent 系统更灵活，但坑也更多。

---