故障排除指南：嵌套 Agent 会话相互阻塞

症状

如果您正在同时运行多个 agent 会话，可能会遇到以下症状：

• 响应延迟或丢失： 一个或多个 agent 会话出现"冻结"或响应时间明显超出预期的情况，即使请求的任务很简单。
• 跨会话阻塞： 一个会话上的长时间运行任务（如 ACP Claude Code 运行）导致完全不相关的会话出现延迟。
• 网关超时： 日志中出现错误信息，显示 lane wait exceeded: lane=nested waitedMs=XXXXX queueAhead=1。
• Discord 投递失败： 在积压期间生成的 Assistant 响应从未投递到 Discord 频道。
• 行为不一致： 某些会话即时响应，而其他会话则闲置数分钟，即使底层任务无关。

根因分析

根本原因是嵌套 agent 执行系统中的单一全局队列瓶颈。

之前，所有会话中的嵌套 agent 操作共享一个名为 "nested" 的通道，配置为 maxConcurrent=1。这意味着：

1. 每个 sessions_send、runAgentStep 和 ACP 调度都竞争同一个队列条目。
2. 当会话 A 运行一个 10 分钟的任务时，会话 B、C 和 D 必须排在其后面等待。
3. 命令队列将每个嵌套操作视为相同，无论它针对哪个会话。

这种架构限制导致队头阻塞，单个长时间运行的嵌套操作可能会阻塞网关中的所有其他 agent 会话。

逐步修复

选项 1：升级到修复版本（推荐）

将您的 OpenClaw 安装升级到版本 v2026.4.19-beta.2 或更高版本。

此版本引入了按会话嵌套通道，将嵌套工作范围限定为 nested:<sessionKey>，允许不同会话并行执行，同时保持每个会话内的并发不变量。

选项 2：验证通道配置（用于手动验证）

如果您需要验证修复是否正确应用，请检查网关日志中使用的通道名称：

修复之前，您会看到类似这样的日志：

[agent:nested] Processing session A
[agent:nested] Processing session B

修复之后，您应该看到作用域限定的通道名称：

[agent:nested:session-A] Processing session A
[agent:nested:session-B] Processing session B

选项 3：检查通道状态映射

在您的网关配置中，通道状态现在应该通过完整的会话作用域标识符作为键，而不是裸的 "nested" 字符串。每个条目应显示：

• nested:<sessionKey> 用于标准会话
• "nested" 仅用于遗留的 cron 路径回退

验证

要确认修复是否正常工作：

1. 运行多个并发会话： 设置两个或更多可以接收嵌套操作的 agent 会话。

2. 在一个会话上触发长时间运行的任务： 例如，调用一个需要几分钟才能完成的任务。

3. 向另一个会话发送快速任务： 在长时间任务运行期间，向不同会话发送简单请求。

4. 验证并行执行： 第二个会话应立即响应，无需等待第一个会话的任务完成。

5. 检查作用域通道的日志： 在网关日志中查找 [agent:nested:<sessionKey>] 前缀，确认每个会话的通道隔离。

修复后的预期测试结果：

pnpm test src/agents/lanes.test.ts         # 13 tests green
pnpm test src/gateway/server.sessions-send.test.ts  # 14 tests green
pnpm test 'src/agents/**/*.test.ts'        # 3841 tests green

常见陷阱

会话密钥处理

• 空或仅包含空白的会话密钥： 这些会回退到非作用域的 "nested" 通道。确保在路由嵌套操作之前正确填充会话密钥。

• 遗留 cron 路径： 使用 resolveNestedAgentLane(lane) 的 cron 集成仍然使用非作用域回退。这是为向后兼容性而设计的。

通道名称冲突

• 用户提供的通道名称： 如果您有自定义通道名称（如 "nested:something"），请注意这些与系统生成的 nested:<sessionKey> 通道不同。系统通道使用特定的前缀约定，匹配现有的 session:<key> 模式。

内存注意事项

通道状态 Map 现在会随着新会话密钥的出现而增长。每个通道状态条目大约 200 字节。现实的上限是活动会话的数量，这已经受到网关会话管理的限制。如果这成为问题，未来可能会添加清理空闲嵌套通道的增强功能。

无关问题

原始报告中提到的两个相关问题不在此修复的范围内：

• 会话投递上下文损坏
• 缺少投递重试/DLQ 机制

这些是单独跟踪的架构后续工作。

相关错误

受影响版本

• 已在以下版本修复： v2026.4.19-beta.2
• 受影响版本： v2026.4.14 及更早版本

兼容性

此修复完全向后兼容：

• AGENT_LANE_NESTED 常量仍然被导出
• 继续直接传递该常量的调用者保留其现有（非作用域）行为
• 无需更改配置
• 无需迁移步骤

该修复加强了会话隔离，同时不会破坏现有集成。