mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-05 22:32:12 +00:00
docs: clarify anthropic extra usage billing
This commit is contained in:
Peter Steinberger
@@ -1479,13 +1479,14 @@ 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: Anthropic changed third-party harness billing on **April 4, 2026
|
||||
at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no
|
||||
longer cover OpenClaw, and Claude CLI usage in OpenClaw now 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, Qwen Cloud Coding Plan, MiniMax Coding Plan, or
|
||||
Z.AI / GLM Coding Plan.
|
||||
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. 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:
|
||||
|
||||
@@ -1495,8 +1496,9 @@ openclaw models auth login --provider anthropic --method cli --set-default
|
||||
|
||||
Onboarding shortcut: `openclaw onboard --auth-choice anthropic-cli`
|
||||
|
||||
Existing Anthropic OAuth/token profiles still run if already configured, but
|
||||
OpenClaw no longer offers Anthropic setup-token as a new auth path.
|
||||
Anthropic setup-token is also 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.
|
||||
@@ -1609,7 +1611,7 @@ Notes:
|
||||
- `setup-token` and `paste-token` are generic token commands for providers that expose token auth methods.
|
||||
- `setup-token` requires an interactive TTY and runs the provider's token-auth method.
|
||||
- `paste-token` prompts for the token value and defaults to auth profile id `<provider>:manual` when `--profile-id` is omitted.
|
||||
- Anthropic OAuth/token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.
|
||||
- Anthropic `setup-token` / `paste-token` are available again as a legacy/manual OpenClaw path. Anthropic told OpenClaw users this path requires **Extra Usage** on the Claude account.
|
||||
|
||||
### `models auth order get|set|clear`
|
||||
|
||||
|
||||
@@ -99,7 +99,7 @@ openclaw models fallbacks list
|
||||
openclaw models auth add
|
||||
openclaw models auth login --provider <id>
|
||||
openclaw models auth setup-token --provider <id>
|
||||
openclaw models auth paste-token --provider <id>
|
||||
openclaw models auth paste-token
|
||||
```
|
||||
|
||||
`models auth add` is the interactive auth helper. It can launch a provider auth
|
||||
@@ -126,10 +126,11 @@ Notes:
|
||||
- `setup-token` requires an interactive TTY and runs the provider's token-auth
|
||||
method (defaulting to that provider's `setup-token` method when it exposes
|
||||
one).
|
||||
- `paste-token` accepts a token string generated elsewhere or from automation.
|
||||
- `paste-token` requires `--provider`, prompts for the token value, and writes
|
||||
it to the default profile id `<provider>:manual` unless you pass
|
||||
`--profile-id`.
|
||||
- `paste-token --expires-in <duration>` stores an absolute token expiry from a
|
||||
relative duration such as `365d` or `12h`.
|
||||
- Anthropic billing note: Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover OpenClaw, and Claude CLI traffic in OpenClaw now requires **Extra Usage** billed separately from the subscription.
|
||||
- Existing Anthropic OAuth/token profiles still run if already configured, but Anthropic no longer supports `setup-token` or `paste-token` as a new OpenClaw auth path.
|
||||
- Anthropic 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.
|
||||
- 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**.
|
||||
|
||||
@@ -255,8 +255,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
|
||||
- Example model: `anthropic/claude-opus-4-6`
|
||||
- CLI: `openclaw onboard --auth-choice apiKey` or `openclaw onboard --auth-choice anthropic-cli`
|
||||
- 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 changed third-party harness billing on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover OpenClaw, and Anthropic OAuth/subscription traffic now requires **Extra Usage** billed separately from the subscription.
|
||||
- Existing Anthropic OAuth/token profiles still run if already configured, but new setup is no longer offered through onboarding or auth commands.
|
||||
- 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.
|
||||
- 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
|
||||
{
|
||||
|
||||
@@ -13,11 +13,13 @@ title: "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 changed third-party harness billing on
|
||||
**April 4, 2026 at 12:00 PM PT / 8:00 PM BST**: Anthropic says Claude
|
||||
subscription limits no longer cover OpenClaw and Anthropic now requires **Extra
|
||||
Usage** for that traffic. OpenAI Codex OAuth is explicitly supported for use in
|
||||
external tools like OpenClaw. This page explains:
|
||||
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.
|
||||
OpenAI Codex OAuth is explicitly supported for use in external tools like
|
||||
OpenClaw. This page explains:
|
||||
|
||||
For Anthropic in production, API key auth is the safer recommended path.
|
||||
|
||||
@@ -64,29 +66,33 @@ All of the above also respect `$OPENCLAW_STATE_DIR` (state dir override). Full r
|
||||
|
||||
For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets).
|
||||
|
||||
## Anthropic OAuth/token compatibility
|
||||
## Anthropic legacy token compatibility
|
||||
|
||||
<Warning>
|
||||
Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM
|
||||
PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover
|
||||
OpenClaw or other third-party harnesses. Existing Anthropic OAuth/token profiles
|
||||
remain technically usable in OpenClaw, but Anthropic now requires **Extra
|
||||
Anthropic's public Claude Code docs say direct Claude Code use stays within
|
||||
Claude subscription limits. Separately, Anthropic told OpenClaw users on
|
||||
**April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that **OpenClaw counts as a
|
||||
third-party harness**. Existing Anthropic token profiles remain technically
|
||||
usable in OpenClaw, but Anthropic says the OpenClaw path now requires **Extra
|
||||
Usage** (pay-as-you-go billed separately from the subscription) for that
|
||||
traffic.
|
||||
|
||||
For Anthropic's current direct-Claude-Code plan docs, see [Using Claude Code
|
||||
with your Pro or Max
|
||||
plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
|
||||
and [Using Claude Code with your Team or Enterprise
|
||||
plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/).
|
||||
|
||||
If you want other subscription-style options in OpenClaw, see [OpenAI
|
||||
Codex](/providers/openai), [Qwen Cloud Coding
|
||||
Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
|
||||
and [Z.AI / GLM Coding Plan](/providers/glm).
|
||||
</Warning>
|
||||
|
||||
OpenClaw no longer offers Anthropic setup-token onboarding or auth commands for
|
||||
new setup. Existing Anthropic OAuth/token profiles are still honored at runtime
|
||||
if they are already configured.
|
||||
|
||||
The generic token helpers still exist for other providers:
|
||||
`openclaw models auth setup-token --provider <id>` and
|
||||
`openclaw models auth paste-token --provider <id>`.
|
||||
OpenClaw now exposes Anthropic setup-token again as a legacy/manual path.
|
||||
Anthropic's OpenClaw-specific billing notice still applies to that path, so
|
||||
use it with the expectation that Anthropic requires **Extra Usage** for
|
||||
OpenClaw-driven Claude-login traffic.
|
||||
|
||||
## Anthropic Claude CLI migration
|
||||
|
||||
@@ -113,10 +119,9 @@ openclaw onboard --auth-choice anthropic-cli
|
||||
```
|
||||
|
||||
This keeps existing Anthropic auth profiles for rollback, but rewrites the main
|
||||
default-model path from `anthropic/...` to a canonical
|
||||
`claude-cli/claude-*` ref, rewrites matching Anthropic Claude fallbacks, and
|
||||
adds matching canonical `claude-cli/claude-*` allowlist entries under
|
||||
`agents.defaults.models`.
|
||||
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:
|
||||
|
||||
@@ -136,10 +141,14 @@ 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 a canonical
|
||||
`claude-cli/claude-*` ref
|
||||
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`
|
||||
|
||||
@@ -59,22 +59,17 @@ API keys for daemon use: `openclaw onboard`.
|
||||
See [Help](/help) for details on env inheritance (`env.shellEnv`,
|
||||
`~/.openclaw/.env`, systemd/launchd).
|
||||
|
||||
## Anthropic: OAuth/token compatibility
|
||||
## Anthropic: legacy token compatibility
|
||||
|
||||
Existing Anthropic OAuth/token profiles are still honored at runtime if they
|
||||
are already configured, but OpenClaw no longer offers Anthropic setup-token
|
||||
auth for new setup via onboarding or `models auth` commands.
|
||||
Anthropic setup-token auth is still available in OpenClaw as a
|
||||
legacy/manual path. Anthropic's public Claude Code docs still cover direct
|
||||
Claude Code terminal use under Claude plans, but Anthropic separately told
|
||||
OpenClaw users that the **OpenClaw** Claude-login path counts as third-party
|
||||
harness usage and requires **Extra Usage** billed separately from the
|
||||
subscription.
|
||||
|
||||
For new setup, use an Anthropic API key or migrate to Claude CLI on the gateway
|
||||
host.
|
||||
|
||||
Other providers can still use the generic token helpers:
|
||||
|
||||
- `openclaw models auth setup-token --provider <id>` runs the provider's token
|
||||
auth flow (interactive TTY required).
|
||||
- `openclaw models auth paste-token --provider <id>` prompts for a token value
|
||||
and writes it to `auth-profiles.json` (default profile id:
|
||||
`<provider>:manual`).
|
||||
For the clearest setup path, use an Anthropic API key or migrate to Claude CLI
|
||||
on the gateway host.
|
||||
|
||||
Manual token entry (any provider; writes `auth-profiles.json` + updates config):
|
||||
|
||||
@@ -130,8 +125,8 @@ 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 a canonical `claude-cli/claude-*` ref and adds
|
||||
matching Claude CLI allowlist entries under `agents.defaults.models`.
|
||||
default model selection to `claude-cli/...` and adds matching Claude CLI
|
||||
allowlist entries under `agents.defaults.models`.
|
||||
|
||||
Verify:
|
||||
|
||||
@@ -145,8 +140,9 @@ Onboarding shortcut:
|
||||
openclaw onboard --auth-choice anthropic-cli
|
||||
```
|
||||
|
||||
Interactive `openclaw onboard` and `openclaw configure` prefer Claude CLI for
|
||||
Anthropic and no longer offer setup-token as a new setup path.
|
||||
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.
|
||||
|
||||
## Checking model auth status
|
||||
|
||||
@@ -211,12 +207,12 @@ openclaw models status
|
||||
|
||||
### Token expiring/expired
|
||||
|
||||
Run `openclaw models status` to confirm which profile is expiring. If an
|
||||
Anthropic OAuth/token profile is missing or expired, migrate that setup to Claude CLI
|
||||
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.
|
||||
|
||||
## Claude CLI requirements
|
||||
|
||||
Only needed for the Anthropic Claude CLI reuse path:
|
||||
|
||||
- Claude CLI installed (`claude` command available)
|
||||
- Claude Code CLI installed (`claude` command available)
|
||||
|
||||
@@ -581,11 +581,12 @@ 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.
|
||||
|
||||
Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM
|
||||
PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover
|
||||
OpenClaw, and Anthropic subscription auth in OpenClaw now requires **Extra
|
||||
Usage** billed separately from the subscription. OpenAI Codex OAuth is
|
||||
explicitly supported for external tools like OpenClaw.
|
||||
Anthropic's public Claude Code docs still include direct Claude Code terminal
|
||||
use 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 now requires
|
||||
**Extra Usage** billed separately from the subscription. OpenAI Codex OAuth
|
||||
is explicitly supported for external tools like OpenClaw.
|
||||
|
||||
OpenClaw also supports other hosted subscription-style options including
|
||||
**Qwen Cloud Coding Plan**, **MiniMax Coding Plan**, and
|
||||
@@ -602,26 +603,26 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
||||
Yes, via a local **Claude CLI** login on the gateway host.
|
||||
|
||||
Claude Pro/Max subscriptions **do not include an API key**, so Claude CLI
|
||||
reuse is the supported subscription-style path in OpenClaw. Anthropic
|
||||
changed third-party harness billing on **April 4, 2026 at 12:00 PM PT /
|
||||
8:00 PM BST**: Anthropic says OpenClaw now requires **Extra Usage** billed
|
||||
separately from the subscription for this path. If you want the clearest
|
||||
and safest supported path for production, use an Anthropic API key.
|
||||
reuse is the supported subscription-style path in OpenClaw. Anthropic's
|
||||
public Claude Code docs still cover direct Claude Code terminal use under
|
||||
your plan. Separately, Anthropic 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. If you
|
||||
want the clearest and safest supported path for production, use an
|
||||
Anthropic API key.
|
||||
|
||||
</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`.
|
||||
|
||||
Existing Anthropic OAuth/token profiles still run if they are already configured, but OpenClaw no longer offers Anthropic setup-token as a new setup path. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
|
||||
Other providers can still use the generic token helpers with
|
||||
`openclaw models auth setup-token --provider <id>` or
|
||||
`openclaw models auth paste-token --provider <id>`.
|
||||
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).
|
||||
|
||||
Important: Anthropic changed third-party harness billing on **April 4, 2026
|
||||
at 12:00 PM PT / 8:00 PM BST**. Anthropic says Claude subscription limits no
|
||||
longer cover OpenClaw, and Anthropic now requires **Extra Usage** billed
|
||||
separately from the subscription for Claude CLI traffic through OpenClaw.
|
||||
Important: Anthropic's public Claude Code docs still cover direct Claude
|
||||
Code terminal use under Claude plans. Separately, Anthropic 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.
|
||||
|
||||
For production or multi-user workloads, Anthropic API key auth is the
|
||||
safer, recommended choice. If you want other subscription-style hosted
|
||||
@@ -634,16 +635,15 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
||||
<a id="why-am-i-seeing-http-429-ratelimiterror-from-anthropic"></a>
|
||||
<Accordion title="Why am I seeing HTTP 429 rate_limit_error from Anthropic?">
|
||||
That means your **Anthropic quota/rate limit** is exhausted for the current window. If you
|
||||
use **Claude CLI** or **Anthropic OAuth/subscription tokens**, wait for the
|
||||
window to reset or enable/upgrade Extra Usage. If you use an **Anthropic API
|
||||
key**, check the Anthropic Console
|
||||
use **Claude CLI**, wait for the window to reset or upgrade your plan. If you
|
||||
use an **Anthropic API key**, check the Anthropic Console
|
||||
for usage/billing and raise limits as needed.
|
||||
|
||||
If the message is specifically:
|
||||
`Extra usage is required for long context requests`, the request is trying to use
|
||||
Anthropic's 1M context beta (`context1m: true`). That only works when your
|
||||
credential is eligible for long-context billing (API key billing or
|
||||
Anthropic OAuth/subscription auth with Extra Usage enabled).
|
||||
credential is eligible for long-context billing (API key billing or the
|
||||
OpenClaw Claude-login path with Extra Usage enabled).
|
||||
|
||||
Tip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited.
|
||||
See [Models](/cli/models), [OAuth](/concepts/oauth), and
|
||||
|
||||
@@ -10,15 +10,25 @@ title: "Anthropic"
|
||||
|
||||
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 Anthropic OAuth/token profiles are still honored at runtime
|
||||
backend. Existing legacy Anthropic token profiles are still honored at runtime
|
||||
if they are already configured.
|
||||
|
||||
<Warning>
|
||||
Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM
|
||||
PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover
|
||||
OpenClaw or other third-party harnesses. Existing Anthropic OAuth/token auth
|
||||
can still run in OpenClaw, but Anthropic now requires **Extra Usage**
|
||||
(pay-as-you-go, billed separately from the subscription) for that traffic.
|
||||
Anthropic's public Claude Code docs say direct Claude Code usage is included
|
||||
with Claude subscriptions. 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).
|
||||
|
||||
That policy distinction is about **OpenClaw-driven Claude CLI reuse**, not
|
||||
about running `claude` directly in your own terminal.
|
||||
|
||||
Anthropic's current direct-Claude-Code plan docs:
|
||||
|
||||
- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
|
||||
- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
|
||||
|
||||
If you want a clearer billing path, use an Anthropic API key instead. OpenClaw
|
||||
also supports other subscription-style options, including [OpenAI
|
||||
@@ -90,7 +100,7 @@ Important limits:
|
||||
|
||||
## Prompt caching (Anthropic API)
|
||||
|
||||
OpenClaw supports Anthropic's prompt caching feature. This is **API-only**; Anthropic OAuth/token auth does not honor cache settings.
|
||||
OpenClaw supports Anthropic's prompt caching feature. This is **API-only**; legacy Anthropic token auth does not honor cache settings.
|
||||
|
||||
### Configuration
|
||||
|
||||
@@ -182,25 +192,27 @@ This only activates when `params.context1m` is explicitly set to `true` for
|
||||
that model.
|
||||
|
||||
Requirement: Anthropic must allow long-context usage on that credential
|
||||
(typically API key billing, or Anthropic OAuth/subscription auth with Extra
|
||||
Usage enabled). Otherwise Anthropic returns:
|
||||
(typically API key billing, or OpenClaw's Claude-login path / legacy token auth
|
||||
with Extra Usage enabled). Otherwise Anthropic returns:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
|
||||
Note: Anthropic currently rejects `context-1m-*` beta requests when using
|
||||
Anthropic OAuth/subscription tokens (`sk-ant-oat-*`). If you configure
|
||||
`context1m: true` with that auth mode, OpenClaw logs a warning and falls back
|
||||
to the standard context window by skipping the context1m beta header while
|
||||
keeping the required OAuth betas.
|
||||
legacy Anthropic token auth (`sk-ant-oat-*`). If you configure
|
||||
`context1m: true` with that legacy auth mode, OpenClaw logs a warning and
|
||||
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
|
||||
|
||||
**Best for:** a single-user gateway host that already has Claude CLI installed
|
||||
and signed in with a Claude subscription.
|
||||
|
||||
Billing note: when Claude CLI is used through OpenClaw, Anthropic now treats
|
||||
that traffic as third-party harness usage. As of **April 4, 2026 at 12:00 PM
|
||||
PT / 8:00 PM BST**, Anthropic requires **Extra Usage** instead of included
|
||||
Claude subscription limits for this path.
|
||||
Billing note: Anthropic's public Claude Code docs cover **direct** Claude Code
|
||||
usage under Pro/Max or Team/Enterprise plans. Separately, Anthropic told
|
||||
OpenClaw users that **OpenClaw-driven** Claude CLI usage is treated as
|
||||
third-party harness traffic. As of **April 4, 2026 at 12:00 PM PT / 8:00 PM
|
||||
BST**, Anthropic says this OpenClaw path 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**
|
||||
@@ -209,10 +221,6 @@ with model refs like:
|
||||
- `claude-cli/claude-sonnet-4-6`
|
||||
- `claude-cli/claude-opus-4-6`
|
||||
|
||||
Shorter aliases like `claude-cli/sonnet`, `claude-cli/opus`, or
|
||||
`claude-cli/opus-4.6` still normalize through the bundled backend, but docs
|
||||
and config examples use the canonical `claude-cli/claude-*` refs.
|
||||
|
||||
How it works:
|
||||
|
||||
1. OpenClaw launches `claude -p --output-format stream-json --include-partial-messages ...`
|
||||
@@ -277,7 +285,7 @@ If the `claude` binary is not on the gateway host PATH:
|
||||
|
||||
### Migrate from Anthropic auth to Claude CLI
|
||||
|
||||
If you currently use `anthropic/...` with an Anthropic OAuth/token profile or API key and want to
|
||||
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.
|
||||
|
||||
@@ -304,11 +312,10 @@ 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 a canonical `claude-cli/claude-*` ref
|
||||
- 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 canonical `claude-cli/claude-*` entries to
|
||||
`agents.defaults.models`
|
||||
- adds matching `claude-cli/...` entries to `agents.defaults.models`
|
||||
|
||||
Quick verification:
|
||||
|
||||
@@ -316,8 +323,7 @@ Quick verification:
|
||||
openclaw models status
|
||||
```
|
||||
|
||||
You should see the resolved primary model under a canonical
|
||||
`claude-cli/claude-*` ref.
|
||||
You should see the resolved primary model under `claude-cli/...`.
|
||||
|
||||
What it does **not** do:
|
||||
|
||||
@@ -339,13 +345,12 @@ More details: [/gateway/cli-backends](/gateway/cli-backends)
|
||||
|
||||
## Notes
|
||||
|
||||
- Anthropic says that starting **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**,
|
||||
OpenClaw usage with Claude CLI or Anthropic OAuth/subscription token auth
|
||||
requires **Extra Usage** (pay-as-you-go billed separately from the
|
||||
- Anthropic's public Claude Code plan docs still cover direct Claude Code
|
||||
terminal use under Claude subscriptions. 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).
|
||||
- Existing Anthropic OAuth/token profiles are still honored at runtime, but
|
||||
OpenClaw no longer offers setup-token onboarding or auth commands for new
|
||||
setups.
|
||||
- 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).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -31,11 +31,13 @@ OpenClaw features that can generate provider usage or paid API calls.
|
||||
`stats`, normalizes `stats.cached` into `cacheRead`, and derives input tokens
|
||||
from `stats.input_tokens - stats.cached` when needed.
|
||||
|
||||
Anthropic note: starting **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**,
|
||||
Anthropic says OpenClaw no longer uses included Claude subscription limits.
|
||||
Anthropic subscription-auth traffic in OpenClaw now requires **Extra Usage**
|
||||
billed separately from the subscription, but Anthropic does not expose a
|
||||
per-message dollar estimate that OpenClaw can show in `/usage full`.
|
||||
Anthropic note: Anthropic's public Claude Code docs still include direct Claude
|
||||
Code terminal usage in Claude plan limits. Separately, Anthropic told OpenClaw
|
||||
users that starting **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**, the
|
||||
**OpenClaw** Claude-login path counts as third-party harness usage and
|
||||
requires **Extra Usage** billed separately from the subscription. Anthropic
|
||||
does not expose a per-message dollar estimate that OpenClaw can show in
|
||||
`/usage full`.
|
||||
|
||||
**CLI usage windows (provider quotas)**
|
||||
|
||||
@@ -74,9 +76,9 @@ Every reply or tool call uses the **current model provider** (OpenAI, Anthropic,
|
||||
primary source of usage and cost.
|
||||
|
||||
This also includes subscription-style hosted providers that still bill outside
|
||||
OpenClaw's local UI, such as **OpenAI Codex**, **Qwen Cloud Coding Plan**,
|
||||
**MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, and
|
||||
Anthropic subscription auth with **Extra Usage** enabled.
|
||||
OpenClaw's local UI, such as **OpenAI Codex**, **Alibaba Cloud Model Studio
|
||||
Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, and
|
||||
Anthropic's OpenClaw Claude-login path with **Extra Usage** enabled.
|
||||
|
||||
See [Models](/providers/models) for pricing config and [Token use & costs](/reference/token-use) for display.
|
||||
|
||||
|
||||
@@ -178,9 +178,9 @@ This maps to Anthropic's `context-1m-2025-08-07` beta header.
|
||||
This only applies when `context1m: true` is set on that model entry.
|
||||
|
||||
Requirement: the credential must be eligible for long-context usage (API key
|
||||
billing, or Anthropic OAuth/subscription auth with Extra Usage enabled). If
|
||||
not, Anthropic responds with
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
billing, or OpenClaw's Claude-login path with Extra Usage enabled). If not,
|
||||
Anthropic responds
|
||||
with `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
|
||||
If you authenticate Anthropic with OAuth/subscription tokens (`sk-ant-oat-*`),
|
||||
OpenClaw skips the `context-1m-*` beta header because Anthropic currently
|
||||
|
||||
@@ -32,7 +32,7 @@ For a high-level overview, see [Onboarding (CLI)](/start/wizard).
|
||||
<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 OAuth/token profiles**: still honored at runtime if already configured, but onboarding/configure no longer offers Anthropic setup-token as a new setup path.
|
||||
- **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`.
|
||||
- Sets `agents.defaults.model` to `openai-codex/gpt-5.4` when model is unset or `openai/*`.
|
||||
|
||||
@@ -195,9 +195,9 @@ openclaw onboard --non-interactive \
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Anthropic setup-token is no longer offered as a new onboarding/configure path.
|
||||
Existing Anthropic OAuth/token profiles still run if they are already
|
||||
configured.
|
||||
Anthropic setup-token is available again as a legacy/manual onboarding path.
|
||||
Use it with the expectation that Anthropic told OpenClaw users the OpenClaw
|
||||
Claude-login path requires **Extra Usage**.
|
||||
|
||||
## Add another agent
|
||||
|
||||
|
||||
@@ -72,7 +72,7 @@ Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).
|
||||
For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
|
||||
In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
|
||||
In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
|
||||
For Anthropic, interactive onboarding/configure prefers **Anthropic Claude CLI** first, then **Anthropic API key**. Existing Anthropic OAuth/token profiles still run if already configured, but new setup is no longer offered through onboarding or auth commands.
|
||||
For Anthropic, interactive onboarding/configure prefers **Anthropic Claude CLI** first, then **Anthropic API key**. Anthropic setup-token is also available again as a legacy/manual OpenClaw path, with Anthropic's OpenClaw-specific **Extra Usage** billing expectation.
|
||||
2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
|
||||
3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
|
||||
In interactive token mode, choose default plaintext token storage or opt into SecretRef.
|
||||
|
||||
Reference in New Issue
Block a user