——
OpenClaw 修复子代理任务通知丢失：3 种重试机制详解
OpenClaw 最新版本修复了一个关键的生产环境问题——子代理（Subagent）完成状态通知丢失。当你的 AI Agent 长时间运行后，子任务完成的消息可能无法正确触达父代理，导致整个工作流卡住。本文将详细拆解这个修复方案的技术原理，以及如何在实际项目中避免类似问题。
—
问题背景：为什么子代理通知会”消失”
在 OpenClaw 的分布式 Agent 架构中，父代理经常需要委派子代理执行耗时任务。正常情况下，子代理完成后会通过 transcript-wait 机制通知父代理恢复执行。但在特定条件下，这个通知会失效：
- 请求运行状态过期（stale）：父代理的运行上下文因超时或资源回收进入过期状态
- 直接完成不可见：子代理的直接完成信号无法被父代理接收
- Transcript 等待机制不支持：某些场景下
transcript-wait唤醒会失败
这些问题共同导致了一个症状：子代理实际已完成，但父代理永远在等待，形成”僵尸任务”。
—
核心修复方案：三重保障机制
本次提交 04eac15 引入了三层递进式修复策略，确保通知必达。
第一层：无 Transcript 等待的重试机制
当检测到 transcript-wait 唤醒不被支持时，系统会降级到无等待模式重试：
// 伪代码示意：重试逻辑的核心判断
async function retryCompletionAnnounce(subagentRun, requesterRun) {
try {
// 第一次尝试：标准 transcript-wait 唤醒
await wakeWithTranscriptWait(subagentRun);
} catch (error) {
if (error.code === 'UNSUPPORTED_TRANSCRIPT_WAIT') {
// 降级策略：移除 transcript 依赖，直接重试
console.log('[OpenClaw] Transcript-wait 不支持，切换到直接唤醒模式');
await wakeWithoutTranscriptWait(subagentRun);
}
throw error;
}
}
关键点：这种降级不会丢失完成状态，只是改变了通知的传输方式。
第二层：强制消息工具交接
当检测到请求者运行已过期（requester run is stale）时，系统会强制触发 message-tool handoff：
// 强制交接的触发条件
if (isRequesterRunStale(requesterRun) && isDirectCompletionInvisible(subagentRun)) {
// 强制使用消息工具通道完成交接
forceMessageToolHandoff({
from: subagentRun,
to: requesterRun.parentContext,
payload: subagentRun.completionResult,
force: true // 绕过常规可见性检查
});
}
message-tool handoff 是 OpenClaw 的可靠消息通道，即使直接完成路径断裂，也能保证状态传递。
第三层：回归测试覆盖
修复方案包含完整的回归测试，模拟”过期唤醒序列”：
运行新增回归测试
npm test -- --grep "stale subagent completion announce"
预期输出：
✓ should recover when transcript-wait is unsupported
✓ should force handoff when requester run is stale
✓ should handle invisible direct completion gracefully
—
实际应用场景
场景一：长时间数据分析任务
// 父代理委派耗时数据分析
const analysisRun = await openclaw.subagents.create({
task: "分析 10GB 日志数据",
timeout: "2h", // 长时间运行
onCompletion: "notifyParent"
});
// 修复前：如果分析在 2 小时后完成，父代理可能已过期，通知丢失
// 修复后：自动重试 + 强制交接，确保通知必达
场景二：嵌套子代理链
父代理 → 子代理 A → 子代理 B → 子代理 C
↑___________________________________|
(完成通知)
在深层嵌套中，任何中间层的过期都可能导致通知链断裂。新机制在每个节点都有重试保障。
—
升级建议
检查当前版本
查看 OpenClaw 版本
openclaw --version
确保 >= 包含 04eac15 提交的版本
配置监控告警
建议为子代理完成通知延迟添加监控：
// 监控配置示例
openclaw.monitoring.configure({
alerts: [{
name: "subagent-completion-delay",
condition: "completion_announce_time > 30s",
severity: "warning"
}]
});
—
常见问题 FAQ
Q1: 这个修复会影响现有子代理的性能吗？
不会。 重试机制仅在检测到失败条件时触发，正常路径的性能开销为零。强制交接也是异步执行，不会阻塞子代理的完成流程。
Q2: 如何知道我的项目是否遇到了这个问题？
检查日志中是否有以下模式：
[WARN] Subagent completed but wake failed: transcript-wait unsupported
[ERROR] Requester run stale, completion announce dropped
如果出现这些日志，说明已触发修复机制，建议升级到最新版本获得完整保护。
Q3: “stale run” 的判定标准是什么？
默认情况下，运行状态在 30 分钟无活动 后标记为 stale。可通过环境变量调整：
export OPENCLAW_RUN_STALE_THRESHOLD_MS=1800000 # 30分钟
Q4: 这个修复与 Issue #83699 有什么关系？
这是该 Issue 的完整修复方案。#83699 报告了生产环境中子代理通知随机丢失的现象，经过诊断确定为上述三重故障条件的组合触发。
Q5: 如果 message-tool handoff 也失败了怎么办？
OpenClaw 会进入 持久化重试队列，将完成状态写入可靠存储，并在系统恢复后重新投递。这是最后的保障层，确保至少一次交付语义。
—
总结
本次修复通过 降级重试、强制交接、回归测试 三层机制，彻底解决了子代理完成通知的可靠性问题。对于运行长时间任务或复杂 Agent 链的用户，建议立即升级到包含此修复的版本。
下一步行动：
1. 升级 OpenClaw 到最新版本
2. 审查现有子代理的超时配置
3. 配置完成通知延迟监控
—
相关阅读
—
参考来源
