diff --git a/docs/cli/index.md b/docs/cli/index.md
index c54d398f263..45866530b80 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -945,7 +945,10 @@ Anthropic Claude CLI migration:
 openclaw models auth login --provider anthropic --method cli --set-default
 ```
 
-Note: `--auth-choice anthropic-cli` is a deprecated legacy alias. Use `models auth login` instead.
+Onboarding shortcut: `openclaw onboard --auth-choice anthropic-cli`
+
+Legacy alias note: `claude-cli` is the deprecated onboarding auth-choice alias.
+Use `anthropic-cli` for onboarding, or use `models auth login` directly.
 
 ### `models` (root)
 
diff --git a/docs/concepts/oauth.md b/docs/concepts/oauth.md
index ff96f8f6a0c..784e5427169 100644
--- a/docs/concepts/oauth.md
+++ b/docs/concepts/oauth.md
@@ -100,7 +100,16 @@ openclaw models status
 ## Anthropic Claude CLI migration
 
 If Claude CLI is already installed and signed in on the gateway host, you can
-switch Anthropic model selection over to the local CLI backend:
+switch Anthropic model selection over to the local CLI backend. This is a
+supported OpenClaw path when you want to reuse a local Claude CLI login on the
+same host.
+
+Prerequisites:
+
+- the `claude` binary is installed on the gateway host
+- Claude CLI is already authenticated there via `claude auth login`
+
+Migration command:
 
 ```bash
 openclaw models auth login --provider anthropic --method cli --set-default
@@ -113,7 +122,15 @@ openclaw onboard --auth-choice anthropic-cli
 ```
 
 This keeps existing Anthropic auth profiles for rollback, but rewrites the main
-default-model path from `anthropic/...` to `claude-cli/...`.
+default-model path from `anthropic/...` to `claude-cli/...`, rewrites matching
+Anthropic Claude fallbacks, and adds matching `claude-cli/...` allowlist
+entries under `agents.defaults.models`.
+
+Verify:
+
+```bash
+openclaw models status
+```
 
 ## OAuth exchange (how login works)
 
@@ -134,6 +151,7 @@ Claude CLI path:
 1. sign in with `claude auth login` on the gateway host
 2. run `openclaw models auth login --provider anthropic --method cli --set-default`
 3. store no new auth profile; switch model selection to `claude-cli/...`
+4. keep existing Anthropic auth profiles for rollback
 
 Wizard paths:
 
diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md
index 273e9fbc5fc..ad055ee4b9b 100644
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@@ -130,7 +130,13 @@ Optional ops scripts (systemd/Termux) are documented here:
 
 If Claude CLI is already installed and signed in on the gateway host, you can
 switch an existing Anthropic setup over to the CLI backend instead of pasting a
-setup-token:
+setup-token. This is a supported OpenClaw migration path for reusing a local
+Claude CLI login on that host.
+
+Prerequisites:
+
+- `claude` installed on the gateway host
+- Claude CLI already signed in there with `claude auth login`
 
 ```bash
 openclaw models auth login --provider anthropic --method cli --set-default
@@ -140,6 +146,12 @@ This keeps your existing Anthropic auth profiles for rollback, but changes the
 default model selection to `claude-cli/...` and adds matching Claude CLI
 allowlist entries under `agents.defaults.models`.
 
+Verify:
+
+```bash
+openclaw models status
+```
+
 Onboarding shortcut:
 
 ```bash
diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md
index 797f4833a95..fdf8ae1730c 100644
--- a/docs/providers/anthropic.md
+++ b/docs/providers/anthropic.md
@@ -285,7 +285,15 @@ If the `claude` binary is not on the gateway host PATH:
 ### Migrate from Anthropic auth to Claude CLI
 
 If you currently use `anthropic/...` with a setup-token or API key and want to
-switch the same gateway host to Claude CLI:
+switch the same gateway host to Claude CLI, OpenClaw supports that as a normal
+provider-auth migration path.
+
+Prerequisites:
+
+- Claude CLI installed on the **same gateway host** that runs OpenClaw
+- Claude CLI already signed in there: `claude auth login`
+
+Then run:
 
 ```bash
 openclaw models auth login --provider anthropic --method cli --set-default
@@ -305,6 +313,14 @@ What this does:
   to `claude-cli/claude-opus-4-6`
 - adds matching `claude-cli/...` entries to `agents.defaults.models`
 
+Quick verification:
+
+```bash
+openclaw models status
+```
+
+You should see the resolved primary model under `claude-cli/...`.
+
 What it does **not** do:
 
 - delete your existing Anthropic auth profiles