diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index 1e9f595a7..1882dc403 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -31,6 +31,34 @@ See also: [Health checks](/gateway/health) and [Logging](/logging).
 
 ## Common Issues
 
+### OAuth token refresh failed (Anthropic Claude subscription)
+
+This means the stored Anthropic OAuth token expired and the refresh failed.
+If you’re on a Claude subscription (no API key), the most reliable fix is to
+switch to a **Claude Code setup-token** or re-sync Claude Code CLI OAuth on the
+**gateway host**.
+
+**Recommended (setup-token):**
+
+```bash
+# Run on the gateway host (runs Claude Code CLI)
+clawdbot models auth setup-token --provider anthropic
+clawdbot models status
+```
+
+If you generated the token elsewhere:
+
+```bash
+clawdbot models auth paste-token --provider anthropic
+clawdbot models status
+```
+
+**If you want to keep OAuth reuse:**
+log in with Claude Code CLI on the gateway host, then run `clawdbot models status`
+to sync the refreshed token into Clawdbot’s auth store.
+
+More detail: [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
+
 ### Control UI fails on HTTP ("device identity required" / "connect failed")
 
 If you open the dashboard over plain HTTP (e.g. `http://<lan-ip>:18789/` or
diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md
index b49550220..a244afff5 100644
--- a/docs/providers/anthropic.md
+++ b/docs/providers/anthropic.md
@@ -100,6 +100,7 @@ clawdbot onboard --auth-choice claude-cli
 ## Notes
 
 - Generate the setup-token with `claude setup-token` and paste it, or run `clawdbot models auth setup-token` on the gateway host.
+- If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token or resync Claude Code CLI OAuth on the gateway host. See [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription).
 - Clawdbot writes `auth.profiles["anthropic:claude-cli"].mode` as `"oauth"` so the profile
   accepts both OAuth and setup-token credentials. Older configs using `"token"` are
   auto-migrated on load.