chore(sync): mirror docs from openclaw/openclaw@b09aed8271

.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"
 }

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

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).