docs: align auth storage and token auth guidance

docs/cli/index.md

@@ -1095,12 +1095,17 @@ Options:
 
 Options:
 
-- `add`: interactive auth helper
+- `add`: interactive token-auth helper
 - `login`: `--provider <name>`, `--method <method>`, `--set-default`
 - `login-github-copilot`: GitHub Copilot OAuth login flow
 - `setup-token`: `--provider <name>`, `--yes`
 - `paste-token`: `--provider <name>`, `--profile-id <id>`, `--expires-in <duration>`
 
+Notes:
+
+- `setup-token` and `paste-token` are generic token commands for providers that expose token auth methods.
+- Anthropic legacy token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.
+
 ### `models auth order get|set|clear`
 
 Options:

docs/cli/models.md

@@ -85,6 +85,8 @@ Notes:
 
 - `login --provider anthropic --method cli --set-default` reuses a local Claude
   CLI login and rewrites the main Anthropic default-model path to `claude-cli/...`.
+- `setup-token` and `paste-token` remain generic token commands for providers
+  that expose token auth methods.
 - `paste-token` accepts a token string generated elsewhere or from automation.
 - Anthropic billing note: Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover OpenClaw, and Claude CLI traffic in OpenClaw now requires **Extra Usage** billed separately from the subscription.
-- Existing legacy Anthropic token profiles still run if already configured, but OpenClaw no longer offers Anthropic setup-token as a new auth path.
+- Existing legacy Anthropic token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.

docs/gateway/authentication.md

@@ -185,6 +185,8 @@ Run `openclaw models status` to confirm which profile is expiring. If a legacy
 Anthropic token profile is missing or expired, migrate that setup to Claude CLI
 or an API key.
 
-## Requirements
+## Claude CLI requirements
+
+Only needed for the Anthropic Claude CLI reuse path:
 
 - Claude Code CLI installed (`claude` command available)

docs/gateway/configuration-examples.md

@@ -67,19 +67,15 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
   // Auth profile metadata (secrets live in auth-profiles.json)
   auth: {
     profiles: {
-      "anthropic:me@example.com": {
-        provider: "anthropic",
-        mode: "oauth",
-        email: "me@example.com",
-      },
+      "anthropic:default": { provider: "anthropic", mode: "api_key" },
       "anthropic:work": { provider: "anthropic", mode: "api_key" },
       "openai:default": { provider: "openai", mode: "api_key" },
-      "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
+      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
     },
     order: {
-      anthropic: ["anthropic:me@example.com", "anthropic:work"],
+      anthropic: ["anthropic:default", "anthropic:work"],
       openai: ["openai:default"],
-      "openai-codex": ["openai-codex:default"],
+      "openai-codex": ["openai-codex:personal"],
     },
   },
 

docs/reference/wizard.md

@@ -61,12 +61,14 @@ For a high-level overview, see [Onboarding (CLI)](/start/wizard).
     - Pick a default model from detected options (or enter provider/model manually). For best quality and lower prompt-injection risk, choose the strongest latest-generation model available in your provider stack.
     - Onboarding runs a model check and warns if the configured model is unknown or missing auth.
     - API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
-    - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
+    - Auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth). `~/.openclaw/credentials/oauth.json` is legacy import-only.
     - More detail: [/concepts/oauth](/concepts/oauth)
     <Note>
     Headless/server tip: complete OAuth on a machine with a browser, then copy
-    `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) to the
-    gateway host.
+    that agent's `auth-profiles.json` (for example
+    `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`, or the matching
+    `$OPENCLAW_STATE_DIR/...` path) to the gateway host. `credentials/oauth.json`
+    is only a legacy import source.
     </Note>
   </Step>
   <Step title="Workspace">

docs/start/wizard-cli-reference.md

@@ -224,8 +224,8 @@ Model behavior:
 
 Credential and profile paths:
 
-- OAuth credentials: `~/.openclaw/credentials/oauth.json`
 - Auth profiles (API keys + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- Legacy OAuth import: `~/.openclaw/credentials/oauth.json`
 
 Credential storage mode:
 
@@ -251,8 +251,10 @@ Credential storage mode:
 
 <Note>
 Headless and server tip: complete OAuth on a machine with a browser, then copy
-`~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`)
-to the gateway host.
+that agent's `auth-profiles.json` (for example
+`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`, or the matching
+`$OPENCLAW_STATE_DIR/...` path) to the gateway host. `credentials/oauth.json`
+is only a legacy import source.
 </Note>
 
 ## Outputs and internals