Retry Policy for Outbound Provider Calls

Goals

• Retries happen per HTTP request, not across a multi-step sequence.
• Keep operations in order by retrying only the step currently in progress.
• Prevent duplicate execution of non-idempotent actions.

Defaults

Behavior

Model providers

• OpenClaw lets provider SDKs manage typical short retries on their own.
• For Stainless-based SDKs like Anthropic and OpenAI, retryable responses (408, 409, 429, and 5xx) may include retry-after-ms or retry-after. If that wait exceeds 60 seconds, OpenClaw injects x-should-retry: false so the SDK surfaces the error immediately and model failover can switch to another auth profile or fallback model.
• Override the cap with OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS=<seconds>. Set it to 0, false, off, none, or disabled to let SDKs respect long Retry-After sleeps internally.

Discord

• Retries occur on rate-limit errors (HTTP 429), request timeouts, HTTP 5xx responses, and transient transport failures like DNS lookup failures, connection resets, socket closes, and fetch failures.
• Uses Discord retry_after when available, otherwise exponential backoff.

Telegram

• Retries on transient errors (429, timeout, connect/reset/closed, temporarily unavailable).
• Uses retry_after when available, otherwise exponential backoff.
• HTML/Markdown parse errors are not retried; they fall back to plain text on the first attempt.

Configuration

Set retry policy per provider in ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
    discord: {
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

Notes

• Retries apply per request (message send, media upload, reaction, poll, sticker).
• Composite flows do not retry completed steps.

Related

• Model failover
• Command queue