一句话总结
OpenClaw 最新更新在 Gateway 层引入了基于 会话键（session key） 和 执行 ID（runId） 的幂等性守卫，彻底解决了异步执行完成事件被重复注入导致的”重复用户回合”问题。
问题背景：为什么会出现重复执行事件？
在使用 OpenClaw 构建 AI Agent 系统时，异步执行（async exec）是核心能力之一。当 Agent 调用外部工具或执行长时间任务时，系统会通过事件驱动机制通知会话完成状态。
然而，在高可用部署或网络不稳定场景下，exec.finished 事件可能被重复发送——这会导致：
- 同一执行结果被多次处理
- 会话中出现重复的用户回合（duplicate user turns）
- 心跳调度异常，触发多余的提示词组装
> 原始 Issue 描述：Investigate a live duplicate async exec completion that appeared as two identical user turns in an OpenClaw session.
技术根因分析
事件流转路径
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Node 执行层 │ ──▶ │ enqueueSystemEvent │ ──▶ │ 心跳唤醒调度 │
│ (exec.finished)│ │ (系统事件入队) │ │ (heartbeat wake) │
└─────────────┘ └─────────────────┘ └─────────────────┘
│
┌─────────────────────────┘
▼
┌─────────────────┐ ┌─────────────────┐
│ 提示词组装 │ ──▶ │ 嵌入会话记录 │
│ (prompt assembly)│ │ (transcript persistence)
└─────────────────┘ └─────────────────┘
最可能的故障点
经过代码追踪，开发团队定位到 Gateway 层缺少对重放事件的幂等性保护。具体表现为：
| 潜在原因 | 评估结果 | 说明 |
|———|———|——|
| 重复唤醒处理 | 较低 | 心跳调度层已有基本防护 |
| 出站投递重试 | 较弱方案 | 会导致重复用户回合，不符合预期 |
| 重复完成事件摄入 | 最高置信度 | Gateway 未对重放的 exec.finished 去重 |
> 关键代码位置：gateway/server-node-events 处理器
解决方案：三层幂等性保障
第一层：核心去重守卫
在 Gateway 的 node-event 处理器中，新增基于规范会话键 + 执行 runId 的幂等性检查：
// gateway/handlers/node-events.js
// 新增：exec.finished 事件去重守卫
const processedExecs = new Set(); // 或使用分布式缓存（Redis 等）
function handleExecFinished(event) {
// 构建唯一键：canonical session key + runId
const dedupeKey = ${event.session.canonicalKey}:${event.runId};
// 幂等性检查：已处理则直接丢弃
if (processedExecs.has(dedupeKey)) {
logger.warn(Duplicate exec.finished ignored: ${dedupeKey});
return { handled: false, reason: 'DUPLICATE_EVENT' };
}
// 标记为已处理
processedExecs.add(dedupeKey);
// 继续处理：入队系统事件
const queued = enqueueSystemEvent(event);
// 第二层优化：仅在实际入队时请求心跳
if (queued) {
requestHeartbeatWake(event.session.id);
}
return { handled: true, queued };
}
第二层：条件化心跳请求
修复前：无论事件是否实际入队，都会触发心跳唤醒
修复后：仅当系统事件成功入队时才请求心跳
// 优化前（问题代码）
enqueueSystemEvent(event); // 可能因去重失败
requestHeartbeatWake(sessionId); // 无条件执行，导致多余唤醒
// 优化后（修复代码）
const queued = enqueueSystemEvent(event);
if (queued) { // 条件化触发
requestHeartbeatWake(sessionId);
}
第三层：回归测试覆盖
新增测试用例确保重复 runId 注入会被正确拦截：
// test/gateway/exec-dedupe.test.js
describe('exec.finished deduplication', () => {
it('should reject duplicate runId injection', async () => {
const sessionKey = 'sess_abc123';
const runId = 'run_xyz789';
// 首次处理：成功
const first = await handleExecFinished({ sessionKey, runId, result: 'done' });
expect(first.handled).toBe(true);
expect(first.queued).toBe(true);
// 重复注入：被拒绝
const second = await handleExecFinished({ sessionKey, runId, result: 'done' });
expect(second.handled).toBe(false);
expect(second.reason).toBe('DUPLICATE_EVENT');
// 验证：仅触发一次心跳
expect(heartbeatWakeCount).toBe(1);
});
});
部署与验证
升级步骤
1. 拉取最新代码
git fetch origin
git checkout 5dcf526a4344340220d2d8e91a3c59b92391b0ce
2. 安装依赖并构建
npm ci
npm run build:gateway
3. 重启 Gateway 服务
pm2 restart openclaw-gateway
4. 验证去重功能
npm run test:regression -- --grep "dedupe"
监控指标
建议在生产环境关注以下指标：
| 指标名称 | 说明 | 告警阈值 |
|———|——|———|
| gateway.exec.dedupe.hits | 去重拦截次数 | > 10/分钟需关注 |
| gateway.exec.duplicate.rejected | 重复事件拒绝数 | 正常应 > 0 |
| heartbeat.wake.unnecessary | 多余心跳唤醒 | 修复后应趋近于 0 |
FAQ
Q1: 这个更新会影响正常的异步执行吗？
不会。 幂等性守卫仅拦截完全相同的 sessionKey + runId 组合。每个新的异步执行都会生成唯一的 runId，正常流程完全不受影响。
Q2: 如果我的 OpenClaw 版本较旧，如何手动实现类似保护？
可在应用层添加临时去重逻辑：
// 临时方案：应用层去重包装
const recentExecs = new Map(); // 注意：单机有效，集群需 Redis
async function safeHandleExec(event) {
const key = ${event.sessionKey}:${event.runId};
if (recentExecs.has(key)) return;
recentExecs.set(key, Date.now());
// 5 分钟后清理
setTimeout(() => recentExecs.delete(key), 300000);
return await yourHandler(event);
}
Q3: 为什么不用数据库唯一索引实现去重？
数据库层防护是最后防线，但：
- 事件已到达 Gateway 才触发 DB 约束，网络/计算资源已消耗
- 心跳唤醒等副作用可能在 DB 拒绝前已执行
- 本方案在最早环节拦截，成本最低
Q4: 分布式部署时 processedExecs 如何共享？
生产环境建议替换为分布式缓存：
// Redis 实现示例
const dedupeKey = exec:finished:${sessionKey}:${runId};
const isNew = await redis.set(dedupeKey, '1', 'NX', 'EX', 3600); // 1小时过期
if (!isNew) return { handled: false, reason: 'DUPLICATE_EVENT' };
Q5: 如何确认我的系统是否曾受此问题影响？
检查日志中是否出现以下模式：
搜索重复用户回合迹象
grep "identical user turns" /var/log/openclaw/*.log
或检查同一 runId 的多次完成事件
awk '/exec.finished/ {print $runId}' app.log | sort | uniq -d
总结
本次 OpenClaw #67281 更新通过三层防护机制解决了异步执行事件的重复注入问题：
1. 核心守卫：sessionKey + runId 幂等性检查
2. 条件优化：仅成功入队时才触发心跳
3. 测试保障：回归测试防止回归
建议所有使用异步执行功能的用户尽快升级，并在生产环境启用相关监控。
—
相关阅读
参考来源
- GitHub Commit: 5dcf526 – 原始代码变更
- OpenClaw 官方文档 – Gateway 配置指南
- Issue #67281 – 问题追踪（如公开）
