OpenClaw Retry Policy: Keep Channel Failures From Duplicating Work

Reliable agents do not only need good answers. They need boring delivery behavior when the outside world gets flaky. A Telegram request can time out. Discord can rate-limit. A media upload can fail halfway through a channel operation. If the agent responds by replaying the whole workflow, you can get duplicate messages, repeated reactions, or a support thread that suddenly looks like the bot lost its mind.

OpenClaw's retry policy is designed around a simple operator rule: retry the current outbound request, not the whole multi-step flow. That is the important distinction. A retry should help a send survive transient channel failure. It should not replay completed work or repeat non-idempotent operations just because one HTTP request complained.

This sits after the normal message pipeline. Inbound messages are routed to a session key, queued if a run is already active, passed through the agent loop, and then delivered through outbound channel calls. If you want the adjacent queue side, read OpenClaw Command Queue. This post is about what happens when the agent already produced a reply and the channel transport is the risky part.

The mistake: retrying the story instead of the step

The fastest way to create confusing agent behavior is to retry too much. Imagine a flow that sends a message, uploads an image, adds a reaction, and posts a follow-up. If the image upload fails and the runtime restarts the entire flow, the first message can appear twice. If a poll fails and the agent reruns the entire response, the user may see two versions of the same operation.

The retry docs make the goal explicit: retries apply per HTTP request, preserve ordering by retrying only the current step, and avoid duplicating non-idempotent operations. That means OpenClaw treats a message send, media upload, reaction, poll, or sticker request as the retry unit. Completed steps are not replayed as part of a composite flow.

Bad mental model:
agent reply failed somewhere -> run the whole reply again

Better mental model:
current channel request failed transiently -> retry that request only

That sounds small, but it is the difference between a resilient channel and a duplicate factory. Operators usually notice retry bugs only after users complain about repeated messages. By then the trust damage is already visible.

What OpenClaw retries by default

The documented defaults are conservative: three attempts, a maximum delay cap of 30000 ms, and 0.1 jitter. Provider defaults set Telegram's minimum delay at 400 ms and Discord's at 500 ms.

Telegram retry handling covers transient failures such as 429, timeout, connect/reset/closed, and temporarily unavailable errors. When Telegram provides retry_after, OpenClaw uses it. Otherwise it falls back to exponential backoff. Markdown parse errors are treated differently: they are not retried as markdown forever; the documented behavior is fallback to plain text.

Discord retry handling covers rate limits, request timeouts, HTTP 5xx responses, and transient transport failures such as DNS lookup failures, connection resets, socket closes, and fetch failures. It uses Discord's retry_after value when it is available, otherwise exponential backoff. The practical operator point is the same: let the channel's rate-limit signal guide the wait, and do not guess with a hard sleep when the provider already told you what it wants.

The same retry docs also separate channel retries from model-provider retries. OpenClaw lets SDKs handle normal short model retries, but for Stainless-based SDKs such as Anthropic and OpenAI it can stop very long Retry-After sleeps, surface the error, and let model failover rotate. The cap is controlled with OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS. That is a different layer than channel delivery, and mixing the two leads to bad debugging.

The config shape

Retry policy is configured per channel provider in ~/.openclaw/openclaw.json. The docs show this shape:

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

I would not tune this casually. If a channel is rate-limiting you, the first fix is usually message volume, queue behavior, or channel-specific limits, not cranking retries into a noisy storm. Retries should smooth transient edges. They should not hide a broken sending pattern.

If your agent is now real enough that duplicate sends would hurt, you need more than a demo setup. Get ClawKit and use the operator playbook I run from every day.

Retries are not queueing

Queueing happens before or during an agent run. It decides what to do when inbound messages arrive while a session is already active: collect them, follow up, steer, interrupt, or use a backlog mode. Retry policy happens later, at the outbound provider request layer.

That distinction prevents bad debugging. If five Slack messages arrive while the agent is busy, retry settings will not make the agent respond faster. That is a queue or concurrency question. If Telegram accepts the prompt, the agent writes a good answer, and the final API request times out, that is where retry policy matters.

The message docs also mention inbound dedupe and debouncing. Those are separate again. Dedupe protects against channels redelivering the same inbound event after reconnects. Debouncing batches rapid text-only messages from the same sender before an agent turn starts. Retry policy is not trying to solve either of those. It is specifically about outbound request failure.

How I debug channel send failures

The channel troubleshooting docs give a simple command ladder. Start there before inventing a complicated model problem:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

A healthy baseline includes Runtime: running, Connectivity probe: ok, an expected channel capability such as read-only, write-capable, or admin-capable, and a channel probe where the transport is connected and, where supported, reports works or audit ok. If the channel is not healthy, retries may only make the failure slower and noisier.

Use openclaw logs when you need to see what the Gateway is actually doing. The logs command can follow the Gateway file log over RPC, return JSON lines, limit output, and render timestamps with --local-time. For channel retry debugging, I usually want the follow stream first and JSON only when another tool needs to parse it.

openclaw logs --follow --local-time
openclaw logs --json --limit 500

Then diagnose the channel signature. Telegram send failures with network errors point toward DNS, IPv6, or proxy routing to api.telegram.org. Discord guild silence may be a message-content intent or allowlist issue. Slack socket mode connected but not responding can be a token or scope problem. Those are not retry-tuning problems until the transport is otherwise healthy.

When to tune attempts and delay

I would consider tuning retries only after logs prove the failures are transient and the channel is otherwise correctly configured. A higher attempt count can help if short network blips are common. A larger minimum delay can help if you repeatedly hit provider pacing. More jitter can reduce synchronized retry bursts when many sends fail at once.

But keep the original goals in view. Retries are there to preserve ordering and avoid duplicated non-idempotent operations. If increasing attempts makes users wait too long, or if the channel keeps rejecting the same request, you are no longer improving reliability. You are hiding a real issue behind longer backoff.

The operator takeaway

OpenClaw's retry policy is intentionally narrow. It retries the failed outbound request, uses provider delay signals when available, applies conservative defaults, and avoids replaying completed composite steps. That is exactly the right bias for real agents. It favors consistency over dramatic recovery tricks.

If your agent lives in Telegram, Discord, or any serious team channel where outbound delivery can fail, treat retry behavior as part of production ops. Queueing keeps inbound runs sane. Dedupe protects against repeated inbound events. Debouncing reduces fragmented prompts. Retry policy protects the final delivery step without turning one failure into duplicate work.

Want the complete guide? Get ClawKit — $9.99