为什么在 OpenClaw 里必须重视“任务幂等”

在自动化编排、任务调度、批处理链路中，“重复执行”不是偶发事件，而是常态：网络闪断导致重试、Worker 崩溃后重新拉起、队列重复投递、分布式锁超时误判、人工误点“重跑”等，都可能让同一任务被执行两次甚至多次。

在 OpenClaw 的实践语境里，我们把“任务幂等”定义为：同一业务语义的任务被重复触发/重复执行时，最终业务结果与只执行一次一致。注意这里强调“业务语义”，而不是“程序代码有没有跑两次”。

如果不做幂等，常见后果包括：

• 重复扣款、重复发货、重复发送消息/短信
• 重复写入导致数据膨胀、统计翻倍
• 多次创建资源导致外部系统配额耗尽（云资源、工单、账号等）
• 任务链路因为重复写状态而进入不可预期的分支

幂等并不是“加个 if 就行”，需要从 OpenClaw 的任务模型、状态落库、重试策略、以及外部依赖的调用方式上一起落地。

先统一术语：OpenClaw 中“重复执行”从哪来

不同系统实现略有差异，但在 OpenClaw 这类任务引擎中，重复执行一般来自以下路径（你可以对照自己的部署实际）：

1. 至少一次投递（at-least-once）：队列/调度器为了可靠性，宁可多投也不漏投。
2. 重试机制：任务失败、超时、回滚失败，会触发自动重试。
3. Worker 不确定性：Worker 执行完但来不及上报就宕机；调度器认为未完成，又派发一次。
4. 手工重跑/补偿：运维或业务同学“重跑任务”用于修复。
5. 任务分片/并发：同一业务事件被不同入口触发，或并发执行同一资源的任务。

因此，设计目标不是“避免重复”，而是：允许重复发生，但结果正确、可验证、可追踪。

幂等设计的三种主流落地方向（建议组合使用）

在 OpenClaw 任务里，通常有三层可做幂等：

1）任务层幂等：同一业务请求只创建一个任务实例

核心：用业务幂等键（Idempotency Key）约束“任务创建”。

• 适用：由 API/事件触发创建任务的场景（例如“订单支付成功”触发发货流程）。
• 做法：在创建任务前先生成一个稳定的 key（例如 orderId + action），在任务表对该 key 建唯一索引。

示例：幂等键建议组成

• biz_type：业务类型，如 SHIP_ORDER
• biz_id：业务主键，如 orderId=123
• biz_action：动作，如 CREATE_SHIPMENT
• biz_version（可选）：同一订单允许多次发货/换货时区分批次

最终 key 形如：SHIP_ORDER:123:CREATE_SHIPMENT:v1

落地要点

• “创建任务”接口需要做到：

  • 若 key 不存在：创建任务并返回 taskId
  • 若 key 已存在：直接返回已有 taskId（而不是报错）
• 唯一索引冲突要转为“幂等命中”语义

这一层可以把大量重复挡在门外，但不足以覆盖：任务已创建后被重复执行的情况。

2）执行层幂等：同一任务实例重复运行不改变最终结果

核心：让 Step/Handler 的业务写操作可安全重复。

常见手段：

• 基于状态机：只有从特定状态才能推进到下一状态（CAS 更新）
• 去重表：对“副作用”打唯一约束（如消息发送、扣减库存）
• 外部系统幂等：调用下游时传入 idempotency_key，让下游保证不重复

3）副作用层幂等：每个外部副作用都“可判定已发生”

副作用包括：

• 写 DB（插入/更新）
• 发消息（MQ / webhook）
• 调外部 API（支付、物流、云资源）

要做到：任何副作用都能通过某个唯一键查询是否已经执行过。

实操：在 OpenClaw 任务里设计一套“幂等护栏”

下面给出一个可直接套用的分层方案。你不需要一次上全套，但建议至少覆盖“执行层 + 副作用层”。

H3 1）为每个任务定义稳定的业务幂等键

目标：同一业务事件重复触发时，能映射到同一个任务或同一组可识别的任务。

建议规则：

• key 必须来自业务输入（不要用随机数）
• key 必须稳定可复现（重试/重放时一致）
• key 必须能表达“这次动作到底是什么”

示例：订单发货任务

• biz_type=ORDER
• biz_id=orderId
• biz_action=SHIP
• biz_version=shipmentNo（无则默认 1）

组成：ORDER:{orderId}:SHIP:{shipmentNo}

H3 2）任务状态推进使用“乐观锁/CAS”，避免重复推进

目标：同一任务被两个 Worker 同时执行时，只有一个能成功推进状态。

建议把关键状态推进写成：

• 条件更新：update ... set status = NEXT, version=version+1 where task_id=? and status=CUR and version=?
• 若影响行数为 0：说明已经被其他执行者推进或状态不匹配，当前执行者应停止并刷新状态

这样可以避免：两个 Worker 都认为自己“完成了这一步”。

H3 3）为“每个外部副作用”建立幂等记录（推荐：Outbox/Effect 表）

目标：把“是否做过某个副作用”变成可查询、可唯一约束的事实。

你可以设计一张表（名字随意），例如 task_effect：

• effect_id（主键）
• task_id
• effect_type（如 SEND_MQ / CALL_API / DB_WRITE）
• effect_key（唯一：幂等键）
• status（INIT/SUCCESS/FAIL）
• payload_digest（可选：请求摘要，辅助排查）
• created_at/updated_at

唯一约束建议：unique(effect_type, effect_key)

其中 effect_key 典型构成：

• taskId + stepName + businessKey

例如：SEND_MQ:task123:stepNotify:ORDER_1001_SHIP

执行副作用时遵循固定流程：

1. 先插入 task_effect(INIT)（或使用 INSERT ... ON CONFLICT DO NOTHING）
2. 如果插入成功：说明第一次执行 -> 执行副作用

3. 如果插入失败（唯一冲突）：说明做过/正在做 -> 查询状态

   • 若 SUCCESS：直接返回成功（幂等命中）
   • 若 INIT/FAIL：根据策略重试或人工介入
4. 副作用成功后更新 task_effect 为 SUCCESS

这种模式的好处是：即使 Worker 崩溃在“副作用完成但未上报”的尴尬窗口，也能通过 task_effect 的存在来判断执行进度，并避免重复。

H3 4）调用外部 API：尽量使用下游幂等能力，并记录请求签名

如果下游支持 Idempotency-Key（很多支付/创建类 API 都支持），务必使用。

建议：

• Idempotency-Key = effect_key（与上面 task_effect 保持一致）
• 记录请求参数摘要：如对关键字段做 hash（避免存敏感信息）

这样当你排查“为什么结果不一致”时，可以对比：

• 同一个 key 是否发送过不同 payload（这通常是上游 bug）

落地示例：订单发货任务的幂等实现（从创建到通知）

下面用一个相对完整的链路示例说明怎么“组合拳”。假设发货任务包含三个步骤：

1. 校验订单状态
2. 创建物流单（调用物流系统 API）
3. 发送“已发货”通知消息（MQ）

H3 A）任务创建幂等（避免重复生成任务）

• 幂等键：ORDER:{orderId}:SHIP:{shipmentNo}
• 任务表加唯一索引：unique(biz_key)

创建逻辑：

• 先尝试插入任务
• 若唯一冲突：查询并返回既有任务 ID

这保证“同一订单同一批次发货”不会生成一堆任务。

H3 B）执行步骤幂等：用 effect 记录“创建物流单”

关键副作用：调用物流系统创建运单，返回 trackingNo。

• effect_type = CALL_API
• effect_key = ORDER:{orderId}:SHIP:{shipmentNo}:CREATE_WAYBILL

执行流程（伪步骤）：

1. 尝试插入 task_effect(effect_type, effect_key, INIT)
2. 若插入成功：调用物流 API（带 Idempotency-Key=effect_key）

3. API 成功：

   • 将 trackingNo 写入业务表（更新操作也要幂等：按 orderId+shipmentNo 更新）
   • 更新 task_effect 为 SUCCESS，并记录返回摘要

4. 若插入失败：

   • 查 task_effect
   • 如果已 SUCCESS：直接读取业务表已有 trackingNo，继续后续步骤

这样即使 OpenClaw 把该 Step 重跑 10 次，也只会创建一次运单。

H3 C）通知消息幂等：Outbox + 去重 key

关键副作用：发 MQ 通知下游（库存/客服/用户通知等）。

常见坑：消息系统“至少一次投递”，即使你只发送一次，下游也可能收到两次。因此建议双向幂等：

• 发送端：OpenClaw 侧用 task_effect 控制只发送一次
• 消费端：下游按 messageId 或业务键去重

在 OpenClaw 侧：

• effect_type = SEND_MQ
• effect_key = ORDER:{orderId}:SHIP:{shipmentNo}:EVENT_SHIPPED
• messageId = effect_key（或其 hash）

流程：

1. 插入 effect INIT
2. 发送 MQ（携带 messageId）
3. 更新 effect SUCCESS

如果 Worker 在“消息已发出但 effect 未更新 SUCCESS”时崩溃，会导致重试再次发送。为了进一步缩小窗口，可以把发送改为 Outbox：

• 先把消息写入 outbox 表（同样按 messageId 唯一约束）
• 由独立 dispatcher 负责投递并更新状态

这会显著提升整体幂等与可恢复性。

常见陷阱与对策（OpenClaw 场景高频）

1）把幂等建立在“先查再写”上

模式：先 select 看有没有，再 insert。

问题：并发下会产生竞态条件（两个并发都查不到，然后都插入）。

对策：

• 使用数据库唯一约束 + 原子 upsert
• 或使用 CAS 更新

2）只做任务创建幂等，不做执行幂等

任务创建幂等只能挡住“重复创建”，挡不住“同一任务被重复执行”。

对策：至少为关键副作用加 task_effect 或下游幂等键。

3）将“幂等”误解为“失败就不重试”

幂等的目标是“可安全重试”，不是“不要重试”。

对策：

• 把副作用拆分为可重试阶段
• 对不可重试的外部调用（例如非幂等的扣款接口）必须补齐幂等键或改为先冻结后确认

4）幂等键设计不稳定

例如把时间戳、随机数、workerId 放进 key，会导致每次重试都不一样，幂等失效。

对策：幂等键必须由业务主键 + 动作构成。

建议的检查清单：你在 OpenClaw 里是否真的“幂等”

上线前用这份清单做自测：

1. 同一业务事件重复触发：是否只创建一个任务实例（或可识别的同一组实例）？
2. 同一任务并发执行：是否只能有一个执行者成功推进关键状态（CAS/锁）？
3. 每个外部副作用：是否都有唯一的 effect_key，并有落库记录可追溯？
4. 调用下游创建类 API：是否传递了 Idempotency-Key？
5. 消息通知：是否有 messageId，并确保消费端可去重？
6. Worker 在任意步骤崩溃后重启：是否能从 effect/状态恢复，不会重复产生副作用？
7. 监控与排障：是否能通过 biz_key/effect_key 快速定位一次业务动作的所有执行痕迹？

小结：推荐的最小可用落地组合

如果你希望在 OpenClaw 的任务体系里快速落地幂等，且成本可控，建议从这套“最小组合”开始：

• 任务创建：biz_key 唯一约束（可选但强烈建议）
• 关键副作用：task_effect（或 outbox）+ effect_key 唯一约束（强烈建议）
• 状态推进：CAS 更新避免并发重复推进（建议）

做到这三点，即使 OpenClaw 因为重试、崩溃恢复、重复投递而让任务重复执行，你也能保证：结果一致、可恢复、可审计，并且能用 effect 记录快速解释“为什么没有重复创建/为什么没有重复发送”。