diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md
index 775d97acf..ff24cb1ed 100644
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@@ -67,6 +67,10 @@ clawdbot doctor
 This should create (or refresh) an auth profile like `anthropic:claude-cli` in
 the agent auth store.
 
+Clawdbot config sets `auth.profiles["anthropic:claude-cli"].mode` to `"oauth"` so
+the profile accepts both OAuth and setup-token credentials. Older configs that
+used `"token"` are auto-migrated on load.
+
 If you see an Anthropic error like:
 
 ```
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 2ad3a09cf..012bec824 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -306,6 +306,10 @@ rotation order used for failover.
 }
 ```
 
+Note: `anthropic:claude-cli` should use `mode: "oauth"` even when the stored
+credential is a setup-token. Clawdbot auto-migrates older configs that used
+`mode: "token"`.
+
 ### `agents.list[].identity`
 
 Optional per-agent identity used for defaults and UX. This is written by the macOS onboarding assistant.
diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md
index f51df04cd..3d957f9a2 100644
--- a/docs/providers/anthropic.md
+++ b/docs/providers/anthropic.md
@@ -59,4 +59,7 @@ clawdbot onboard --auth-choice claude-cli
 ## Notes
 
 - The wizard can run `claude setup-token` on the gateway host and store the token.
+- 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.
 - Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
diff --git a/docs/start/faq.md b/docs/start/faq.md
index 0e9729194..13b0b0ff6 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -239,6 +239,10 @@ It also warns if your configured model is unknown or missing auth.
 
 The wizard can run `claude setup-token` on the gateway host (or you run it yourself), then stores the token as an auth profile for the **anthropic** provider. That profile is used for model calls the same way an API key or OAuth profile would be. If you already ran `claude setup-token`, pick **Anthropic token (paste setup-token)** and paste it. More detail: [OAuth](/concepts/oauth).
 
+Clawdbot keeps `auth.profiles["anthropic:claude-cli"].mode` set to `"oauth"` so
+the profile accepts both OAuth and setup-token credentials; older `"token"` mode
+entries auto-migrate.
+
 ### Do you support Claude subscription auth (Claude Code OAuth)?
 
 Yes. Clawdbot can **reuse Claude Code CLI credentials** (OAuth) and also supports **setup-token**. If you have a Claude subscription, we recommend **setup-token** on the gateway host for the most reliable long‑running setup (requires Claude Pro/Max + the `claude` CLI). OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).