diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index a17496e0d..82d3af2ba 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "c71f07ba43baf813c8c3a3d22b44a5c2f6980fe2",
-  "syncedAt": "2026-04-23T02:28:40.863Z"
+  "sha": "b09aed827147508f1b3befcc9c71a59d9d19ad6b",
+  "syncedAt": "2026-04-23T02:33:25.151Z"
 }
diff --git a/docs/concepts/model-failover.md b/docs/concepts/model-failover.md
index 0219b9322..cbe454135 100644
--- a/docs/concepts/model-failover.md
+++ b/docs/concepts/model-failover.md
@@ -141,6 +141,13 @@ timeout only when the provider context is actually OpenRouter. Generic internal
 fallback text such as `LLM request failed with an unknown error.` stays
 conservative and does not trigger failover by itself.
 
+Some provider SDKs may otherwise sleep for a long `Retry-After` window before
+returning control to OpenClaw. For Stainless-based SDKs such as Anthropic and
+OpenAI, OpenClaw caps SDK-internal `retry-after-ms` / `retry-after` waits at 60
+seconds by default and surfaces longer retryable responses immediately so this
+failover path can run. Tune or disable the cap with
+`OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; see [/concepts/retry](/concepts/retry).
+
 Rate-limit cooldowns can also be model-scoped:
 
 - OpenClaw records `cooldownModel` for rate-limit failures when the failing
diff --git a/docs/concepts/retry.md b/docs/concepts/retry.md
index ad2660672..dd03e9800 100644
--- a/docs/concepts/retry.md
+++ b/docs/concepts/retry.md
@@ -25,6 +25,18 @@ title: "Retry Policy"
 
 ## Behavior
 
+### Model providers
+
+- OpenClaw lets provider SDKs handle normal short retries.
+- For Stainless-based SDKs such as Anthropic and OpenAI, retryable responses
+  (`408`, `409`, `429`, and `5xx`) can include `retry-after-ms` or
+  `retry-after`. When that wait is longer than 60 seconds, OpenClaw injects
+  `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 `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS=<seconds>`.
+  Set it to `0`, `false`, `off`, `none`, or `disabled` to let SDKs honor long
+  `Retry-After` sleeps internally.
+
 ### Discord
 
 - Retries only on rate-limit errors (HTTP 429).