1. 为什么 Agent 系统比普通服务更怕重复请求OpenClaw Gateway 的幂等性处理核心就一句话同一个操作执行一次和执行一百次效果完全一样。听起来像老生常谈但放到 Agent 场景里这件事的权重会被放大好几倍。普通 HTTP 服务一次请求可能几十毫秒就结束了重复一次无非多查一次库而 Agent 的一次运行往往要串起多个工具调用跑几十秒到几分钟中间还夹着模型推理、外部 API、文件写入、消息发送。这个时间窗口越长网络断连、客户端超时重试、消息队列重投的概率就越高。你可以把 Agent 请求想象成一次“代客办事”客户把任务交给助理助理跑出去打电话、填表、发通知。如果客户因为没收到回执又派了一个助理两个助理可能同时去发同一条通知用户就收到两条。更糟的是如果任务里包含“扣款”“删文件”“发邮件”这类动作重复执行的代价不是多花点算力而是真实世界的副作用。OpenClaw 的 Gateway 层就是那个“前台接待”它要在请求真正进入 Agent 执行链路之前先判断这个请求是不是已经来过了。判断依据是一个幂等键idempotencyKey通常由客户端生成一个 UUID随请求一起带上。Gateway 拿这个键去 dedupe Map 里查命中就直接把上次的结果返回没命中才放行执行执行完再把结果快照存回去。这套机制不复杂但键怎么设计、Map 生命周期怎么管、副作用已经发生怎么办才是真正决定系统稳不稳的地方。2. TaoToken 前置把模型调用和 Gateway 幂等串起来在动手配 Gateway 之前得先让 Agent 背后的模型调用有个稳定的入口。我自己的做法是先把模型访问层统一到 TaoToken 上这样 Gateway 里配置的模型端点、密钥、超时参数都能集中管理排查幂等问题时不会因为模型侧抖动而混淆视听。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。你需要先在控制台创建一个 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完在 API Keys 页面复制出来页面地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你只是想先验证模型通不通可以直接用模型对话页面发一条测试消息 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。这一步的目的是确认模型侧返回正常这样后面 Gateway 幂等测试里如果出现异常就能快速排除是模型问题还是去重逻辑问题。对于长期跑编码类 Agent 的场景可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了不同语言 SDK 的调用方式。如果你用的是 Claude Code 这类工具对应的 Anthropic 兼容接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。把这一层准备好之后Gateway 的幂等配置才有意义因为你知道模型调用本身是可控的剩下的重复问题就集中在 Gateway 的 dedupe 逻辑上。3. OpenClaw Gateway 幂等配置骨架与 dedupe Map 参数OpenClaw 的 dedupe Map 本质上是一个带 TTL 和容量上限的内存缓存。它的键是agent:${idempotencyKey}这种带命名空间前缀的形式值是一份响应快照包含 ok、payload、error 三个字段。Gateway 在处理 Agent 请求时的典型逻辑是这样的// src/gateway/server-methods/agent.ts const idem request.idempotencyKey; const cacheKey agent:${idem}; const cached context.dedupe.get(cacheKey); if (cached) { respond(cached.ok, cached.payload, cached.error, { cached: true }); return; } // 未命中真正执行 Agent 链路 const result await runAgent(request); // 执行完成后写入 dedupe Map context.dedupe.set(cacheKey, { ok: result.ok, payload: result.payload, error: result.error, timestamp: Date.now(), }); respond(result.ok, result.payload, result.error, { cached: false });这段骨架里最关键的是三个参数TTL、最大条目数、以及键的命名空间。TTL 决定一个幂等键在多久内有效超过这个时间就允许同一个键再次执行。最大条目数决定 Map 最多存多少条记录超了就按时间戳淘汰最老的。命名空间前缀则是为了避免不同业务线的幂等键互相碰撞比如agent:和send:分开。下面是一份可以直接参考的配置示例参数值需要根据你的 Agent 最大执行时间来调整// src/gateway/config/dedupe.ts export const DEDUPE_CONFIG { // 幂等键有效期单位毫秒 // 建议 Agent 最大执行时间 * 2 ttlMs: 10 * 60 * 1000, // 最大缓存条目数超出按 timestamp 淘汰最老 maxEntries: 50000, // 清理周期单位毫秒 sweepIntervalMs: 30 * 1000, // 键前缀按业务线区分 keyPrefix: { agent: agent:, send: send:, chat: chat:, }, };TTL 的设置逻辑很直白如果一个 Agent 最长跑 5 分钟那 TTL 至少设到 10 分钟给客户端重试留出足够窗口。如果 TTL 设得太短客户端在 TTL 过期后重试Gateway 会认为这是一个新请求重复执行就发生了。如果设得太长内存占用会上升但因为有条目数上限兜底实际风险可控。维护逻辑在src/gateway/server-maintenance.ts里定期扫描 Map把超过 TTL 的条目删掉同时检查条目数是否超过 maxEntries超了就按 timestamp 排序淘汰最老的。一个条目大概就是一个 UUID 加一份响应快照几万条也就几十 MB对现代服务来说压力不大。消息发送场景比普通 Agent 请求更复杂因为“发消息”这个动作本身不幂等。OpenClaw 在send.ts里加了一层 inflightMap用来防止并发发送同一条消息。dedupe Map 管的是“历史上发过没有”inflightMap 管的是“当前是不是正在发”。两层叠加之后基本堵死了重复发送的可能。Chat 方法还有第三层保护用transcriptHasIdempotencyKey()检查对话历史里是否已经存在某个幂等键避免重复追加消息。4. 验证重复请求命中缓存完整步骤与结果配置写完之后必须实际验证一遍确认重复请求真的命中了缓存而不是重新执行。下面是我常用的验证流程你可以跟着操作。第一步启动 Gateway确认 dedupe 配置已加载。可以在启动日志里搜dedupe关键字看到 TTL 和 maxEntries 的输出就说明配置生效了。第二步构造一个带幂等键的 Agent 请求。用 curl 发一个最简单的请求幂等键用一个固定的 UUIDcurl -X POST http://localhost:8080/api/agent/run \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { idempotencyKey: 11111111-2222-3333-4444-555555555555, prompt: 帮我统计当前目录下的文件数量, model: gpt-4o-mini }第一次请求会正常执行返回结果里cached字段是 false。记下这次返回的 payload。第三步用完全相同的幂等键再发一次curl -X POST http://localhost:8080/api/agent/run \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { idempotencyKey: 11111111-2222-3333-4444-555555555555, prompt: 帮我统计当前目录下的文件数量, model: gpt-4o-mini }如果幂等生效第二次返回的cached字段应该是 truepayload 和第一次完全一致而且响应时间会明显短于第一次因为 Gateway 没有真正执行 Agent 链路直接返回了缓存快照。第四步换一个幂等键再发一次确认新键会正常执行cached回到 false。这一步是为了排除“所有请求都被缓存”的误判。第五步等 TTL 过期后再用第一个幂等键发一次确认此时会重新执行。这一步验证 TTL 清理逻辑是否正常工作。如果 TTL 设的是 10 分钟你可以临时把配置改成 10 秒来快速验证验证完再改回去。实测下来这套验证流程能覆盖 dedupe Map 的命中、未命中、过期三种状态。如果你在第二步看到cached: true但 payload 和第一次不一致那说明缓存写入逻辑有问题需要检查写入时是否用了正确的键和快照。5. 本篇常见错排查5.1 重复请求没有命中缓存最常见的原因是幂等键不一致。客户端每次重试都生成新的 UUIDGateway 自然认为是新请求。解决办法是客户端在第一次发起请求时生成 UUID 并本地缓存重试时复用同一个键。消息平台 Webhook 场景更简单平台本身每条消息都有唯一 ID直接拿来当幂等键即可。另一个原因是键的命名空间不匹配。比如写入时用了agent:${idem}查询时用了${idem}两边对不上。检查代码里 get 和 set 是否用了同一个 keyPrefix。5.2 dedupe Map 内存持续增长如果 maxEntries 设得太大或者清理周期太长Map 会一直涨。检查server-maintenance.ts里的 sweep 逻辑是否真的在跑以及 maxEntries 是否被设成了一个不合理的值。正常情况下几万条条目占用几十 MB如果发现内存涨到几百 MB先看条目数是不是远超 maxEntries。5.3 进程重启后幂等失效内存 dedupe Map 在进程重启后会丢失这是设计上的取舍。对于单实例部署重启窗口很短实际风险不大。如果业务不能接受这个窗口需要把幂等状态持久化到 Redis 或数据库。用 Redis 的话可以用 SETNX 加过期时间来实现键就是幂等键值就是响应快照。代价是每次请求多一次 IO得根据业务容忍度权衡。5.4 分布式多实例下幂等不生效单实例的内存 Map 搞不定多实例场景因为同一个幂等键的请求可能落到不同节点。两种解法一是换成集中式存储比如 Redis二是在请求入口加一致性哈希保证同一个幂等键总是路由到同一个实例。前者更通用后者性能更好但需要额外的路由层。5.5 工具已经产生副作用怎么办这是最棘手的情况。OpenClaw 的策略是防止重复触发不做自动回滚。已经执行的副作用就让它留着重点保证后续不会再重复执行。实践中一般从三个层面缓解让工具本身尽量幂等比如“写入文件”天然幂等“发送消息”就不行对不可幂等的工具在工具侧做去重比如发消息前先检查这条消息是否已经发过接受“至多一次”语义宁可漏执行也不重复执行对很多业务场景来说漏发一条通知比重复发十条要好得多。如果确实需要补偿可以在工具侧记录操作日志副作用发生后如果发现是重复触发用日志里的反向操作去抵消。但这条路成本很高而且不是所有操作都有反向操作所以更现实的做法还是在前置去重上多下功夫。6. 把幂等当成 Agent 的基础设施来对待Agent 系统的幂等性不是一个可以事后补的功能它应该和日志、监控一样从第一天就设计进去。OpenClaw Gateway 的 dedupe Map 提供了一个轻量但有效的起点一个 UUID、一个带 TTL 的内存缓存、一套清理逻辑就能挡住大部分重复请求。但你要清楚它的边界内存不持久、单实例不跨节点、副作用不回滚。在这些边界之内它足够好用超出边界就得引入 Redis 或一致性哈希来补强。如果你还在搭 Agent 的早期阶段建议先把幂等键的生成和传递规范定下来客户端怎么生成、怎么缓存、怎么重试这些约定比具体实现更重要。模型调用层可以用 TaoToken 统一收口Gateway 层把 dedupe 配置写清楚工具层尽量设计成幂等操作。三层各管一段组合起来才能让 Agent 在真实网络环境里跑得稳。