OpenClaw Retry Policy Explained

Retry logic is one of those features you only notice when it is wrong. OpenClaw's docs make the design goal explicit: retry per HTTP request, not per whole multi-step flow. That sounds small, but it is exactly how you avoid duplicate sends, duplicate uploads, or repeated side effects after half a workflow already succeeded. The system is trying to preserve ordering, recover from transient failures, and avoid making bad situations noisier.

The defaults are conservative on purpose

The documented defaults are 3 attempts, a maximum delay cap of 30000 milliseconds, and jitter of 0.1. Channel-specific minimum delays are also documented, with Telegram at 400 ms and Discord at 500 ms. Those numbers are not aggressive. They are there to smooth over transient issues and rate limits without turning the gateway into an endless retry machine. The retry model is deliberately bounded.

Different providers get different behavior

Model providers largely keep their own short retry behavior through the provider SDKs, but OpenClaw adds an important safeguard for long Retry-After delays. For Stainless-based SDKs such as Anthropic and OpenAI, retryable responses like 408, 409, 429, and 5xx can include retry-after-ms or retry-after. If that wait is longer than 60 seconds, OpenClaw injects x-should-retry: false so the SDK surfaces the error immediately and failover can move to another auth profile or fallback model.

That behavior is tunable through OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS. Set it to a number if you want a different threshold, or disable the cap with values like 0, false, off, none, or disabled if you want the SDK to honor long Retry-After waits internally. The docs are effectively telling you to choose between patience and fast failover. For operators balancing uptime and latency, that is a meaningful decision.

Channel retries are narrower than people expect

Discord retries only on rate-limit errors, specifically HTTP 429, and it uses Discord retry_after when available. Telegram retries on transient errors such as 429, timeouts, connection resets, closed connections, or temporarily unavailable responses. Telegram also has one nice safety rule: Markdown parse errors are not retried forever. They fall back to plain text instead. That is a pragmatic move because malformed formatting is not a transient network issue.

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

The operator lesson

The best part of the docs is the part that says retries apply per request, including message sends, media uploads, reactions, polls, and stickers, but composite flows do not retry completed steps. That is the right philosophy. Retrying the current failing edge is useful. Blindly replaying the full workflow is how you send the same thing twice and spend an afternoon explaining it. OpenClaw's retry policy is not trying to be heroic. It is trying to be safe, predictable, and scoped to the thing that actually failed.

Another useful detail in the docs is that retries are not only about transport health. They are also about protecting idempotency assumptions. Message sends, reactions, uploads, and polls are all handled as individual retry edges so OpenClaw can recover from the failing call without replaying earlier successful actions. That is the kind of discipline you only appreciate after a duplicate send incident, which is exactly why the retry docs are worth reading before you hit one. It also explains why the platform prefers bounded backoff over heroic infinite recovery loops.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.