核心改进：阻断重复异步执行完成事件的重复注入

OpenClaw 最新更新针对一个隐蔽但影响重大的系统问题——重复异步执行完成事件（exec.finished）被多次注入父会话——实施了精准修复。该问题表现为用户在同一会话中看到两个完全相同的 AI 回复，严重影响用户体验。本文将深入剖析问题根因、技术实现路径及修复方案。

—

问题现象：为什么会出现”双胞胎”回复？

在 OpenClaw 的分布式执行架构中，异步任务（如长时运行的代码执行、外部 API 调用）完成后，会通过 gateway 层的 node-event 处理器将 exec.finished 事件注入会话，触发心跳（heartbeat）并生成新的用户可见回合。

实际生产环境中，由于网络重试、消息队列重放或网关重启等场景，同一执行任务的完成事件可能被多次投递：

用户视角：同一问题 → AI 回复 A → [重复] AI 回复 A（完全相同）
系统日志：exec.finished (runId: abc-123) 被处理 2 次

这种重复用户回合不仅造成困惑，还可能触发下游计费、分析系统的数据异常。

—

技术根因分析：事件流转全链路

执行完成事件的完整路径

理解修复方案前，需先追踪 exec.finished 的完整生命周期：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Node 执行器  │ → │  系统事件入队  │ → │  心跳调度唤醒  │ → │  提示词组装   │
│ (exec producer)│   │enqueueSystemEvent│   │heartbeat wake │   │prompt assembly│
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                                                                  ↓
┌─────────────┐    ┌─────────────┐
│  会话持久化   │ ← │  嵌入转录存储  │
│  (session)   │   │  (transcript) │
└─────────────┘    └─────────────┘

最可能的故障点：网关层缺少幂等性防护

通过代码级分析，开发团队定位到网关服务端的事件处理器存在防护缺口：

| 潜在原因 | 分析结论 | 置信度 |
|———|———|——–|
| 重复唤醒处理（duplicate wake handling） | 心跳调度层已有去重机制 | 低 |
| 出站投递重试（outbound delivery retry） | 重试针对的是传输层，非应用层事件 | 中 |
| 重复完成事件摄入（duplicate completion event ingestion） | 网关 server-node-events 未对 exec.finished 做幂等校验 | 高 |

> 关键洞察：简单的出站投递重试无法解决应用层重复事件问题，必须在事件入队前拦截。

—

修复方案：精准的幂等性守卫

核心实现：基于会话键+执行ID的去重

OpenClaw 在网关层引入了窄范围幂等性守卫，代码核心逻辑如下：

// gateway/server-node-events/handlers/exec-finished.js

/**
 * 处理 exec.finished 节点事件
 * 新增：幂等性守卫防止重复注入
 */
async function handleExecFinished(event) {
  const { runId, sessionKey } = event;
  
  // 构建规范化的幂等键：会话+执行ID
  const idempotencyKey = ${sessionKey}:${runId};
  
  // 检查是否已处理过该执行完成事件
  if (await idempotencyStore.has(idempotencyKey)) {
    logger.info([DEDUPE] Skipping replayed exec.finished: ${runId});
    return { processed: false, reason: 'DUPLICATE_EVENT' };
  }
  
  // 首次处理：标记为已处理（TTL 与会话生命周期对齐）
  await idempotencyStore.set(idempotencyKey, {
    timestamp: Date.now(),
    ttl: SESSION_TTL_MS
  });
  
  // 尝试入队系统事件
  const enqueued = await enqueueSystemEvent({
    type: 'EXEC_FINISHED',
    payload: event,
    idempotencyKey  // 向下传递用于追踪
  });
  
  // 优化：仅当实际入队成功时才请求心跳
  if (enqueued) {
    await requestHeartbeat(sessionKey, { 
      trigger: 'exec.finished',
      runId 
    });
  }
  
  return { processed: enqueued, enqueued };
}

关键设计决策

| 设计选择 | 理由 |
|———|——|
| 作用域收紧 | 仅针对 exec.finished 事件，避免影响其他节点事件类型 |
| 键设计 | canonical session key + runId 确保同一执行在会话内唯一 |
| 延迟心跳请求 | 改为”入队成功后请求心跳”，避免无效唤醒 |
| 存储 TTL | 与会话生命周期对齐，自动清理过期键 |

回归测试覆盖

新增测试用例确保修复有效性：

// test/gateway/exec-finished-dedupe.test.js

describe('exec.finished 幂等性守卫', () => {
  test('应阻止相同 runId 的重复事件注入', async () => {
    const sessionKey = 'sess_abc123';
    const runId = 'run_xyz789';
    
    // 首次处理：应成功
    const first = await handleExecFinished({ sessionKey, runId, result: 'ok' });
    expect(first.processed).toBe(true);
    expect(first.enqueued).toBe(true);
    
    // 模拟重放：相同 runId 再次进入
    const replay = await handleExecFinished({ sessionKey, runId, result: 'ok' });
    expect(replay.processed).toBe(false);
    expect(replay.reason).toBe('DUPLICATE_EVENT');
    
    // 验证：仅触发一次心跳
    expect(heartbeatMock).toHaveBeenCalledTimes(1);
  });
  
  test('不同 runId 应正常处理', async () => {
    // 同一会话，不同执行ID
    const result1 = await handleExecFinished({ sessionKey: 'sess_1', runId: 'run_A' });
    const result2 = await handleExecFinished({ sessionKey: 'sess_1', runId: 'run_B' });
    
    expect(result1.processed && result2.processed).toBe(true);
    expect(heartbeatMock).toHaveBeenCalledTimes(2);
  });
});

—

部署与验证

升级检查清单

1. 确认当前版本
openclaw version  # 需 >= 1.47.0

2. 验证网关配置
openclaw config get gateway.node_events.dedupe_enabled
预期输出: true

3. 检查幂等存储后端连接
openclaw health check idempotency-store

4. 监控关键指标（升级后 24 小时）
openclaw metrics query --name="gateway_exec_finished_deduped_total" --since="1d"

关键监控指标

| 指标名称 | 说明 | 正常范围 |
|———|——|———|
| gateway_exec_finished_deduped_total | 被拦截的重复事件数 | 根据重试策略，>0 即表示生效 |
| gateway_heartbeat_requested_total | 心跳请求次数 | 应与成功入队事件数 1:1 |
| session_duplicate_turn_rate | 会话重复回合率 | 修复后应趋近于 0 |

—

常见问题解答

Q1: 这个修复会影响正常的重试机制吗？

不会。 该修复针对的是应用层事件重复摄入，而非传输层的网络重试。OpenClaw 的节点执行器与网关之间的消息投递仍保留原有的重试策略，仅在网关事件处理器入口处增加幂等校验。

Q2: 如何确认我的系统是否遇到过这个问题？

检查以下日志模式：

查询历史重复事件（如有保留原始日志）
grep "DUPLICATE_EVENT" /var/log/openclaw/gateway.log


或分析会话转录中的异常
openclaw sessions analyze --pattern="identical_consecutive_turns" --since="7d"

Q3: 幂等键的存储使用什么后端？有持久化要求吗？

默认使用与 OpenClaw 会话存储相同的 Redis 集群，键的 TTL 设置为会话生命周期（默认 24 小时）。无需额外持久化，重复事件防护仅需覆盖事件重放的典型时间窗口（通常秒级到分钟级）。

Q4: 如果网关是多实例部署，去重还能生效吗？

可以。 幂等存储基于共享的 Redis 后端，所有网关实例共享同一去重状态。测试验证显示，在 3 实例网关集群下，并发