From ce89bc2b40bbf4b174485fc9d5ace96d81152c42 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 25 Jan 2026 00:07:13 +0000
Subject: [PATCH] docs: add anthropic auth error troubleshooting

---
 docs/gateway/troubleshooting.md | 18 ++++++++++++++++++
 docs/providers/anthropic.md     |  5 +++++
 2 files changed, 23 insertions(+)

diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
index c3e245cb2..24815e258 100644
--- a/docs/gateway/troubleshooting.md
+++ b/docs/gateway/troubleshooting.md
@@ -31,6 +31,24 @@ See also: [Health checks](/gateway/health) and [Logging](/logging).
 
 ## Common Issues
 
+### No API key found for provider "anthropic"
+
+This means the **agent’s auth store is empty** or missing Anthropic credentials.
+Auth is **per agent**, so a new agent won’t inherit the main agent’s keys.
+
+Fix options:
+- Re-run onboarding and choose **Anthropic** for that agent.
+- Or paste a setup-token on the **gateway host**:
+  ```bash
+  clawdbot models auth setup-token --provider anthropic
+  ```
+- Or copy `auth-profiles.json` from the main agent dir to the new agent dir.
+
+Verify:
+```bash
+clawdbot models status
+```
+
 ### OAuth token refresh failed (Anthropic Claude subscription)
 
 This means the stored Anthropic OAuth token expired and the refresh failed.
diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md
index b5f723d92..7876c4ae9 100644
--- a/docs/providers/anthropic.md
+++ b/docs/providers/anthropic.md
@@ -114,6 +114,11 @@ clawdbot onboard --auth-choice claude-cli
 - If the Claude CLI login lives on a different machine, use
   `clawdbot models auth paste-token --provider anthropic` on the gateway host.
 
+**No API key found for provider "anthropic"**
+- Auth is **per agent**. New agents don’t inherit the main agent’s keys.
+- Re-run onboarding for that agent, or paste a setup-token / API key on the
+  gateway host, then verify with `clawdbot models status`.
+
 **No credentials found for profile `anthropic:default` or `anthropic:claude-cli`**
 - Run `clawdbot models status` to see which auth profile is active.
 - Re-run onboarding, or paste a setup-token / API key for that profile.