mirror of https://github.com/openclaw/openclaw.git
docs(anthropic): clarify api key and doctor recovery
This commit is contained in:
Peter Steinberger
parent
2d7157b424
commit
fe93f29486
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 <auto|full|compact>`: websocket log style (default `auto`).
|
||||
- `--compact`: alias for `--ws-log compact`.
|
||||
- `--raw-stream`: log raw model stream events to jsonl.
|
||||
|
|
|
|||
|
|
@ -1354,7 +1354,6 @@ Options:
|
|||
- `--force` (kill existing listener on port)
|
||||
- `--verbose`
|
||||
- `--cli-backend-logs`
|
||||
- `--claude-cli-logs` (deprecated alias)
|
||||
- `--ws-log <auto|full|compact>`
|
||||
- `--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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <duration>` 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**.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
## 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 <generated-file>`
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -565,7 +565,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
|||
<Accordion title="What does onboarding actually do?">
|
||||
`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,
|
|||
</Accordion>
|
||||
|
||||
<Accordion title="Can I use Claude Max subscription without an API key?">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Do you support Claude subscription auth (Claude Pro or Max)?">
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.<id>`.
|
||||
- User config still wins. OpenClaw merges `agents.defaults.cliBackends.<id>` over the
|
||||
plugin default before running the CLI.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<Warning>
|
||||
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 <uuid>`.
|
||||
3. Follow-up turns reuse the stored Claude session via `--resume <sessionId>`.
|
||||
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)**
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ For a high-level overview, see [Onboarding (CLI)](/start/wizard).
|
|||
</Step>
|
||||
<Step title="Model/Auth">
|
||||
- **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`.
|
||||
|
|
|
|||
|
|
@ -51,18 +51,15 @@ openclaw onboard --non-interactive \
|
|||
## Provider-specific examples
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anthropic Claude CLI example">
|
||||
<Accordion title="Anthropic API key example">
|
||||
```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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gemini example">
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -129,19 +129,6 @@ What you set:
|
|||
<Accordion title="Anthropic API key">
|
||||
Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
|
||||
</Accordion>
|
||||
<Accordion title="Anthropic Claude CLI">
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI Code subscription (Codex CLI reuse)">
|
||||
If `~/.codex/auth.json` exists, the wizard can reuse it.
|
||||
Reused Codex CLI credentials stay managed by Codex CLI; on expiry OpenClaw
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue