跳转至

重试策略

目标

  • 按每个 HTTP 请求重试,而不是按多步骤流程重试。
  • 仅重试当前步骤以保持顺序。
  • 避免重复非幂等操作。

默认值

以下默认值适用于渠道发送。模型请求使用下面的恢复策略。

设置 默认值 适用范围
尝试次数 3 下面的每个信封
抖动 0.1 (10%) 下面的每个信封
最小延迟 400 ms 共享渠道信封:Telegram 以及任何未覆盖的渠道
最小延迟 500 ms Discord 发送和 Discord REST 调用
最大延迟上限 30000 ms 共享渠道信封和 Discord 发送
最大延迟上限 300000 ms Discord REST API 调用

这些是每请求级别的信封。Discord Gateway WebSocket 重连循环是独立的,不使用这些设置:它允许最多 50 次重连尝试,并从 2000 ms 开始指数退避,上限为 30000 ms,且无抖动。

行为

模型提供商

Agent 运行会自动恢复临时的速率限制、过载和提供商故障,然后才会显示最终错误。速率限制最多可进行 10 次总尝试;其他瞬时故障允许在 90 秒重试窗口内进行 8 次重试。一次成功完成的模型响应会清除中断窗口,因此故障之间有用的模型和工具工作不会消耗该窗口。部分流、失败响应以及仅有工具活动不会清除该窗口。整个运行过程中的重试次数保持有界。退避从约一秒开始,指数增长,并加入抖动以分散并发重试。提供商的节奏控制,包括 retry-after、retry-after-ms 以及“请在 … 后重试”等提示,会设置最小等待时间,即使超过 30 秒的退避上限也如此。取消操作和运行截止时间仍会停止恢复。

恢复会继续现有转录,并带有指令以保留已完成的工作,并在决定是否重复这些操作之前检查被中断的操作。它可以在工具活动或部分输出后从限流中恢复,而无需重新提交原始用户请求。运行在等待期间显示一个瞬时重试指示器,并且仍然可取消。已恢复的尝试不会留下持久化的助理错误;只有最终失败会保留一个错误。计费失败、身份验证错误和提供商拒绝不会使用这个瞬时重试预算。

空错误响应体不会使确定性 HTTP 客户端错误可重试。无响应体的 400 和 422 响应会直接呈现,而不会静默重新提交错误;带有可识别瞬时重试证据的客户端错误仍遵循现有恢复策略。空成功响应保留其独立的响应修复重试。

在嵌入式运行时中,当最新批次中的每个工具都有记录结果且所有工具执行均已结束时,工具活动后的模型空闲超时也会使用这种恢复机制。下一次尝试会保持工具可用以完成任务,包括处理已记录的工具失败。待处理的审批、异步工具活动、有意终止工具、取消操作和运行截止时间仍会阻止这种继续。已完成的操作不会被重新提交。

在终止事件之前结束的 Responses 流也符合瞬时恢复的条件,包括工具调用尚未完成的情况。部分工具参数绝不会被执行。带有不一致工具调用身份的已完成响应不视为断开连接的流。Gemini 或 Vertex AI 流在事件帧中间结束时也以同样方式符合条件;但整个损坏的 JSON 帧不符合。

如果 Responses 请求在生成工具调用时达到其输出 token 限制,嵌入式运行器也会在被接纳的工具结束后,根据记录结果自动继续。它会保持相同的模型和账户,保留已完成的操作,并且绝不执行部分参数。这种继续与重试计数预算和运行截止时间共享,但不共享 90 秒的中断窗口:生成完整响应可能需要更长时间。取消操作、待处理的审批、进行中的异步工作和有意终止工具仍会停止继续。提供商拒绝和未知的不完整响应原因不符合条件。

已耗尽的订阅、每日、每周或每月用量窗口会直接进入符合条件的认证配置文件或模型回退。单独的 Retry-After 值并不构成用量窗口耗尽:临时限流仍会遵循提供商的最小等待时间,但不超过保存的 retry.provider.maxRetryDelayMs(默认 60 秒)。当配置了回退时,超过该上限的速率限制下限会直接进入回退,因为运维人员已经说明了服务器请求的等待可以占用运行多长时间;未配置回退时,该下限将被完全遵循,而 maxRetryDelayMs: 0 会禁用该上限。

模型故障转移控制器 拥有此恢复预算。一旦预算耗尽,OpenClaw 会遵循符合条件的认证配置文件或模型回退路径,或呈现最终失败。原生工具框架可能会在向 OpenClaw 返回最终失败之前,在内部重试单个请求;这些内部重试与 OpenClaw 的继续预算分开。

ChatGPT SSE 错误会将 HTTP 状态和 Retry-After 一起保留,因此即使其消息或提供商代码不熟悉,瞬时 HTTP 响应仍可重试。ChatGPT 传输层会在流式传输前针对 websocket_connection_limit_reached 单独重新连接一次;这不是 SSE HTTP 响应重试。

对于保留内部重试的 SDK 调用,基于 Stainless 的 SDK(如 Anthropic 和 OpenAI)可以在可重试响应(408、409、429 和 5xx)上接收 retry-after-ms 或 retry-after。当该等待时间超过 60 秒时,OpenClaw 会注入 x-should-retry: false,以便 SDK 迅速返回控制权。可使用 OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS=<seconds> 覆盖此仅限 SDK 的上限。将其设置为 0、false、off、none 或 disabled,即可让这些 SDK 调用在内部遵循较长的 Retry-After 休眠。

托管 Git 操作

共享 Git runner 会在命令原始超时内延迟一秒后,对瞬时的 fetch 和 ls-remote 失败重试一次。这包括对象传输不完整、连接重置、临时 DNS 失败以及瞬时 HTTP 错误。托管项目克隆使用相同策略,并在重试前移除其失败的部分检出。取消会停止重试,并在再次尝试前再次检查工作区或发布权限。每次计划的重试都会写入一条 git/network 警告,包含操作、尝试次数、延迟和退出码。它省略命令参数、仓库 URL 和原始 Git 输出。

身份验证失败、仓库或 refs 缺失、本地存储失败、进程终止以及命令超时耗尽均不会重试。push 和 pull 不会被此 runner 重放:已接受的写入之后可能出现连接失败,因此发布流程保留其现有的远程结果对账机制。此策略不会包装由代理或设置脚本运行的任意 Git 命令。

Discord

  • 在速率限制错误(HTTP 429)、请求超时、HTTP 5xx 响应以及瞬时传输故障(例如 DNS 查找失败、连接重置、套接字关闭和 fetch 失败)时重试。
  • 在可用时使用 Discord retry_after,否则使用指数退避。
  • 如果无法读取错误响应体,则收到的 HTTP 状态和速率限制头仍会决定重试。永久的 401、403 和 404 拒绝不会重试。

Telegram

  • 使用内置传输时,新的文本消息和富文本消息会使用全新的 HTTP 连接,避免初始预览、回复和终止错误使用过期的 keep-alive 套接字。轮询、编辑和控制请求保留连接池。这会使每条新文本消息增加一次连接握手。
  • 这些非幂等文本发送仅在 Telegram 以 flood control(429)拒绝请求,或传输层证明请求未开始时重试。发送后发生的重置、超时或响应丢失仍具有歧义,不会被重放。
  • 幂等操作(包括预览编辑)可以重试瞬时网络故障和 HTTP 5xx 响应,而不会替换现有消息。
  • 在可用时使用 retry_after,否则使用指数退避。
  • HTML/Markdown 解析错误不会重试;首次尝试时会回退到纯文本。

配置

Discord 和 Telegram 频道的重试时序是内置的,无法在 openclaw.json 中配置。

嵌入式运行时的现有会话设置 retry.provider.maxRetries 会覆盖其恢复重试预算;0 会禁用重试,速率限制仍保持最多 10 次总尝试的上限。这是一个嵌入式会话设置,而不是 openclaw.json 键,它不会配置原生 harness 请求重试。自动恢复无需新配置。

备注

  • 重试按请求应用(消息发送、媒体上传、reaction、poll、sticker)。
  • 复合流程不会重试已完成的步骤。

持久出站投递

持久出站队列有独立的投递尝试预算。当投递使用生产者声明时,预留操作会在扣除一次尝试之前检查确切的所有者及其租约。过期或被替换的声明不会消耗剩余预算;恢复可以在重试前获取新的声明。

生产者租约持续 60 秒,并在所有者处于活动状态时每 20 秒续期一次。这可以容忍短暂的 Gateway 停顿;消失的生产者的恢复会等待其最后一个租约过期。

租约过期不会抹除发送已经开始的证据。这些条目在重放前仍需要对账,且未被替换的所有者可以记录迟到结果,而不会授权另一次发送。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw