Retry policy

Goals

• Retry per HTTP request, not per multi-step flow.
• Preserve ordering by retrying only the current step.
• Avoid duplicating non-idempotent operations.

Defaults

• Attempts: 3
• Max delay cap: 30000 ms
• Jitter: 0.1 (10 percent)
• Provider defaults:
  • Telegram min delay: 400 ms
  • Discord min delay: 500 ms

Behavior

Model providers

• OpenClaw lets provider SDKs handle normal short retries.
• For Stainless-based SDKs such as Anthropic and OpenAI, retryable responses (
  text

  Copy

  408
  ,
  text

  Copy

  409
  ,
  text

  Copy

  429
  , and
  text

  Copy

  5xx
  ) can include
  text

  Copy

  retry-after-ms
  or
  text

  Copy

  retry-after
  . When that wait is longer than 60 seconds, OpenClaw injects
  text

  Copy

  x-should-retry: false
  so the SDK surfaces the error immediately and model failover can rotate to another auth profile or fallback model.
• Override the cap with
  text

  Copy

  OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS=<seconds>
  . Set it to
  text

  Copy

  0
  ,
  text

  Copy

  false
  ,
  text

  Copy

  off
  ,
  text

  Copy

  none
  , or
  text

  Copy

  disabled
  to let SDKs honor long
  text

  Copy

  Retry-After
  sleeps internally.

Discord

• Retries only on rate-limit errors (HTTP 429).
• Uses Discord
  text

  Copy

  retry_after
  when available, otherwise exponential backoff.

Telegram

• Retries on transient errors (429, timeout, connect/reset/closed, temporarily unavailable).
• Uses
  text

  Copy

  retry_after
  when available, otherwise exponential backoff.
• Markdown parse errors are not retried; they fall back to plain text.

Configuration

Set retry policy per provider in

:

json5
Copy
{
  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