OpenClaw 网关死信队列与工具调用安全重放（2026）：毒消息隔离、契约漂移、幂等 drain、与熔断器和指标协同，以及在云 Mac mini 上的 macOS 演练

当智能体网关把流量扇出到大量 HTTP 工具时，总有一些失败无法靠指数退避“熬过去”：参数永远通不过 JSON Schema、上游在证书轮换窗口持续返回 5xx、或租户策略禁止自动重试写入。到 2026 年，成熟的 OpenClaw 部署会把这些终态失败隔离进死信队列（DLQ），让 SRE 在受控吞吐下检查、修正并重放，而不是让热点线程池被毒消息占满。本文说明入队条件、信封字段、与 幂等键与去重 的衔接、与 熔断器 的 drain 协同、该在 Prometheus 上暴露哪些深度与成功率指标，以及如何用 日志脱敏与轮转 保留审计价值。

成本视角：在 MacHTML 以约 每天 16.9 美元 租用专用 Mac mini 预演死信 drain，比生产环境因重复重放导致重复扣款或 CRM 双写的事故便宜一个数量级。

为什么仅有重试队列不够

重试队列假设故障在秒级恢复；但合作伙伴在灰度时改字段名、向量库在分片再均衡时连续 12 分钟 500、或企业出口策略突然拦截域名，都会让“无限重试”变成放大器。若失败请求仍占用 worker，模型流式输出会被拖慢，内存里悬挂的 trace 与缓冲也会推高 OOM 风险。把终态与未知类型错误转入 DLQ，可以把热点路径从“等一个可能永不成功的上游”解放出来。

经验阈值（仅供起步）：对幂等读接口，内联重试不超过 3 次、总窗口 2.5 秒；超过仍失败则按错误类分流——可恢复网络抖动留在热队列，契约/策略/毒参数直接进入死信。对缺幂等键的写，要么快速向规划器返回结构化错误，要么进入需人工审批的死信分区，绝不能默默循环。

OpenClaw 一次规划可能并行触发六个工具：必须为每个工具划分 DLQ 分区（按 tool_name + 租户），避免 CRM 毒包阻塞健康计算器工具的 drain。

毒消息与 Schema 拒收

毒消息指不改代码或数据就永远不可能成功的载荷：网关 JSON Schema 校验失败、被出口策略拒绝的 URL、或指向已下线能力的工具名。应立即打上 failure_class（如 SCHEMA_REJECT、EGRESS_DENY），并附带原始 request_id 以便客服工单对齐。

契约漂移要记录 tool_contract_version，例如 20260425.3，并在运维手册写明“若版本早于 14:00 UTC 的热修复，则优先尝试自动重放”。留存期常见为 14 天、单分区磁盘预算 500 MB；超期自动 tombstone，同时递增 dlq_expired_total 以满足删除证明与统计。

批量索引场景下，若 100 条里 5 条校验失败，应按行级拆死信，避免整批回滚拖累其余 95 条成功路径。

死信信封必备字段

除原始参数外，信封至少包含：tenant_id、request_id、idempotency_key 或显式空、tool_name、tool_version、first_seen_at、last_error_code、retry_count、failure_class，以及限幅在 4 KB 内的脱敏 HTTP 头副本。正文若超过 256 KB，应写对象存储指针，避免 Redis 或 Kafka 单条过大阻塞复制。

{
  "dlq_version": 1,
  "request_id": "req_9f2c…",
  "idempotency_key": "idem_7a91…",
  "tool": {"name": "crm_search", "contract": "20260425.3"},
  "failure_class": "UPSTREAM_TIMEOUT",
  "retry_count": 3,
  "last_http_status": 504,
  "first_seen_at": "2026-04-25T01:12:04Z"
}

令牌与刷新凭证只能写 Vault 引用路径，例如 vault://tenant/42/oauth，由重放 worker 在执行时再取，避免磁盘快照泄露。

重放安全与人工门槛

无幂等的重放等于主动制造双写发票。要么在 TTL（常见 24–72 小时）内复用原幂等键，要么签发新键并写 supersedes_request_id 让下游识别“有意二次执行”。人工 drain 建议从每条依赖每秒 1 条起步，若 5 分钟内错误率低于 0.5% 再线性提速；并为并发加操作员级配额，避免两名值班同时把吞吐翻倍。

对资金/写库类工具，可在信封要求双人审批标记后才允许 worker 出队；CI 触发的自动重放应使用独立服务账号，密钥 30 天轮换，指标标签与人工 drain 分离。

与熔断器状态机协同

熔断打开时禁止盲目 drain，否则等于向正在恢复的故障源二次投毒。正确顺序是：观察半开探测成功后，再启用受控 drain，并在熔断再次打开时自动暂停并递增 dlq_drain_paused_total。细节参见上文熔断器专题。若上游返回 429 且带 Retry-After，drain 侧应像普通客户端一样尊重该头并加 250 毫秒 以内抖动，避免多 worker 齐步走。

指标与 48 小时处置 SLO

至少导出：dlq_depth 按工具分区、dlq_ingress_total{failure_class}、dlq_replay_success_total、dlq_replay_failure_total、从首次失败到成功重放的 dlq_age_seconds 直方图、以及合规用的 dlq_expired_total。示例 SLO：48 小时内 95% 死信要么成功重放要么被显式处置（丢弃/转工单）；单租户 15 分钟内深度超 10000 通常意味着上游大面积事故被误判为客户端错误。

日志、脱敏与合规留存

每次重放记录操作者、时间戳、新旧幂等键以及参数 diff（脱敏后）。结合 newsyslog 或 logrotate 将单文件限制在 50 MB、保留 7 代，可与 DLQ 留存对齐，便于事故周后期仍能关联。详见日志专题链接。

对比：热重试队列 / DLQ / 事务发件箱

维度	热重试队列	死信队列	事务发件箱
时延预算	毫秒级	分钟到数天	受数据库提交约束
人工介入	少见	预期流程	可选
顺序语义	按 key 尽力有序	分区内 FIFO 近似	单写者可做强一致
典型用途	短暂 5xx 浪涌	毒包、长中断、策略冻结	对本库副作用的准一次投递

值班 runbook（编号步骤）

1. 对比消息中间件控制台与 dlq_depth，排除抓取间隔造成的假峰值。
2. 随机抽样 5 条，若 failure_class 一致，合并为单根因工单。
3. 核对熔断与错误预算，再开启 drain。
4. 以每秒 1 条起步观察 dlq_replay_failure_total。
5. 结束后导出指标快照附到事故记录。

常见问题

死信与热重试能共用 Redis 吗？

可以共用机器，但应使用不同 key 前缀与内存淘汰策略，避免死信积压挤掉热重试元数据。

智能体能自动重放吗？

仅建议对只读且已证明幂等并有严格限速的工具；其余需人工意图以防自治循环。

幂等键 TTL 如何与法务对齐？

计费类可拉长到 30 天，通用工具常见 72 小时，与法务争议窗口一致即可。

可靠的死信体系一半是队列设计，一半是观测与演练。通过 MacHTML 租用 Mac mini，在原生 macOS 上与生产相近的 LaunchAgent、磁盘配额和网络栈里预演 broker、网关与 Prometheus 边车，可在真实 Safari 与桌面工具链旁完成 drain 剧本，日成本仍约为 16.9 美元，却显著降低夜间事故的情绪与时间成本。