diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a20479c2f7..58d0fb97e4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ Docs: https://docs.openclaw.ai - Providers/Amazon Bedrock Mantle: add a bundled OpenAI-compatible Mantle provider with bearer-token discovery, automatic OSS model catalog loading, and Bedrock Mantle region detection for hosted GPT-OSS, Qwen, Kimi, GLM, and similar routes. (#61296) Thanks @wirjo. - Providers/Amazon Bedrock: discover regional and global inference profiles, inherit their backing model capabilities, and inject the Bedrock request region automatically so cross-region Claude profiles work without manual provider overrides. (#61299) Thanks @wirjo. +- Providers/Anthropic: remove the Claude CLI backend, have `openclaw doctor` convert stale `anthropic:claude-cli` state back to Anthropic token/OAuth when stored credential bytes still exist (or delete the stale Claude CLI config when they do not), and steer Anthropic setup to API keys or legacy setup-token with the correct Extra Usage billing guidance. +- Providers/Anthropic: remove setup-token from new onboarding and auth-command setup paths, keep existing configured legacy token profiles runnable, and steer new Anthropic setup to API keys. - Providers/Fireworks: add a bundled Fireworks AI provider plugin with `FIREWORKS_API_KEY` onboarding, Fire Pass Kimi defaults, and dynamic Fireworks model-id support. - Providers/Qwen: add a bundled Qwen provider plugin with dedicated onboarding, media understanding, and video generation support. - Providers/StepFun: add the bundled StepFun provider plugin with standard and Step Plan endpoints, China/global onboarding choices, `step-3.5-flash` on both catalogs, and `step-3.5-flash-2603` currently exposed on Step Plan. (#60032) Thanks @hengm3467. @@ -38,7 +40,6 @@ Docs: https://docs.openclaw.ai - Agents/cache: stabilize cache-relevant system prompt fingerprints by normalizing equivalent structured prompt whitespace, line endings, hook-added system context, and runtime capability ordering so semantically unchanged prompts reuse KV/cache more reliably. Thanks @vincentkoc. - Providers/OpenAI Codex: add forward-compat `openai-codex/gpt-5.4-mini` synthesis across provider runtime, model catalog, and model listing so Codex mini works before bundled Pi catalog updates land. - Providers/OpenAI: add an opt-in GPT personality and move GPT-5 prompt tuning onto provider-owned system-prompt contributions so cache-stable guidance stays above the prompt cache boundary and embedded runner paths reuse the same provider-specific prompt behavior. -- Providers/Anthropic: remove setup-token from new onboarding and auth-command setup paths, keep existing configured legacy token profiles runnable, and steer new Anthropic setup to Claude CLI or API keys. - Docs/IRC: replace public IRC hostname examples with `irc.example.com` and recommend private servers for bot coordination while listing common public networks for intentional use. - Memory/dreaming: add configurable aging controls (`recencyHalfLifeDays`, `maxAgeDays`) plus optional verbose logging so operators can tune recall decay and inspect promotion decisions more easily. - Plugins/reply dispatch: add a generic `reply_dispatch` hook so bundled plugins like ACPX can own reply interception without hardcoded ACP paths in core auto-reply routing. diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index aa3ebc74189..d0566ce674a 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -58,7 +58,6 @@ Notes: - `--force`: kill any existing listener on the selected port before starting. - `--verbose`: verbose logs. - `--cli-backend-logs`: only show CLI backend logs in the console (and enable stdout/stderr). -- `--claude-cli-logs`: deprecated alias for `--cli-backend-logs`. - `--ws-log `: websocket log style (default `auto`). - `--compact`: alias for `--ws-log compact`. - `--raw-stream`: log raw model stream events to jsonl. diff --git a/docs/cli/index.md b/docs/cli/index.md index 87aee3f46ca..3b8c0fedaa6 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1354,7 +1354,6 @@ Options: - `--force` (kill existing listener on port) - `--verbose` - `--cli-backend-logs` -- `--claude-cli-logs` (deprecated alias) - `--ws-log ` - `--compact` (alias for `--ws-log compact`) - `--raw-stream` @@ -1479,31 +1478,20 @@ Tip: the owner-only `gateway` runtime tool still refuses to rewrite `tools.exec. See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy. -Billing note: We believe Claude Code CLI fallback is likely allowed for local, -user-managed automation based on Anthropic's public CLI docs. That said, -Anthropic's third-party harness policy creates enough ambiguity around -subscription-backed use in external products that we do not recommend it for -production. Anthropic also notified OpenClaw users on **April 4, 2026 at -12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as -third-party harness usage and requires **Extra Usage** billed separately from -the subscription. For production, prefer an Anthropic API key or another supported -subscription-style provider such as OpenAI Codex, Alibaba Cloud Model Studio -Coding Plan, MiniMax Coding Plan, or Z.AI / GLM Coding Plan. +Billing note: for Anthropic in OpenClaw, the practical split is **API key** or +**Claude subscription with Extra Usage**. Anthropic notified OpenClaw users on +**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** +Claude-login path counts as third-party harness usage and requires +**Extra Usage** billed separately from the subscription. Our local repros also +show the OpenClaw-identifying prompt string does not reproduce on the +Anthropic SDK + API-key path. For production, prefer an Anthropic API key or +another supported subscription-style provider such as OpenAI Codex, Alibaba +Cloud Model Studio Coding Plan, MiniMax Coding Plan, or Z.AI / GLM Coding +Plan. -Anthropic Claude CLI migration: - -```bash -openclaw models auth login --provider anthropic --method cli --set-default -``` - -Onboarding shortcut: `openclaw onboard --auth-choice anthropic-cli` - -Anthropic setup-token is also available again as a legacy/manual auth path. +Anthropic setup-token is available again as a legacy/manual auth path. Use it only with the expectation that Anthropic told OpenClaw users the -OpenClaw Claude-login path requires **Extra Usage**. - -Legacy alias note: `claude-cli` is the deprecated onboarding auth-choice alias. -Use `anthropic-cli` for onboarding, or use `models auth login` directly. +OpenClaw-managed Anthropic subscription path requires **Extra Usage**. ### `models` (root) diff --git a/docs/cli/models.md b/docs/cli/models.md index 9028f88bc38..974a4fc210b 100644 --- a/docs/cli/models.md +++ b/docs/cli/models.md @@ -112,15 +112,11 @@ provider you choose. 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 a canonical - `claude-cli/claude-*` ref. - `setup-token` and `paste-token` remain generic token commands for providers that expose token auth methods. - `setup-token` requires an interactive TTY and runs the provider's token-auth @@ -132,5 +128,5 @@ Notes: `--profile-id`. - `paste-token --expires-in ` stores an absolute token expiry from a relative duration such as `365d` or `12h`. -- Anthropic billing note: We believe Claude Code CLI fallback is likely allowed for local, user-managed automation based on Anthropic's public CLI docs. That said, Anthropic's third-party harness policy creates enough ambiguity around subscription-backed use in external products that we do not recommend it for production. Anthropic also notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. +- Anthropic billing note: for Anthropic in OpenClaw, the practical split is **API key** or **Claude subscription with Extra Usage**. Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. Our local repros also show the OpenClaw-identifying prompt string does not reproduce on the Anthropic SDK + API-key path. - Anthropic `setup-token` / `paste-token` are available again as a legacy/manual OpenClaw path. Use them with the expectation that Anthropic told OpenClaw users this path requires **Extra Usage**. diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 1d5a28b4204..d03abe87caf 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -253,9 +253,9 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no** - Auth: `ANTHROPIC_API_KEY` - Optional rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (single override) - Example model: `anthropic/claude-opus-4-6` -- CLI: `openclaw onboard --auth-choice apiKey` or `openclaw onboard --auth-choice anthropic-cli` +- CLI: `openclaw onboard --auth-choice apiKey` - Direct public Anthropic requests support the shared `/fast` toggle and `params.fastMode`, including API-key and OAuth-authenticated traffic sent to `api.anthropic.com`; OpenClaw maps that to Anthropic `service_tier` (`auto` vs `standard_only`) -- Billing note: Anthropic's public Claude Code docs still include direct Claude Code terminal usage in Claude plan limits. Separately, Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. +- Billing note: for Anthropic in OpenClaw, the practical split is **API key** or **Claude subscription with Extra Usage**. Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. Our local repros also show the OpenClaw-identifying prompt string does not reproduce on the Anthropic SDK + API-key path. - Anthropic setup-token is available again as a legacy/manual OpenClaw path. Use it with the expectation that Anthropic told OpenClaw users this path requires **Extra Usage**. ```json5 diff --git a/docs/concepts/oauth.md b/docs/concepts/oauth.md index fbc95b0bb64..77ee4a50cb7 100644 --- a/docs/concepts/oauth.md +++ b/docs/concepts/oauth.md @@ -11,13 +11,14 @@ title: "OAuth" # OAuth OpenClaw supports “subscription auth” via OAuth for providers that offer it -(notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, new -setup should use the local **Claude CLI** login path on the gateway host, but -Anthropic distinguishes between direct Claude Code usage and OpenClaw's reuse -path. Anthropic's public Claude Code docs say direct Claude Code use stays -inside Claude subscription limits. Separately, Anthropic notified OpenClaw -users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that OpenClaw counts as -a third-party harness and now requires **Extra Usage** for that traffic. +(notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic, the practical split +is now: + +- **Anthropic API key**: normal Anthropic API billing +- **Anthropic subscription auth inside OpenClaw**: Anthropic notified OpenClaw + users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this now + requires **Extra Usage** + OpenAI Codex OAuth is explicitly supported for use in external tools like OpenClaw. This page explains: @@ -96,62 +97,23 @@ OpenClaw-driven Claude-login traffic. ## 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. 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 -``` - -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/...`, rewrites matching -Anthropic Claude fallbacks, and adds matching `claude-cli/...` allowlist -entries under `agents.defaults.models`. - -Verify: - -```bash -openclaw models status -``` +Anthropic no longer has a supported local Claude CLI migration path in +OpenClaw. Use Anthropic API keys for Anthropic traffic, or keep legacy +token-based auth only where it is already configured and with the expectation +that Anthropic treats that OpenClaw path as **Extra Usage**. ## OAuth exchange (how login works) OpenClaw’s interactive login flows are implemented in `@mariozechner/pi-ai` and wired into the wizards/commands. -### Anthropic Claude CLI +### Anthropic setup-token Flow shape: -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 - -Anthropic's public Claude Code docs describe this direct Claude subscription -login flow for `claude` itself. OpenClaw can reuse that local login, but -Anthropic separately classifies the OpenClaw-controlled path as third-party -harness usage for billing purposes. - -Interactive assistant path: - -- `openclaw onboard` / `openclaw configure` → auth choice `anthropic-cli` +1. start Anthropic setup-token or paste-token from OpenClaw +2. OpenClaw stores the resulting Anthropic credential in an auth profile +3. model selection stays on `anthropic/...` +4. existing Anthropic auth profiles remain available for rollback/order control ### OpenAI Codex (ChatGPT OAuth) diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md index 1c5dae6b23e..b71cd67bf3c 100644 --- a/docs/gateway/authentication.md +++ b/docs/gateway/authentication.md @@ -1,5 +1,5 @@ --- -summary: "Model authentication: OAuth, API keys, and Claude CLI reuse" +summary: "Model authentication: OAuth, API keys, and legacy Anthropic setup-token" read_when: - Debugging model auth or OAuth expiry - Documenting authentication or credential storage @@ -9,7 +9,7 @@ title: "Authentication" # Authentication (Model Providers) -This page covers **model provider** authentication (API keys, OAuth, Claude CLI reuse). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth). +This page covers **model provider** authentication (API keys, OAuth, and legacy Anthropic setup-token). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth). OpenClaw supports OAuth and API keys for model providers. For always-on gateway @@ -26,8 +26,9 @@ For credential eligibility/reason-code rules used by `models status --probe`, se If you’re running a long-lived gateway, start with an API key for your chosen provider. -For Anthropic specifically, API key auth is the safe path. Claude CLI reuse is -the other supported subscription-style setup path. +For Anthropic specifically, API key auth is the safe path. Anthropic +subscription-style auth inside OpenClaw is the legacy setup-token path and +should be treated as an **Extra Usage** path, not a plan-limits path. 1. Create an API key in your provider console. 2. Put it on the **gateway host** (the machine running `openclaw gateway`). @@ -68,8 +69,9 @@ OpenClaw users that the **OpenClaw** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription. -For the clearest setup path, use an Anthropic API key or migrate to Claude CLI -on the gateway host. +For the clearest setup path, use an Anthropic API key. If you must keep a +subscription-style Anthropic path in OpenClaw, use the legacy setup-token path +with the expectation that Anthropic treats it as **Extra Usage**. Manual token entry (any provider; writes `auth-profiles.json` + updates config): @@ -108,41 +110,17 @@ Notes: Optional ops scripts (systemd/Termux) are documented here: [Auth monitoring scripts](/help/scripts#auth-monitoring-scripts) -## Anthropic: Claude CLI migration +## Anthropic note -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. This is a -supported OpenClaw migration path for reusing a local Claude CLI login on that -host. +The Anthropic `claude-cli` backend was removed. -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 -``` - -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 -openclaw onboard --auth-choice anthropic-cli -``` - -Interactive `openclaw onboard` and `openclaw configure` still prefer Claude CLI -for Anthropic, but Anthropic setup-token is available again as a -legacy/manual path and should be used with the Extra Usage billing expectation. +- Use Anthropic API keys for Anthropic traffic in OpenClaw. +- Anthropic setup-token remains a legacy/manual path and should be used with + the Extra Usage billing expectation Anthropic communicated to OpenClaw users. +- `openclaw doctor` now detects stale removed Anthropic Claude CLI state. If + stored credential bytes still exist, doctor converts them back into + Anthropic token/OAuth profiles. If not, doctor removes the stale Claude CLI + config and points you to API key or setup-token recovery. ## Checking model auth status @@ -198,8 +176,8 @@ to one model id rather than the whole provider profile. ### "No credentials found" -If the Anthropic profile is missing, migrate that setup to Claude CLI or an API -key on the **gateway host**, then re-check: +If the Anthropic profile is missing, configure an Anthropic API key on the +**gateway host** or set up the legacy Anthropic setup-token path, then re-check: ```bash openclaw models status @@ -208,11 +186,16 @@ openclaw models status ### Token expiring/expired 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. +Anthropic token profile is missing or expired, refresh that setup via +setup-token or migrate to an Anthropic API key. -## Claude CLI requirements +If the machine still has stale removed Anthropic Claude CLI state from older +builds, run: -Only needed for the Anthropic Claude CLI reuse path: +```bash +openclaw doctor --yes +``` -- Claude Code CLI installed (`claude` command available) +Doctor converts `anthropic:claude-cli` back to Anthropic token/OAuth when the +stored credential bytes still exist. Otherwise it removes stale Claude CLI +profile/config/model refs and leaves the next-step guidance. diff --git a/docs/gateway/cli-backends.md b/docs/gateway/cli-backends.md index e350b39a97f..ecaa546879c 100644 --- a/docs/gateway/cli-backends.md +++ b/docs/gateway/cli-backends.md @@ -2,7 +2,7 @@ summary: "CLI backends: local AI CLI fallback with optional MCP tool bridge" read_when: - You want a reliable fallback when API providers fail - - You are running Claude CLI or other local AI CLIs and want to reuse them + - You are running Codex CLI or other local AI CLIs and want to reuse them - You want to understand the MCP loopback bridge for CLI backend tool access title: "CLI Backends" --- @@ -13,9 +13,8 @@ OpenClaw can run **local AI CLIs** as a **text-only fallback** when API provider rate-limited, or temporarily misbehaving. This is intentionally conservative: - **OpenClaw tools are not injected directly**, but backends with `bundleMcp: true` - (the Claude CLI default) can receive gateway tools via a loopback MCP bridge. -- **JSONL streaming** (Claude CLI uses `--output-format stream-json` with - `--include-partial-messages`; prompts are sent via stdin). + can receive gateway tools via a loopback MCP bridge. +- **JSONL streaming** for CLIs that support it. - **Sessions are supported** (so follow-up turns stay coherent). - **Images can be passed through** if the CLI accepts image paths. @@ -28,15 +27,9 @@ thread/conversation binding, and persistent external coding sessions, use ## Beginner-friendly quick start -You can use Claude CLI **without any config** (the bundled Anthropic plugin +You can use Codex CLI **without any config** (the bundled OpenAI plugin registers a default backend): -```bash -openclaw agent --message "hi" --model claude-cli/claude-sonnet-4-6 -``` - -Codex CLI also works out of the box (via the bundled OpenAI plugin): - ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` @@ -49,8 +42,8 @@ command path: agents: { defaults: { cliBackends: { - "claude-cli": { - command: "/opt/homebrew/bin/claude", + "codex-cli": { + command: "/opt/homebrew/bin/codex", }, }, }, @@ -75,12 +68,11 @@ Add a CLI backend to your fallback list so it only runs when primary models fail defaults: { model: { primary: "anthropic/claude-opus-4-6", - fallbacks: ["claude-cli/claude-sonnet-4-6", "claude-cli/claude-opus-4-6"], + fallbacks: ["codex-cli/gpt-5.4"], }, models: { "anthropic/claude-opus-4-6": { alias: "Opus" }, - "claude-cli/claude-sonnet-4-6": {}, - "claude-cli/claude-opus-4-6": {}, + "codex-cli/gpt-5.4": {}, }, }, }, @@ -89,12 +81,9 @@ Add a CLI backend to your fallback list so it only runs when primary models fail Notes: -- If you use `agents.defaults.models` (allowlist), you must include `claude-cli/...`. +- If you use `agents.defaults.models` (allowlist), you must include your CLI backend models there too. - If the primary provider fails (auth, rate limits, timeouts), OpenClaw will try the CLI backend next. -- The bundled Claude CLI backend still accepts shorter aliases like - `claude-cli/opus`, `claude-cli/opus-4.6`, or `claude-cli/sonnet`, but docs - and config examples use the canonical `claude-cli/claude-*` refs. ## Configuration overview @@ -104,7 +93,7 @@ All CLI backends live under: agents.defaults.cliBackends ``` -Each entry is keyed by a **provider id** (e.g. `claude-cli`, `my-cli`). +Each entry is keyed by a **provider id** (e.g. `codex-cli`, `my-cli`). The provider id becomes the left side of your model ref: ``` @@ -118,8 +107,8 @@ The provider id becomes the left side of your model ref: agents: { defaults: { cliBackends: { - "claude-cli": { - command: "/opt/homebrew/bin/claude", + "codex-cli": { + command: "/opt/homebrew/bin/codex", }, "my-cli": { command: "my-cli", @@ -148,12 +137,19 @@ The provider id becomes the left side of your model ref: ## How it works -1. **Selects a backend** based on the provider prefix (`claude-cli/...`). +1. **Selects a backend** based on the provider prefix (`codex-cli/...`). 2. **Builds a system prompt** using the same OpenClaw prompt + workspace context. 3. **Executes the CLI** with a session id (if supported) so history stays consistent. 4. **Parses output** (JSON or plain text) and returns the final text. 5. **Persists session ids** per backend, so follow-ups reuse the same CLI session. + +The bundled Anthropic `claude-cli` backend was removed after Anthropic's +OpenClaw billing boundary changed. OpenClaw still supports generic CLI +backends, but Anthropic API traffic should use the Anthropic provider directly +instead of the removed local Claude CLI path. + + ## Sessions - If the CLI supports sessions, set `sessionArg` (e.g. `--session-id`) or @@ -171,7 +167,6 @@ Serialization notes: - `serialize: true` keeps same-lane runs ordered. - Most CLIs serialize on one provider lane. -- `claude-cli` is narrower: resumed runs serialize per Claude session id, and fresh runs serialize per workspace path. Independent workspaces can run in parallel. - OpenClaw drops stored CLI session reuse when the backend auth state changes, including relogin, token rotation, or a changed auth profile credential. ## Images (pass-through) @@ -186,15 +181,14 @@ imageMode: "repeat" OpenClaw will write base64 images to temp files. If `imageArg` is set, those paths are passed as CLI args. If `imageArg` is missing, OpenClaw appends the file paths to the prompt (path injection), which is enough for CLIs that auto- -load local files from plain paths (Claude CLI behavior). +load local files from plain paths. ## Inputs / outputs - `output: "json"` (default) tries to parse JSON and extract text + session id. - For Gemini CLI JSON output, OpenClaw reads reply text from `response` and usage from `stats` when `usage` is missing or empty. -- `output: "jsonl"` parses JSONL streams (for example Claude CLI `stream-json` - and Codex CLI `--json`) and extracts the final agent message plus session +- `output: "jsonl"` parses JSONL streams (for example Codex CLI `--json`) and extracts the final agent message plus session identifiers when present. - `output: "text"` treats stdout as the final response. @@ -206,19 +200,6 @@ Input modes: ## Defaults (plugin-owned) -The bundled Anthropic plugin registers a default for `claude-cli`: - -- `command: "claude"` -- `args: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions"]` -- `resumeArgs: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]` -- `output: "jsonl"` -- `input: "stdin"` -- `modelArg: "--model"` -- `systemPromptArg: "--append-system-prompt"` -- `sessionArg: "--session-id"` -- `systemPromptWhen: "first"` -- `sessionMode: "always"` - The bundled OpenAI plugin also registers a default for `codex-cli`: - `command: "codex"` @@ -270,7 +251,6 @@ opt into a generated MCP config overlay with `bundleMcp: true`. Current bundled behavior: -- `claude-cli`: `bundleMcp: true` (default) - `codex-cli`: no bundle MCP overlay - `google-gemini-cli`: no bundle MCP overlay @@ -283,19 +263,16 @@ When bundle MCP is enabled, OpenClaw: - merges them with any existing backend `--mcp-config` - rewrites the CLI args to pass `--strict-mcp-config --mcp-config ` -The `--strict-mcp-config` flag prevents Claude CLI from inheriting ambient -user-level or global MCP servers. If no MCP servers are enabled, OpenClaw still -injects a strict empty config so background runs stay isolated. +If no MCP servers are enabled, OpenClaw still injects a strict config when a +backend opts into bundle MCP so background runs stay isolated. ## Limitations - **No direct OpenClaw tool calls.** OpenClaw does not inject tool calls into - the CLI backend protocol. However, backends with `bundleMcp: true` (the - Claude CLI default) receive gateway tools through a loopback MCP bridge, - so Claude CLI can invoke OpenClaw tools via its native MCP support. -- **Streaming is backend-specific.** Claude CLI uses JSONL streaming - (`stream-json` with `--include-partial-messages`); other CLI backends may - still be buffered until exit. + the CLI backend protocol. Backends only see gateway tools when they opt into + `bundleMcp: true`. +- **Streaming is backend-specific.** Some backends stream JSONL; others buffer + until exit. - **Structured outputs** depend on the CLI’s JSON format. - **Codex CLI sessions** resume via text output (no JSONL), which is less structured than the initial `--json` run. OpenClaw sessions still work diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index af790734d88..f8f1fe23c96 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1073,8 +1073,8 @@ Optional CLI backends for text-only fallback runs (no tool calls). Useful as a b agents: { defaults: { cliBackends: { - "claude-cli": { - command: "/opt/homebrew/bin/claude", + "codex-cli": { + command: "/opt/homebrew/bin/codex", }, "my-cli": { command: "my-cli", diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md index 12742ac1fca..de793c4f743 100644 --- a/docs/gateway/doctor.md +++ b/docs/gateway/doctor.md @@ -307,11 +307,18 @@ Doctor checks: Doctor inspects OAuth profiles in the auth store, warns when tokens are expiring/expired, and can refresh them when safe. If the Anthropic -OAuth/token profile is stale, it suggests migrating to Claude CLI or an -Anthropic API key. +OAuth/token profile is stale, it suggests an Anthropic API key or the legacy +Anthropic setup-token path. Refresh prompts only appear when running interactively (TTY); `--non-interactive` skips refresh attempts. +Doctor also detects stale removed Anthropic Claude CLI state. If old +`anthropic:claude-cli` credential bytes still exist in `auth-profiles.json`, +doctor converts them back into Anthropic token/OAuth profiles and rewrites +stale `claude-cli/...` model refs plus `agents.defaults.cliBackends.claude-cli`. +If the bytes are gone, doctor removes the stale config and prints recovery +commands instead. + Doctor also reports auth profiles that are temporarily unusable due to: - short cooldowns (rate limits/timeouts/auth failures) diff --git a/docs/help/faq.md b/docs/help/faq.md index bbe744f5ab9..1fafb2f368e 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -565,7 +565,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, `openclaw onboard` is the recommended setup path. In **local mode** it walks you through: - - **Model/auth setup** (provider OAuth, Claude CLI reuse, and API keys supported, plus local model options such as LM Studio) + - **Model/auth setup** (provider OAuth, API keys, Anthropic legacy setup-token, plus local model options such as LM Studio) - **Workspace** location + bootstrap files - **Gateway settings** (bind/port/auth/tailscale) - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, plus bundled channel plugins like QQ Bot) @@ -581,14 +581,17 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, **local-only models** so your data stays on your device. Subscriptions (Claude Pro/Max or OpenAI Codex) are optional ways to authenticate those providers. - We believe Claude Code CLI fallback is likely allowed for local, - user-managed automation based on Anthropic's public CLI docs. That said, - Anthropic's third-party harness policy creates enough ambiguity around - subscription-backed use in external products that we do not recommend it - for production. Anthropic also notified OpenClaw users on **April 4, 2026 - at 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path - counts as third-party harness usage and now requires **Extra Usage** - billed separately from the subscription. OpenAI Codex OAuth is explicitly + For Anthropic in OpenClaw, the practical split is: + + - **Anthropic API key**: normal Anthropic API billing + - **Claude subscription auth in OpenClaw**: Anthropic told OpenClaw users on + **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this requires + **Extra Usage** billed separately from the subscription + + Our local repros also show that `claude -p --append-system-prompt ...` can + hit the same Extra Usage guard when the appended prompt identifies + OpenClaw, while the same prompt string does **not** reproduce that block on + the Anthropic SDK + API-key path. OpenAI Codex OAuth is explicitly supported for external tools like OpenClaw. OpenClaw also supports other hosted subscription-style options including @@ -603,30 +606,27 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - Yes, via a local **Claude CLI** login on the gateway host. + Yes, but treat it as **Claude subscription auth with Extra Usage**. - Claude Pro/Max subscriptions **do not include an API key**, so Claude CLI - reuse is the local fallback path in OpenClaw. We believe Claude Code CLI - fallback is likely allowed for local, user-managed automation based on - Anthropic's public CLI docs. That said, Anthropic's third-party harness - policy creates enough ambiguity around subscription-backed use in external - products that we do not recommend it for production. We recommend - Anthropic API keys instead. + Claude Pro/Max subscriptions do not include an API key. In OpenClaw, that + means Anthropic's OpenClaw-specific billing notice applies: subscription + traffic requires **Extra Usage**. If you want Anthropic traffic without + that Extra Usage path, use an Anthropic API key instead. - Yes. Reuse a local **Claude CLI** login on the gateway host with `openclaw models auth login --provider anthropic --method cli --set-default`. + Yes, but the supported interpretation is now: - Anthropic setup-token is also available again as a legacy/manual OpenClaw path. Anthropic's OpenClaw-specific billing notice still applies there, so use it with the expectation that Anthropic requires **Extra Usage**. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). + - Anthropic in OpenClaw with a subscription means **Extra Usage** + - Anthropic in OpenClaw without that path means **API key** - Important: We believe Claude Code CLI fallback is likely allowed for local, - user-managed automation based on Anthropic's public CLI docs. That said, - Anthropic's third-party harness policy creates enough ambiguity around - subscription-backed use in external products that we do not recommend it - for production. Anthropic also told OpenClaw users on **April 4, 2026 at - 12:00 PM PT / 8:00 PM BST** that the **OpenClaw** Claude-login path - requires **Extra Usage** billed separately from the subscription. + Anthropic setup-token is still available as a legacy/manual OpenClaw path, + and Anthropic's OpenClaw-specific billing notice still applies there. We + also reproduced the same billing guard locally with direct + `claude -p --append-system-prompt ...` usage when the appended prompt + identifies OpenClaw, while the same prompt string did **not** reproduce on + the Anthropic SDK + API-key path. For production or multi-user workloads, Anthropic API key auth is the safer, recommended choice. If you want other subscription-style hosted diff --git a/docs/help/testing.md b/docs/help/testing.md index 08524bc9869..2afbabe167f 100644 --- a/docs/help/testing.md +++ b/docs/help/testing.md @@ -245,7 +245,7 @@ openclaw models list openclaw models list --json ``` -## Live: CLI backend smoke (Claude CLI or other local CLIs) +## Live: CLI backend smoke (Codex CLI or other local CLIs) - Test: `src/gateway/gateway-cli-backend.live.test.ts` - Goal: validate the Gateway + agent pipeline using a local CLI backend, without touching your default config. @@ -253,26 +253,23 @@ openclaw models list --json - `pnpm test:live` (or `OPENCLAW_LIVE_TEST=1` if invoking Vitest directly) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Defaults: - - Model: `claude-cli/claude-sonnet-4-6` - - Command: `claude` - - Args: `["-p","--output-format","stream-json","--include-partial-messages","--verbose","--permission-mode","bypassPermissions"]` + - Model: `codex-cli/gpt-5.4` + - Command: `codex` + - Args: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]` - Overrides (optional): - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"` - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"` - - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","stream-json","--include-partial-messages","--verbose","--permission-mode","bypassPermissions"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'` + - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` + - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` to send a real image attachment (paths are injected into the prompt). - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` to pass image file paths as CLI args instead of prompt injection. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (or `"list"`) to control how image args are passed when `IMAGE_ARG` is set. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` to send a second turn and validate resume flow. -- `OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0` to keep Claude CLI MCP config enabled (default injects a temporary strict empty `--mcp-config` so ambient/global MCP servers stay disabled during the smoke). Example: ```bash OPENCLAW_LIVE_CLI_BACKEND=1 \ - OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-6" \ + OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` @@ -285,10 +282,8 @@ pnpm test:docker:live-cli-backend Notes: - The Docker runner lives at `scripts/test-live-cli-backend-docker.sh`. -- It runs the live CLI-backend smoke inside the repo Docker image as the non-root `node` user, because Claude CLI rejects `bypassPermissions` when invoked as root. -- For `claude-cli`, it installs the Linux `@anthropic-ai/claude-code` package into a cached writable prefix at `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`). -- For `claude-cli`, the live smoke injects a strict empty MCP config unless you set `OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0`. -- It copies `~/.claude` into the container when available, but on machines where Claude auth is backed by `ANTHROPIC_API_KEY`, it also preserves `ANTHROPIC_API_KEY` / `ANTHROPIC_API_KEY_OLD` for the child Claude CLI via `OPENCLAW_LIVE_CLI_BACKEND_PRESERVE_ENV`. +- It runs the live CLI-backend smoke inside the repo Docker image as the non-root `node` user. +- For `codex-cli`, it installs the Linux `@openai/codex` package into a cached writable prefix at `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`). ## Live: ACP bind smoke (`/acp spawn ... --bind here`) @@ -330,8 +325,8 @@ pnpm test:docker:live-acp-bind Docker notes: - The Docker runner lives at `scripts/test-live-acp-bind-docker.sh`. -- It sources `~/.profile`, copies the matching CLI auth home (`~/.claude` or `~/.codex`) into the container, then installs the requested live CLI (`@anthropic-ai/claude-code` or `@openai/codex`) if missing. -- Inside Docker, the runner relies on the embedded `acpx` plugin's built-in agent registry and the sourced profile env; use `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` only when you need a custom harness command. +- It sources `~/.profile`, stages the matching CLI auth material into the container, installs `acpx` into a writable npm prefix, then installs the requested live CLI (`@anthropic-ai/claude-code` or `@openai/codex`) if missing. +- Inside Docker, the runner sets `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` so acpx keeps provider env vars from the sourced profile available to the child harness CLI. ### Recommended live recipes @@ -528,9 +523,10 @@ Useful env vars: - `OPENCLAW_WORKSPACE_DIR=...` (default: `~/.openclaw/workspace`) mounted to `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (default: `~/.profile`) mounted to `/home/node/.profile` and sourced before running tests - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (default: `~/.cache/openclaw/docker-cli-tools`) mounted to `/home/node/.npm-global` for cached CLI installs inside Docker -- External CLI auth dirs under `$HOME` are mounted read-only under `/host-auth/...`, then copied into `/home/node/...` before tests start - - Default: mount all supported dirs (`.codex`, `.claude`, `.minimax`) - - Narrowed provider runs mount only the needed dirs inferred from `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` +- External CLI auth dirs/files under `$HOME` are mounted read-only under `/host-auth...`, then copied into `/home/node/...` before tests start + - Default dirs: `.codex`, `.minimax` + - Default files: `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` + - Narrowed provider runs mount only the needed dirs/files inferred from `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Override manually with `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, or a comma list like `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` to narrow the run - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` to filter providers in-container diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index 81856ab6647..918050c1795 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -354,9 +354,9 @@ descriptor-backed placeholders for parse-time lazy loading. ### CLI backend registration `api.registerCliBackend(...)` lets a plugin own the default config for a local -AI CLI backend such as `claude-cli` or `codex-cli`. +AI CLI backend such as `codex-cli`. -- The backend `id` becomes the provider prefix in model refs like `claude-cli/opus`. +- The backend `id` becomes the provider prefix in model refs like `codex-cli/gpt-5`. - The backend `config` uses the same shape as `agents.defaults.cliBackends.`. - User config still wins. OpenClaw merges `agents.defaults.cliBackends.` over the plugin default before running the CLI. diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index 533c05b4191..a6c4011a6a4 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -1,34 +1,37 @@ --- -summary: "Use Anthropic Claude via API keys or Claude CLI in OpenClaw" +summary: "Use Anthropic Claude via API keys in OpenClaw" read_when: - You want to use Anthropic models in OpenClaw - - You want to reuse Claude CLI subscription auth on the gateway host title: "Anthropic" --- # Anthropic (Claude) Anthropic builds the **Claude** model family and provides access via an API. -In OpenClaw, new Anthropic setup should use an API key or the local Claude CLI -backend. Existing legacy Anthropic token profiles are still honored at runtime -if they are already configured. +In OpenClaw, new Anthropic setup should use an API key. Existing legacy +Anthropic token profiles are still honored at runtime if they are already +configured. -Anthropic's public Claude Code docs explicitly document non-interactive CLI -usage such as `claude -p`. Based on those docs, we believe local, -user-managed Claude Code CLI fallback is likely allowed. +For Anthropic in OpenClaw, the billing split is: -Separately, Anthropic notified OpenClaw users on **April 4, 2026 at 12:00 PM -PT / 8:00 PM BST** that **OpenClaw counts as a third-party harness**. Their -stated policy is that OpenClaw-driven Claude-login traffic no longer uses the -included Claude subscription pool and instead requires **Extra Usage** -(pay-as-you-go, billed separately from the subscription). +- **Anthropic API key**: normal Anthropic API billing. +- **Claude subscription auth inside OpenClaw**: Anthropic told OpenClaw users on + **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that this counts as + third-party harness usage and requires **Extra Usage** (pay-as-you-go, + billed separately from the subscription). -That policy distinction is about **OpenClaw-driven Claude CLI reuse**, not -about running `claude` directly in your own terminal. That said, Anthropic's -third-party harness policy still leaves enough ambiguity around -subscription-backed use in external products that we do not recommend this -path for production. +Our local repros match that split: + +- direct `claude -p` may still work +- `claude -p --append-system-prompt ...` can trip the Extra Usage guard when + the prompt identifies OpenClaw +- the same OpenClaw-like system prompt does **not** reproduce the block on the + Anthropic SDK + `ANTHROPIC_API_KEY` path + +So the practical rule is: **Anthropic API key, or Claude subscription with +Extra Usage**. If you want the clearest production path, use an Anthropic API +key. Anthropic's current public docs: @@ -60,7 +63,7 @@ openclaw onboard openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ``` -### Claude CLI config snippet +### Anthropic config snippet ```json5 { @@ -210,166 +213,31 @@ legacy Anthropic token auth (`sk-ant-oat-*`). If you configure falls back to the standard context window by skipping the context1m beta header while keeping the required OAuth betas. -## Option B: Claude CLI as the message provider +## Removed: Claude CLI backend -**Best for:** a single-user gateway host that already has Claude CLI installed -and signed in, as a local fallback rather than the recommended production path. +The bundled Anthropic `claude-cli` backend was removed. -Billing note: We believe Claude Code CLI fallback is likely allowed for local, -user-managed automation based on Anthropic's public CLI docs. That said, -Anthropic's third-party harness policy creates enough ambiguity around -subscription-backed use in external products that we do not recommend it for -production. Anthropic also told OpenClaw users that **OpenClaw-driven** Claude -CLI usage is treated as third-party harness traffic and, as of **April 4, 2026 -at 12:00 PM PT / 8:00 PM BST**, requires **Extra Usage** instead of the -included Claude subscription limits. - -This path uses the local `claude` binary for model inference instead of calling -the Anthropic API directly. OpenClaw treats it as a **CLI backend provider** -with model refs like: - -- `claude-cli/claude-sonnet-4-6` -- `claude-cli/claude-opus-4-6` - -How it works: - -1. OpenClaw launches `claude -p --output-format stream-json --include-partial-messages ...` - on the **gateway host** and sends the prompt over stdin. -2. The first turn sends `--session-id `. -3. Follow-up turns reuse the stored Claude session via `--resume `. -4. Your chat messages still go through the normal OpenClaw message pipeline, but - the actual model reply is produced by Claude CLI. - -### Requirements - -- Claude CLI installed on the gateway host and available on PATH, or configured - with an absolute command path. -- Claude CLI already authenticated on that same host: - -```bash -claude auth status -``` - -- OpenClaw auto-loads the bundled Anthropic plugin at gateway startup when your - config explicitly references `claude-cli/...` or `claude-cli` backend config. - -### Config snippet - -```json5 -{ - agents: { - defaults: { - model: { - primary: "claude-cli/claude-sonnet-4-6", - }, - models: { - "claude-cli/claude-sonnet-4-6": {}, - }, - sandbox: { mode: "off" }, - }, - }, -} -``` - -If the `claude` binary is not on the gateway host PATH: - -```json5 -{ - agents: { - defaults: { - cliBackends: { - "claude-cli": { - command: "/opt/homebrew/bin/claude", - }, - }, - }, - }, -} -``` - -### What you get - -- Claude subscription auth reused from the local CLI (read at runtime, not persisted) -- Normal OpenClaw message/session routing -- Claude CLI session continuity across turns (invalidated on auth changes) -- Gateway tools exposed to Claude CLI via loopback MCP bridge -- JSONL streaming with live partial-message progress - -### Migrate from Anthropic auth to Claude CLI - -If you currently use `anthropic/...` with a legacy token profile or API key and want to -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 -``` - -Or in onboarding: - -```bash -openclaw onboard --auth-choice anthropic-cli -``` - -Interactive `openclaw onboard` and `openclaw configure` now prefer **Anthropic -Claude CLI** first and **Anthropic API key** second. - -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` - -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 -- 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. -- OpenClaw does not inject tool calls directly. Claude CLI receives gateway - tools through a loopback MCP bridge (`bundleMcp: true`, the default). -- Claude CLI streams replies via JSONL (`stream-json` with - `--include-partial-messages`). Prompts are sent over stdin, not argv. -- Auth is read at runtime from live Claude CLI credentials and is not persisted - to OpenClaw profiles. Keychain prompts are suppressed in non-interactive - contexts. -- Session reuse is tracked via `cliSessionBinding` metadata. When Claude CLI - login state changes (relogin, token rotation), stored sessions are - invalidated and a fresh session starts. -- Best fit for a personal gateway host, not shared multi-user billing setups. - -More details: [/gateway/cli-backends](/gateway/cli-backends) +- Anthropic's April 4, 2026 notice says OpenClaw-driven Claude-login traffic is + third-party harness usage and requires **Extra Usage**. +- Our local repros also show that direct + `claude -p --append-system-prompt ...` can hit the same guard when the + appended prompt identifies OpenClaw. +- The same OpenClaw-like system prompt does not hit that guard on the + Anthropic SDK + `ANTHROPIC_API_KEY` path. +- Use Anthropic API keys for Anthropic traffic in OpenClaw. +- If you need a local CLI fallback runtime, use another supported CLI backend + such as Codex CLI. See [/gateway/cli-backends](/gateway/cli-backends). ## Notes - Anthropic's public Claude Code docs still document direct CLI usage such as - `claude -p`. We believe local, user-managed fallback is likely allowed, but - Anthropic's separate notice to OpenClaw users says the **OpenClaw** - Claude-login path is third-party harness usage and requires **Extra Usage** - (pay-as-you-go billed separately from the subscription). For production, we + `claude -p`, but Anthropic's separate notice to OpenClaw users says the + **OpenClaw** Claude-login path is third-party harness usage and requires + **Extra Usage** (pay-as-you-go billed separately from the subscription). + Our local repros also show that direct + `claude -p --append-system-prompt ...` can hit the same guard when the + appended prompt identifies OpenClaw, while the same prompt shape does not + reproduce on the Anthropic SDK + `ANTHROPIC_API_KEY` path. For production, we recommend Anthropic API keys instead. - Anthropic setup-token is available again in OpenClaw as a legacy/manual path. Anthropic's OpenClaw-specific billing notice still applies, so use it with the expectation that Anthropic requires **Extra Usage** for this path. - Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth). @@ -379,7 +247,7 @@ More details: [/gateway/cli-backends](/gateway/cli-backends) **401 errors / token suddenly invalid** - Legacy Anthropic token auth can expire or be revoked. -- For new setup, migrate to an Anthropic API key or the local Claude CLI path on the gateway host. +- For new setup, migrate to an Anthropic API key. **No API key found for provider "anthropic"** @@ -390,7 +258,7 @@ More details: [/gateway/cli-backends](/gateway/cli-backends) **No credentials found for profile `anthropic:default`** - Run `openclaw models status` to see which auth profile is active. -- Re-run onboarding, or configure an API key or Claude CLI for that profile path. +- Re-run onboarding, or configure an API key for that profile path. **No available auth profile (all in cooldown/unavailable)** diff --git a/docs/reference/wizard.md b/docs/reference/wizard.md index 628147bce76..7b2561b22d8 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 Claude CLI**: preferred Anthropic assistant choice in onboarding/configure. 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 a canonical `claude-cli/claude-*` ref. + - **Anthropic API key**: preferred Anthropic assistant choice in onboarding/configure. - **Anthropic setup-token (legacy/manual)**: available again in onboarding/configure, but Anthropic told OpenClaw users that the OpenClaw Claude-login path counts as third-party harness usage and requires **Extra Usage** on the Claude account. - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it. Reused Codex CLI credentials stay managed by Codex CLI; on expiry OpenClaw re-reads that source first and, when the provider can refresh it, writes the refreshed credential back to Codex storage instead of taking ownership itself. - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. diff --git a/docs/start/wizard-cli-automation.md b/docs/start/wizard-cli-automation.md index 163481b0313..f39cf483c91 100644 --- a/docs/start/wizard-cli-automation.md +++ b/docs/start/wizard-cli-automation.md @@ -51,18 +51,15 @@ openclaw onboard --non-interactive \ ## Provider-specific examples - + ```bash openclaw onboard --non-interactive \ --mode local \ - --auth-choice anthropic-cli \ + --auth-choice apiKey \ + --anthropic-api-key "$ANTHROPIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` - - Requires Claude CLI already installed and signed in on the same gateway - host. - ```bash diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index e2f363a2a23..70acd7f0086 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -129,19 +129,6 @@ 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 a canonical `claude-cli/claude-*` ref. - - This is an available local fallback path in `openclaw onboard` and - `openclaw configure`. For production, prefer an Anthropic API key. - - - macOS: checks Keychain item "Claude Code-credentials" - - Linux and Windows: reuses `~/.claude/.credentials.json` if present - - On macOS, choose "Always Allow" so launchd starts do not block. - - If `~/.codex/auth.json` exists, the wizard can reuse it. Reused Codex CLI credentials stay managed by Codex CLI; on expiry OpenClaw diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index 74f02cba305..d8f7df80650 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -111,9 +111,8 @@ For Claude Code through ACP, the stack is: Important distinction: -- ACP Claude is not the same thing as the direct `claude-cli/...` fallback runtime. - ACP Claude is a harness session with ACP controls, session resume, background-task tracking, and optional conversation/thread binding. -- `claude-cli/...` is a text-only local CLI backend. See [CLI Backends](/gateway/cli-backends). +- CLI backends are separate text-only local fallback runtimes. See [CLI Backends](/gateway/cli-backends). For operators, the practical rule is: