diff --git a/docs/cli/models.md b/docs/cli/models.md
index 5c4f59a87..ab36c91ed 100644
--- a/docs/cli/models.md
+++ b/docs/cli/models.md
@@ -43,3 +43,7 @@ clawdbot models auth paste-token
 ```
 `models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
 `clawdbot plugins list` to see which providers are installed.
+
+Notes:
+- `setup-token` runs `claude setup-token` on the current machine (requires the Claude Code CLI).
+- `paste-token` accepts a token string generated elsewhere.
diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md
index 0c77144f5..f90104434 100644
--- a/docs/providers/anthropic.md
+++ b/docs/providers/anthropic.md
@@ -40,13 +40,13 @@ clawdbot onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
 
 ### Where to get a setup-token
 
-Setup-tokens are created by the **Claude Code CLI**, not the Anthropic Console. Run this on the **gateway host**:
+Setup-tokens are created by the **Claude Code CLI**, not the Anthropic Console. You can run this on **any machine**:
 
 ```bash
 claude setup-token
 ```
 
-Paste the token into Clawdbot (wizard: **Anthropic token (paste setup-token)**), or let Clawdbot run the command for you:
+Paste the token into Clawdbot (wizard: **Anthropic token (paste setup-token)**), or let Clawdbot run the command locally:
 
 ```bash
 clawdbot onboard --auth-choice setup-token
@@ -54,6 +54,12 @@ clawdbot onboard --auth-choice setup-token
 clawdbot models auth setup-token --provider anthropic
 ```
 
+If you generated the token on a different machine, paste it:
+
+```bash
+clawdbot models auth paste-token --provider anthropic
+```
+
 ### CLI setup
 
 ```bash
diff --git a/docs/start/faq.md b/docs/start/faq.md
index 02b56061f..b11ede191 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -240,7 +240,7 @@ It also warns if your configured model is unknown or missing auth.
 
 ### How does Anthropic "setup-token" auth work?
 
-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).
+`claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. If you run it on the gateway host, the wizard can auto-detect the CLI credentials. If you run it elsewhere, choose **Anthropic token (paste setup-token)** and paste the string. The token is stored as an auth profile for the **anthropic** provider and used like an API key or OAuth profile. 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
@@ -1123,6 +1123,10 @@ can’t find that profile in its auth store.
 - **Sync the Claude Code CLI token on the gateway host**
   - Run `clawdbot models status` (it loads + syncs Claude Code CLI credentials).
   - If it still says missing: run `claude setup-token` (or `clawdbot models auth setup-token --provider anthropic`) and retry.
+- **If the token was created on another machine**
+  - Paste it into the gateway host with `clawdbot models auth paste-token --provider anthropic`.
+- **Check the profile mode**
+  - `auth.profiles["anthropic:claude-cli"].mode` must be `"oauth"` (token mode rejects OAuth credentials).
 - **If you want to use an API key instead**
   - Put `ANTHROPIC_API_KEY` in `~/.clawdbot/.env` on the **gateway host**.
   - Clear any pinned order that forces `anthropic:claude-cli`: