diff --git a/docs/cli/index.md b/docs/cli/index.md index 78d7c8b5ac0..7c5b6201b15 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -872,6 +872,13 @@ Policy note: this is technical compatibility. Anthropic has blocked some subscription usage outside Claude Code in the past; verify current Anthropic terms before relying on setup-token in production. +Anthropic Claude CLI migration: + +```bash +openclaw models auth login --provider anthropic --method cli --set-default +openclaw onboard --auth-choice anthropic-cli +``` + ### `models` (root) `openclaw models` is an alias for `models status`. diff --git a/docs/cli/models.md b/docs/cli/models.md index ceba129099b..446843e8753 100644 --- a/docs/cli/models.md +++ b/docs/cli/models.md @@ -74,8 +74,17 @@ openclaw models auth paste-token `models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use `openclaw plugins list` to see which providers are installed. +Examples: + +```bash +openclaw models auth login --provider anthropic --method cli --set-default +openclaw models auth login --provider openai-codex --set-default +``` + 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` prompts for a setup-token value (generate it with `claude setup-token` on any machine). - `paste-token` accepts a token string generated elsewhere or from automation. - Anthropic policy note: setup-token support is technical compatibility. Anthropic has blocked some subscription usage outside Claude Code in the past, so verify current terms before using it broadly. diff --git a/docs/concepts/oauth.md b/docs/concepts/oauth.md index 2589dcaa8f9..d505c7a77ce 100644 --- a/docs/concepts/oauth.md +++ b/docs/concepts/oauth.md @@ -10,7 +10,7 @@ title: "OAuth" # OAuth -OpenClaw supports “subscription auth” via OAuth for providers that offer it (notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, use the **setup-token** flow. Anthropic subscription use outside Claude Code has been restricted for some users in the past, so treat it as a user-choice risk and verify current Anthropic policy yourself. OpenAI Codex OAuth is explicitly supported for use in external tools like OpenClaw. This page explains: +OpenClaw supports “subscription auth” via OAuth for providers that offer it (notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, you can either use the **setup-token** flow or reuse a local **Claude CLI** login on the gateway host. Anthropic subscription use outside Claude Code has been restricted for some users in the past, so treat it as a user-choice risk and verify current Anthropic policy yourself. OpenAI Codex OAuth is explicitly supported for use in external tools like OpenClaw. This page explains: For Anthropic in production, API key auth is the safer recommended path over subscription setup-token auth. @@ -80,19 +80,48 @@ Verify: 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: + +```bash +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Onboarding shortcut: + +```bash +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/...`. + ## OAuth exchange (how login works) OpenClaw’s interactive login flows are implemented in `@mariozechner/pi-ai` and wired into the wizards/commands. -### Anthropic setup-token +### Anthropic setup-token / Claude CLI Flow shape: +Setup-token path: + 1. run `claude setup-token` 2. paste the token into OpenClaw 3. store as a token auth profile (no refresh) -The wizard path is `openclaw onboard` → auth choice `setup-token` (Anthropic). +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/...` + +Wizard paths: + +- `openclaw onboard` → auth choice `anthropic-cli` +- `openclaw onboard` → auth choice `setup-token` (Anthropic) ### OpenAI Codex (ChatGPT OAuth) diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md index 895124bd8c3..e3a462fe0fe 100644 --- a/docs/gateway/authentication.md +++ b/docs/gateway/authentication.md @@ -113,6 +113,26 @@ Optional ops scripts (systemd/Termux) are documented here: > `claude setup-token` requires an interactive TTY. +## Anthropic: Claude CLI migration + +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: + +```bash +openclaw models auth login --provider anthropic --method cli --set-default +``` + +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`. + +Onboarding shortcut: + +```bash +openclaw onboard --auth-choice anthropic-cli +``` + ## Checking model auth status ```bash diff --git a/docs/help/faq.md b/docs/help/faq.md index 85ed47b6409..7ca459db968 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -546,8 +546,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - Yes. You can authenticate with a **setup-token** - instead of an API key. This is the subscription path. + Yes. You can either use a **setup-token** or reuse a local **Claude CLI** + login on the gateway host. Claude Pro/Max subscriptions **do not include an API key**, so this is the technical path for subscription accounts. But this is your decision: Anthropic @@ -572,7 +572,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). + Yes. You can either: + + - use a **setup-token** + - reuse a local **Claude CLI** login on the gateway host with `openclaw models auth login --provider anthropic --method cli --set-default` + + Setup-token is still supported. Claude CLI migration is simpler when the gateway host already runs Claude Code. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). Important: this is technical compatibility, not a policy guarantee. Anthropic has blocked some subscription usage outside Claude Code in the past. diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index e6a5b8decd3..04473b9eebc 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -261,6 +261,38 @@ If the `claude` binary is not on the gateway host PATH: - Normal OpenClaw message/session routing - Claude CLI session continuity across turns +### 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: + +```bash +openclaw models auth login --provider anthropic --method cli --set-default +``` + +Or in onboarding: + +```bash +openclaw onboard --auth-choice anthropic-cli +``` + +What this does: + +- verifies Claude CLI is already signed in on the gateway host +- switches the default model to `claude-cli/...` +- rewrites Anthropic default-model fallbacks like `anthropic/claude-opus-4-6` + to `claude-cli/claude-opus-4-6` +- adds matching `claude-cli/...` entries to `agents.defaults.models` + +What it does **not** do: + +- delete your existing Anthropic auth profiles +- remove every old `anthropic/...` config reference outside the main default + model/allowlist path + +That makes rollback simple: change the default model back to `anthropic/...` if +you need to. + ### Important limits - This is **not** the Anthropic API provider. It is the local CLI runtime. diff --git a/docs/reference/wizard.md b/docs/reference/wizard.md index 6268649d443..039d3df811e 100644 --- a/docs/reference/wizard.md +++ b/docs/reference/wizard.md @@ -31,7 +31,7 @@ For a high-level overview, see [Onboarding (CLI)](/start/wizard). - **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. - - **Anthropic OAuth (Claude Code CLI)**: on macOS onboarding checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present. + - **Anthropic Claude CLI**: on macOS onboarding checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present and switches model selection to `claude-cli/...`. - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default). - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it. - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index 1ec9f15ea2f..73418425c71 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -126,7 +126,10 @@ What you set: Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. - + + Reuses a local Claude CLI login on the gateway host and switches model + selection to `claude-cli/...`. + - macOS: checks Keychain item "Claude Code-credentials" - Linux and Windows: reuses `~/.claude/.credentials.json` if present