diff --git a/docs/providers/anthropic.md b/docs/providers/anthropic.md index b109244b6df..e0866aebf53 100644 --- a/docs/providers/anthropic.md +++ b/docs/providers/anthropic.md @@ -7,83 +7,117 @@ title: "Anthropic" # Anthropic (Claude) -Anthropic builds the **Claude** model family and provides access via an API and -Claude CLI. In OpenClaw, Anthropic API keys and Claude CLI reuse are both -supported. Existing legacy Anthropic token profiles are still honored at -runtime if they are already configured. +Anthropic builds the **Claude** model family. OpenClaw supports two auth routes: + +- **API key** — direct Anthropic API access with usage-based billing (`anthropic/*` models) +- **Claude CLI** — reuse an existing Claude CLI login on the same host Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so -OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this -integration unless Anthropic publishes a new policy. +OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned unless +Anthropic publishes a new policy. For long-lived gateway hosts, Anthropic API keys are still the clearest and -most predictable production path. If you already use Claude CLI on the host, -OpenClaw can reuse that login directly. +most predictable production path. Anthropic's current public docs: - [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) - [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview) - - [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 the clearest billing path, use an Anthropic API key instead. -OpenClaw also supports other subscription-style options, including [OpenAI -Codex](/providers/openai), [Qwen Cloud Coding Plan](/providers/qwen), -[MiniMax Coding Plan](/providers/minimax), and [Z.AI / GLM Coding -Plan](/providers/glm). - +## Getting started -## Option A: Anthropic API key + + + **Best for:** standard API access and usage-based billing. -**Best for:** standard API access and usage-based billing. -Create your API key in the Anthropic Console. + + + Create an API key in the [Anthropic Console](https://console.anthropic.com/). + + + ```bash + openclaw onboard + # choose: Anthropic API key + ``` -### CLI setup + Or pass the key directly: -```bash -openclaw onboard -# choose: Anthropic API key + ```bash + openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" + ``` + + + ```bash + openclaw models list --provider anthropic + ``` + + -# or non-interactive -openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" -``` + ### Config example -### Anthropic config snippet + ```json5 + { + env: { ANTHROPIC_API_KEY: "sk-ant-..." }, + agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } }, + } + ``` -```json5 -{ - env: { ANTHROPIC_API_KEY: "sk-ant-..." }, - agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } }, -} -``` + + + + **Best for:** reusing an existing Claude CLI login without a separate API key. + + + + Verify with: + + ```bash + claude --version + ``` + + + ```bash + openclaw onboard + # choose: Claude CLI + ``` + + OpenClaw detects and reuses the existing Claude CLI credentials. + + + ```bash + openclaw models list --provider anthropic + ``` + + + + + Setup and runtime details for the Claude CLI backend are in [CLI Backends](/gateway/cli-backends). + + + + If you want the clearest billing path, use an Anthropic API key instead. OpenClaw also supports subscription-style options from [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/glm). + + + + ## Thinking defaults (Claude 4.6) -- Anthropic Claude 4.6 models default to `adaptive` thinking in OpenClaw when no explicit thinking level is set. -- You can override per-message (`/think:`) or in model params: - `agents.defaults.models["anthropic/"].params.thinking`. -- Related Anthropic docs: - - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) - - [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) +Claude 4.6 models default to `adaptive` thinking in OpenClaw when no explicit thinking level is set. -## Fast mode (Anthropic API) - -OpenClaw's shared `/fast` toggle also supports direct public Anthropic traffic, including API-key and OAuth-authenticated requests sent to `api.anthropic.com`. - -- `/fast on` maps to `service_tier: "auto"` -- `/fast off` maps to `service_tier: "standard_only"` -- Config default: +Override per-message with `/think:` or in model params: ```json5 { agents: { defaults: { models: { - "anthropic/claude-sonnet-4-6": { - params: { fastMode: true }, + "anthropic/claude-opus-4-6": { + params: { thinking: "adaptive" }, }, }, }, @@ -91,25 +125,21 @@ OpenClaw's shared `/fast` toggle also supports direct public Anthropic traffic, } ``` -Important limits: + +Related Anthropic docs: +- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) +- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) + -- OpenClaw only injects Anthropic service tiers for direct `api.anthropic.com` requests. If you route `anthropic/*` through a proxy or gateway, `/fast` leaves `service_tier` untouched. -- Explicit Anthropic `serviceTier` or `service_tier` model params override the `/fast` default when both are set. -- Anthropic reports the effective tier on the response under `usage.service_tier`. On accounts without Priority Tier capacity, `service_tier: "auto"` may still resolve to `standard`. +## Prompt caching -## Prompt caching (Anthropic API) +OpenClaw supports Anthropic's prompt caching feature for API-key auth. -OpenClaw supports Anthropic's prompt caching feature. This is **API-only**; legacy Anthropic token auth does not honor cache settings. - -### Configuration - -Use the `cacheRetention` parameter in your model config: - -| Value | Cache Duration | Description | -| ------- | -------------- | ------------------------ | -| `none` | No caching | Disable prompt caching | -| `short` | 5 minutes | Default for API Key auth | -| `long` | 1 hour | Extended cache | +| Value | Cache duration | Description | +| ------------------- | -------------- | -------------------------------------- | +| `"short"` (default) | 5 minutes | Applied automatically for API-key auth | +| `"long"` | 1 hour | Extended cache | +| `"none"` | No caching | Disable prompt caching | ```json5 { @@ -125,122 +155,141 @@ Use the `cacheRetention` parameter in your model config: } ``` -### Defaults + + + Use model-level params as your baseline, then override specific agents via `agents.list[].params`: -When using Anthropic API Key authentication, OpenClaw automatically applies `cacheRetention: "short"` (5-minute cache) for all Anthropic models. You can override this by explicitly setting `cacheRetention` in your config. + ```json5 + { + agents: { + defaults: { + model: { primary: "anthropic/claude-opus-4-6" }, + models: { + "anthropic/claude-opus-4-6": { + params: { cacheRetention: "long" }, + }, + }, + }, + list: [ + { id: "research", default: true }, + { id: "alerts", params: { cacheRetention: "none" } }, + ], + }, + } + ``` -### Per-agent cacheRetention overrides + Config merge order: -Use model-level params as your baseline, then override specific agents via `agents.list[].params`. + 1. `agents.defaults.models["provider/model"].params` + 2. `agents.list[].params` (matching `id`, overrides by key) -```json5 -{ - agents: { - defaults: { - model: { primary: "anthropic/claude-opus-4-6" }, - models: { - "anthropic/claude-opus-4-6": { - params: { cacheRetention: "long" }, // baseline for most agents + This lets one agent keep a long-lived cache while another agent on the same model disables caching for bursty/low-reuse traffic. + + + + + - Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured. + - Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime. + - API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock refs when no explicit value is set. + + + +## Advanced configuration + + + + OpenClaw's shared `/fast` toggle supports direct Anthropic traffic (API-key and OAuth to `api.anthropic.com`). + + | Command | Maps to | + |---------|---------| + | `/fast on` | `service_tier: "auto"` | + | `/fast off` | `service_tier: "standard_only"` | + + ```json5 + { + agents: { + defaults: { + models: { + "anthropic/claude-sonnet-4-6": { + params: { fastMode: true }, + }, + }, }, }, - }, - list: [ - { id: "research", default: true }, - { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only - ], - }, -} -``` + } + ``` -Config merge order for cache-related params: + + - Only injected for direct `api.anthropic.com` requests. Proxy routes leave `service_tier` untouched. + - Explicit `serviceTier` or `service_tier` params override `/fast` when both are set. + - On accounts without Priority Tier capacity, `service_tier: "auto"` may resolve to `standard`. + -1. `agents.defaults.models["provider/model"].params` -2. `agents.list[].params` (matching `id`, overrides by key) + -This lets one agent keep a long-lived cache while another agent on the same model disables caching to avoid write costs on bursty/low-reuse traffic. + + Anthropic's 1M context window is beta-gated. Enable it per model: -### Bedrock Claude notes - -- Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured. -- Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime. -- Anthropic API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock model refs when no explicit value is set. - -## 1M context window (Anthropic beta) - -Anthropic's 1M context window is beta-gated. In OpenClaw, enable it per model -with `params.context1m: true` for supported Opus/Sonnet models. - -```json5 -{ - agents: { - defaults: { - models: { - "anthropic/claude-opus-4-6": { - params: { context1m: true }, + ```json5 + { + agents: { + defaults: { + models: { + "anthropic/claude-opus-4-6": { + params: { context1m: true }, + }, + }, }, }, - }, - }, -} -``` + } + ``` -OpenClaw maps this to `anthropic-beta: context-1m-2025-08-07` on Anthropic -requests. + OpenClaw maps this to `anthropic-beta: context-1m-2025-08-07` on requests. -This only activates when `params.context1m` is explicitly set to `true` for -that model. + + Requires long-context access on your Anthropic credential. Legacy token auth (`sk-ant-oat-*`) is rejected for 1M context requests — OpenClaw logs a warning and falls back to the standard context window. + -Requirement: Anthropic must allow long-context usage on that credential. - -Note: Anthropic currently rejects `context-1m-*` beta requests when using -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. - -## Claude CLI backend - -The bundled Anthropic `claude-cli` backend is supported in OpenClaw. - -- Anthropic staff told us this usage is allowed again. -- OpenClaw therefore treats Claude CLI reuse and `claude -p` usage as - sanctioned for this integration unless Anthropic publishes a new policy. -- Anthropic API keys remain the clearest production path for always-on gateway - hosts and explicit server-side billing control. -- Setup and runtime details are in [/gateway/cli-backends](/gateway/cli-backends). - -## Notes - -- Anthropic's public Claude Code docs still document direct CLI usage such as - `claude -p`, and Anthropic staff told us OpenClaw-style Claude CLI usage is - allowed again. We are treating that guidance as settled unless Anthropic - publishes a new policy change. -- Anthropic setup-token remains available in OpenClaw as a supported token-auth path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available. -- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth). + + ## Troubleshooting -**401 errors / token suddenly invalid** + + + Anthropic token auth can expire or be revoked. For new setups, migrate to an Anthropic API key. + -- Anthropic token auth can expire or be revoked. -- For new setup, migrate to an Anthropic API key. + + Auth is **per agent**. New agents don't inherit the main agent's keys. Re-run onboarding for that agent, or configure an API key on the gateway host, then verify with `openclaw models status`. + -**No API key found for provider "anthropic"** + + Run `openclaw models status` to see which auth profile is active. Re-run onboarding, or configure an API key for that profile path. + -- Auth is **per agent**. New agents don’t inherit the main agent’s keys. -- Re-run onboarding for that agent, or configure an API key on the gateway - host, then verify with `openclaw models status`. + + Check `openclaw models status --json` for `auth.unusableProfiles`. Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic model may still be usable. Add another Anthropic profile or wait for cooldown. + + -**No credentials found for profile `anthropic:default`** + +More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq). + -- Run `openclaw models status` to see which auth profile is active. -- Re-run onboarding, or configure an API key for that profile path. +## Related -**No available auth profile (all in cooldown/unavailable)** - -- Check `openclaw models status --json` for `auth.unusableProfiles`. -- Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic - model may still be usable even when the current one is cooling down. -- Add another Anthropic profile or wait for cooldown. - -More: [/gateway/troubleshooting](/gateway/troubleshooting) and [/help/faq](/help/faq). + + + Choosing providers, model refs, and failover behavior. + + + Claude CLI backend setup and runtime details. + + + How prompt caching works across providers. + + + Auth details and credential reuse rules. + +