重试策略

目标¶

• 按 HTTP 请求重试，而不是按多步骤流程重试。
• 通过仅重试当前步骤来保持顺序。
• 避免重复执行非幂等操作。

默认值¶

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

这些是逐请求的包络。Discord Gateway WebSocket 重连循环是 独立的，并且不使用它们：它最多允许 50 次重连尝试，并从 2000 ms 指数退避到 30000 ms 上限，没有抖动。

行为¶

模型提供商¶

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

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

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

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

在终止事件之前结束的 Responses 流也符合瞬时恢复条件，包括工具调用仍未完成的情况。部分工具参数永远不会执行。具有不一致工具调用标识的已完成响应不符合断开连接的流条件。

如果 Responses 请求在生成工具调用时达到其输出令牌限制，嵌入式运行器也会在已接纳工具稳定后自动从记录的结果继续。它保持相同的模型和账户，保留已完成的操作，并且从不执行部分参数。此继续共享重试次数预算和运行截止时间，但不共享 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 运行器会在命令原始超时范围内，延迟一秒后，对瞬时的 fetch 和 ls-remote 失败重试一次。这包括对象传输不完整、连接重置、临时 DNS 失败以及瞬时 HTTP 错误。托管项目克隆使用相同策略，并在重试前删除其失败的未完成检出。取消会停止重试，并且在再次尝试前会重新检查工作区或发布权限。每次计划的重试都会写入一条 git/network 警告，其中包含操作、尝试次数、延迟和退出码。它会省略命令参数、仓库 URL 和原始 Git 输出。

认证失败、仓库或引用缺失、本地存储失败、进程终止以及命令超时耗尽均不会重试。此运行器不会重放 push 和 pull：失败连接可能发生在已接受的写入之后，因此发布会保留其现有的远程结果对账。此策略不会包装由代理或设置脚本运行的任意 Git 命令。

Discord¶

• 在速率限制错误（HTTP 429）、请求超时、HTTP 5xx 响应以及瞬时传输故障（例如 DNS 查找失败、连接重置、套接字关闭和获取失败）时重试。
• 可用时使用 Discord retry_after，否则使用指数退避。

Telegram¶

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

配置¶

Discord 和 Telegram 通道的重试时序已内置，无法在 openclaw.json 中配置。

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

说明¶

• 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。
• 复合流程不会重试已完成的步骤。

持久出站投递¶

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

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

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

相关¶

• 模型故障转移
• 命令队列
• 流式传输与分块