一句话总结

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. 测试保障：回归测试防止回归

建议所有使用异步执行功能的用户尽快升级，并在生产环境启用相关监控。

—

相关阅读

• OpenClaw 异步执行最佳实践
• Gateway 事件处理架构详解
• AI Agent 幂等性设计模式

参考来源

• GitHub Commit: 5dcf526 – 原始代码变更
• OpenClaw 官方文档 – Gateway 配置指南
• Issue #67281 – 问题追踪（如公开）