Anthropic Provider: Authentication and Cost Tracking

Anthropic is the company behind the Claude model family. OpenClaw offers two ways to authenticate with it:

• API key - direct access to the Anthropic API, billed according to usage (anthropic/* models)
• Claude CLI - reuses an existing Claude Code login already present on the machine, via Anthropic's official Agent SDK

Usage and cost tracking

OpenClaw figures out which Anthropic credential is available and picks the matching usage surface:

• Credentials managed by OpenClaw for subscriptions or setup display quota windows and an optional budget for extra usage.
• Native Claude CLI logins remain entirely under Claude's refresh control, so OpenClaw never queries their quota endpoint.
• ANTHROPIC_ADMIN_KEY or ANTHROPIC_ADMIN_API_KEY presents 30 days of provider-reported organization cost and Messages API usage in the Control UI Usage section, with daily spend, token/cache totals, top models, and cost categories.
• A credential of type sk-ant-admin... stored in the Anthropic provider profile is automatically recognized as an Admin API key.

Cost history for the Admin API comes from Anthropic's Usage and Cost API. This reflects actual provider billing, not the estimated cost OpenClaw derives from sessions.

Warning

Claude Code retains ownership of its existing login and subscription; OpenClaw neither stores nor refreshes that login. Usage via the Agent SDK and claude -p currently counts against the limits of the signed-in subscription. API-key auth operates on separate pay-as-you-go billing and suits shared automation or predictable production spending better.

Anthropic's current support articles can alter this behavior without a new OpenClaw release:

• Claude Code CLI reference
• Use the Claude Agent SDK with your Claude plan
• Use Claude Code with your Pro or Max plan
• Use Claude Code with your Team or Enterprise plan
• Manage Claude Code costs

Getting started

API key

Best for: standard API access with usage-based billing.

Get your API key

Generate an API key inside the Anthropic Console.

Run onboarding

openclaw onboard
# choose: Anthropic API key

Alternatively, supply the key directly:

openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Verify the model is available

openclaw models list --provider anthropic

Config example

{
  env: { vars: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" } },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } },
}

Claude CLI

Best for: reusing a current Claude CLI login without needing a separate API key.

Ensure Claude CLI is installed and logged in

OpenClaw launches the installed Claude Code executable through Anthropic's official Agent SDK. Confirm that Claude Code is present and current:

claude --version
claude auth status --text

When Claude has no active login, authenticate once as the Gateway user:

claude auth login

If the installed build won't work, upgrade Claude Code and restart OpenClaw so the gateway picks up the new binary:

claude update

Run onboarding

openclaw onboard
# choose: Claude CLI

Regular agent turns go through the official Agent SDK with the installed, authenticated Claude Code executable. OpenClaw applies a non-secret route marker and never reads, stores, refreshes, selects, or forwards the native login tokens. Claude manages its own login and token refresh cycle. Explicitly chosen API-key or token credentials still rely on protected file-descriptor forwarding. Approvals for native tools remain under OpenClaw control. Schema-valid native calls pass through OpenClaw's canonical tool policy before native approval. Isolated side-question completions and paired-node execution keep the supervised CLI path.

Consecutive agent turns share the same warm Agent SDK query and Claude Code subprocess when their authenticated session and execution policy align. If that process terminates or the gateway restarts, the next turn resumes the persisted Claude Code session.

Verify the model is available

openclaw models list --provider anthropic

Note

Setup and runtime details for the Claude CLI backend live in CLI Backends.

Warning

Reusing the Claude CLI assumes the OpenClaw process shares a host with the Claude CLI login. Docker installs can persist a container home and log in to Claude Code there; see Claude CLI backend in Docker. Other container setups such as Podman do not mount host ~/.claude into setup or runtime; use an Anthropic API key there, or pick a provider with OpenClaw-managed OAuth like OpenAI Codex.

Get a setup token

Run claude setup-token on any machine that has Claude Code installed. It outputs a long-lived token beginning with sk-ant-oat01-.

During onboarding, paste the token into the macOS app by selecting Anthropic setup-token under Connect with an API key or token, or run:

openclaw models auth login --provider anthropic --method setup-token

Config example

Prefer the canonical Anthropic model ref with a CLI runtime override:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5" },
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Legacy claude-cli/claude-opus-4-7 model refs remain functional for compatibility, but new config should keep provider/model selection as anthropic/* and place the execution backend in provider/model runtime policy.

Billing and claude -p

Anthropic currently classifies Agent SDK and non-interactive CLI invocations as programmatic usage:

• Anthropic's June 15, 2026 support update halted the previously announced separate Agent SDK credit plan.
• Subscription-plan Claude Agent SDK, claude -p, and third-party app usage still draw from the signed-in subscription's usage limits.
• The previously announced monthly Agent SDK credit is unavailable while Anthropic reworks that plan.
• Console/API-key logins use pay-as-you-go API billing and get no subscription Agent SDK credit.

Anthropic may change Claude Code billing and rate-limit behavior without an OpenClaw release. Check claude auth status, /status, and Anthropic's linked docs when billing predictability matters.

Tip

For shared production automation, prefer an Anthropic API key over Claude CLI. OpenClaw also offers subscription-style options from OpenAI Codex, Qwen Cloud, MiniMax, and Z.AI / GLM.

Claude sessions across computers

The bundled Anthropic plugin adds a Claude Code group to the normal sessions sidebar. Rows open in the normal Chat pane. It finds non-archived Claude Code sessions on the Gateway and on connected node hosts:

• Claude CLI sessions come from valid project-index records. For unindexed transcripts, a bounded metadata fallback recognizes concurrent non-sidechain interactive (cli) and headless Agent SDK CLI (sdk-cli) sessions under ~/.claude/projects/.
• Claude Desktop sessions use the Desktop title, activity time, and archive state when its metadata points to the same Claude Code session ID.
• A CLI-only session has no archive flag, so it stays visible while its transcript is present.

Claude Code /rename titles override automatic titles and the first prompt. /color imports the matching session color; cleared or unrecognized colors remain unset. Discovery reads a bounded transcript prefix and tail, so recent metadata appended to large transcripts is included without reading the entire history. Metadata outside those windows may be unavailable. Desktop rows keep their Desktop title and stay colorless.

Discovery needs no extra OpenClaw config. The Anthropic plugin is bundled and enabled by default; a native macOS node advertises the read-only Claude session commands when the local ~/.claude/projects/ directory exists. Approve the node pairing upgrade when those commands first appear.

The sidebar groups rows by their Gateway or paired-node host and shows each host's newest bounded page as soon as that computer responds. It reconciles again after host-connectivity changes, when the page regains focus, and at most every 30 seconds while visible, so Claude sessions created outside OpenClaw appear without a reload. A changed catalog gets a faster follow-up pass. Use Load more sessions below a catalog group to append the next page for every host that has more history; appended rows stay visible and are re-fetched to the same depth across refreshes. Catalog clients use sessions.catalog.list; opening a row uses sessions.catalog.read.

Catalog visibility follows the authenticated Gateway profile. Admin connections see every discovered Claude row, and solo or shared-secret Gateways remain unfiltered. On a multi-user Gateway, a non-admin sees only rows already adopted by their durable profile; unattributed host-discovered Claude CLI and Desktop rows stay hidden. This is a privacy control within one trusted Gateway domain; see Multi-user mode.

Terminal takeover resolves claude from the owning host user's login-shell PATH before the service/daemon PATH. This keeps app-launched sessions aligned with the Claude CLI the operator gets in a normal terminal.

Selecting a row reads the newest transcript page first. Load older transcript items follows an opaque byte cursor and reads another bounded section from the JSONL file instead of loading the entire history. Normal user, assistant, reasoning, tool-call, and tool-result content is preserved. An individual item larger than the node/Gateway safety ceiling is clearly marked as truncated.

For a Gateway-local claude-cli row, typing in the normal composer calls sessions.catalog.continue. OpenClaw re-resolves the local catalog record, creates or reuses a model-locked native session, imports at most 200 visible items or 512 KiB, and seeds the Claude CLI binding. The first turn resumes with --fork-session; Claude assigns the fork a new session ID, so later turns use the fork and the source session stays untouched.

The new OpenClaw session starts with the catalog title and color. Continuing an already adopted session preserves any title or color changes made in OpenClaw.

A headless node host can also make its Claude CLI rows continuable by enabling the node-local setting below and restarting the node host:

{
  nodeHost: {
    agentRuns: {
      claude: { enabled: true },
    },
  },
}

The node advertises agent.cli.claude.run.v1 only when the setting is enabled and its local claude executable resolves. OpenClaw re-resolves the catalog record on that node, imports the same bounded history, and binds the adopted session to the node and catalog-reported working directory. Each turn runs the node's real claude -p process using that node's Claude files and login. The node's exec approval policy still applies; the Gateway cannot force the opt-in.

Node continuation v1 is one-shot only. It omits Gateway loopback MCP config and Gateway skills plugin arguments, does not reseed from a Gateway transcript, and rejects attachments and images. Claude Desktop rows remain view-only. Native macOS app nodes also remain view-only until the app advertises the run command.

Note

Paired-node Claude sessions remain read-only unless the headless node explicitly advertises agent.cli.claude.run.v1. OpenClaw never modifies Claude Desktop metadata or archives Claude sessions. Catalog list and read use operator.read, while continuation uses operator.write. Paired-node command advertisement and Gateway node policy remain additional requirements for node-backed rows.

See Nodes: Claude sessions and transcripts for the node command and security boundary.

Live model discovery

With an Anthropic API key configured, OpenClaw refreshes the Claude catalog from Anthropic's models endpoint, so newly published snapshots of supported model families appear without an OpenClaw release. Models the shipped catalog already describes always keep their published metadata and pricing.

A newly discovered model is only offered when Anthropic's advertised capabilities match the request shaping OpenClaw would apply to it. A brand-new model generation therefore stays hidden until OpenClaw adds support for it, rather than appearing in the picker and failing every request. Discovery is advisory: without an API key, or if the endpoint is unreachable, the shipped catalog is used unchanged.

Thinking defaults (Claude Opus 5, Sonnet 5, Mythos 5, Fable 5, 4.8, and 4.6)

Bare family aliases are rolling: opus tracks the current supported Claude Opus generation and today resolves to anthropic/claude-opus-5, the same way sonnet tracks the current Sonnet. Upgrading OpenClaw can therefore move a config that says opus onto a newer model generation. Pin a version to opt out, versioned aliases such as opus-4.8 keep resolving to their own model, and configs that already name claude-opus-4-8 are never rewritten.

anthropic/claude-opus-5 uses adaptive thinking at high effort by default. Use /think off to disable thinking, or /think xhigh|max for the model's higher native effort levels. OpenClaw omits manual thinking budgets, custom sampling parameters, assistant prefills, and Priority Tier for Opus 5 because Anthropic does not support those request features on this model. The catalog publishes its 1,000,000-token context window, 128,000-token output limit, image input, and $5/$25 input/output pricing.

anthropic/claude-sonnet-5 uses the same adaptive-thinking defaults and request restrictions. The catalog uses Anthropic's introductory $2/$10 input/output pricing through August 31, 2026; standard $3/$15 pricing begins September 1, 2026.

anthropic/claude-fable-5 always uses adaptive thinking and defaults to high effort. Anthropic does not allow thinking to be disabled for this model, so /think off and /think minimal map to low effort instead. OpenClaw also omits custom temperature values for Fable 5 requests, since Anthropic rejects a temperature override on any thinking-enabled request.

anthropic/claude-mythos-5 is a limited-access model with the same always-on adaptive-thinking contract. OpenClaw defaults to high, maps /think off and /think minimal to low, and omits caller-selected sampling parameters. The catalog publishes its 1,000,000-token context window, 128,000-token output limit, image input, and $10/$50 input/output pricing.

Claude Opus 4.8 keeps thinking off by default in OpenClaw. When you explicitly enable adaptive thinking with /think high|xhigh|max, OpenClaw sends Anthropic's Opus 4.8 effort values; Claude 4.6 models (Opus 4.6 and Sonnet 4.6) default to adaptive.

Override per-message with /think:<level> or in model params:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {
          params: { thinking: "high" },
        },
      },
    },
  },
}

Note

Related Anthropic docs:

• Adaptive thinking
• Extended thinking

Safety refusal fallback (Claude Opus 5 and Fable 5)

Warning

Claude Opus 5 and Fable 5 can route a safety-classifier refusal to another Claude model. OpenClaw opts into Anthropic's recommended per-category routing for direct API-key requests. A fallback-served turn is billed at the model that answered. If your policy requires every turn to stay on the requested model, do not use these models through the automatic fallback path.

Why this exists

Opus 5 and Fable 5 classifiers return stop_reason: "refusal" on requests in restricted domains. Without a fallback, the turn ends with an error even when Anthropic has a recommended model for that refusal category.

How it works

1. For every direct API-key request to anthropic/claude-opus-5 or anthropic/claude-fable-5, OpenClaw sends the server-side-fallback-2026-07-01 beta header plus fallbacks: "default". Anthropic selects the recommended model for the reported refusal category.
2. Only a safety-classifier decline triggers the fallback. Rate limits, overloads, and server errors behave exactly as before and go through OpenClaw's normal model failover.
3. The rescue happens inside the same call. A decline before any output is invisible apart from latency; the whole answer comes from the serving model. On a mid-stream decline the partial text is kept as the prefix the fallback model continues from, while the declined model's reasoning and tool calls are discarded per Anthropic's replay rules (they must not be echoed back or executed).
4. If the recommended model declines as well, the turn surfaces the refusal as an error.

The fallback happens at the Anthropic API level, so the serving model does not need to be in your configured OpenClaw fallback chain.

Observability and billing

• A fallback-served turn records a provider_fallback diagnostic on the assistant message naming fromModel and toModel, and the message's responseModel reports the model that answered.
• Anthropic bills the fallback attempt at the serving model's rates. OpenClaw prices known Opus 4.8 fallback-served turns at Opus 4.8 rates.
• A mid-stream decline additionally bills the already-streamed primary-model partial on Anthropic's side; that portion is reported in the API's per-attempt usage but not folded into OpenClaw's per-turn estimate.

Scope

This applies to anthropic/claude-opus-5 and anthropic/claude-fable-5 when using API-key authentication against api.anthropic.com. OAuth setups (including Claude CLI subscription reuse), proxy base URLs, Bedrock, Vertex, and Foundry requests remain unaffected, and refusals there still surface as errors.

For the underlying behavior, refer to Anthropic's refusals and fallback guide.

Prompt caching

Prompt caching from Anthropic is supported by OpenClaw for API-key authentication.

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

Per-agent cache overrides

Start with model-level parameters as your baseline, then use agents.entries.*.params to override individual agents:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
    entries: {
      research: { default: true },
      alerts: { params: { cacheRetention: "none" } },
    },
  },
}

Config merge order:

1. agents.defaults.models["provider/model"].params
2. agents.entries.*.params (matching id, overrides by key)

This setup allows one agent to maintain a long-lived cache while another agent on the same model turns off caching for bursty or low-reuse traffic.

Bedrock Claude notes

• When configured, amazon-bedrock/*anthropic.claude* Bedrock Claude models accept cacheRetention pass-through.
• Non-Anthropic Bedrock models are forced to cacheRetention: "none" at runtime.
• For Claude-on-Bedrock refs without an explicit value, API-key smart defaults also seed cacheRetention: "short".

Advanced configuration

Fast mode

For Claude Opus 5 and Opus 4.8, OpenClaw's shared /fast toggle leverages Anthropic's native fast mode for direct API-key traffic to api.anthropic.com.

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {
          params: { fastMode: true },
        },
      },
    },
  },
}

Note

• Native fast mode is a research preview for Claude Opus 5 and Opus 4.8. It can deliver up to 2.5x higher output-token throughput and is billed at $10/$50 per million input/output tokens. OpenClaw applies the same 2x multiplier to cache pricing in its cost estimate.
• Native fast mode only applies to direct api.anthropic.com requests made with an API key. OAuth/subscription-token requests, Claude CLI, proxies, Bedrock, Vertex, and Foundry never receive the beta or speed field.
• Accounts need fast-mode access and a non-zero fast-mode rate limit. Anthropic returns a fast-specific 429 when the separate fast quota is exhausted or zero.
• For other direct Anthropic models, /fast retains the existing Priority Tier mapping: on uses service_tier: "auto" and off uses service_tier: "standard_only".
• Explicit serviceTier or service_tier params override /fast when both are set.
• Claude Sonnet 5 supports neither native fast mode nor Priority Tier, so OpenClaw omits both fields.

Server-side compaction

Anthropic server-side compaction is opt-in. For supported anthropic/* models using API-key auth directly against api.anthropic.com, enable it per model:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: { anthropicServerCompaction: true },
        },
      },
    },
  },
}

OpenClaw adds the compact-2026-01-12 beta header and sends an Anthropic context_management compaction edit. When compaction occurs, OpenClaw stores the newest summary as hidden provider replay state and sends it first on the next matching request. The full transcript remains local; only the outbound history before the checkpoint is omitted. If Anthropic rejects a stored checkpoint, that turn reports the provider error and the following turn falls back to full local history.

When anthropicCompactThreshold is omitted, OpenClaw uses max(50000, floor(contextWindow * 0.7)). To choose a different input-token trigger:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: {
            anthropicServerCompaction: true,
            anthropicCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Configured thresholds below 50000 are clamped to 50000.

Warning

Anthropic server-side compaction is a beta feature and OpenClaw never enables it automatically. It applies only to direct Anthropic API requests authenticated with an API key. OAuth/subscription tokens, Claude CLI, proxies, Bedrock, Vertex, and Foundry are excluded. OpenClaw does not send pause_after_compaction or custom compaction instructions.

See Anthropic's compaction guide.

Media understanding (image and PDF)

The bundled Anthropic plugin registers image and PDF understanding. OpenClaw auto-resolves media capabilities from the configured Anthropic auth; no additional config is needed.

When an image or PDF is attached to a conversation, OpenClaw automatically routes it through the Anthropic media understanding provider.

1M context window

Claude Opus 5, Sonnet 5, Mythos 5, and Fable 5 have an exact 1,000,000-token input window and support up to 128,000 output tokens. Anthropic's 1M context window is also GA on Claude 4.x models with adaptive thinking: Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. OpenClaw sizes these models automatically, no params.context1m needed:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {},
        "anthropic/claude-sonnet-5": {},
        "anthropic/claude-mythos-5": {},
        "anthropic/claude-opus-4-8": {},
      },
    },
  },
}

Older configurations can retain params.context1m: true; it functions as a harmless no-op for these models, and OpenClaw no longer transmits the deprecated context-1m-2025-08-07 beta header in any case. During request header resolution, older anthropicBeta config entries containing that value are discarded, and unsupported legacy Claude models continue using their standard context window.

The Claude CLI (claude-cli/*) maintains its own context allocation. For legacy models like Sonnet 4.6, API availability does not automatically trigger the CLI's extended context. OpenClaw relies on CLI-managed metadata and configured limits; an eligible [1m] model reference or params.context1m: true activates a 1M budget. Access to native extended context still hinges on the installed CLI and your account; refer to Claude Code extended context.

Warning

Your Anthropic credential must have long-context access enabled. OAuth and subscription token auth preserve the required Anthropic beta headers, but OpenClaw removes the obsolete 1M beta header if it persists in older configurations.

Claude Opus 5 1M context

anthropic/claude-opus-5 and its claude-cli counterpart default to a 1M context window; no params.context1m: true is required.

Troubleshooting

Claude CLI OAuth session expired or could not be refreshed

Execute these commands as the Gateway user on the Gateway host:

claude auth status --text
claude auth login
openclaw gateway restart

Claude Code manages its own login and refresh lifecycle; avoid copying an OAuth token into OpenClaw.

401 errors / token suddenly invalid

Anthropic token authentication can expire and be revoked. For fresh installations, prefer an Anthropic API key.

No API key found for provider "anthropic"

Anthropic authentication operates on a per agent basis; new agents do not inherit the main agent's credentials. Re-run onboarding for that agent (or set up an API key on the gateway host), then confirm with openclaw models status.

No credentials found for profile "anthropic:default"

Use openclaw models status to identify the active auth profile. Re-run onboarding, or set up an API key for that profile path.

No available auth profile (all in cooldown)

Inspect openclaw models status --json for auth.unusableProfiles. Anthropic rate-limit cooldowns may be scoped to specific models, so another Anthropic model could remain operational. Add an additional Anthropic profile or wait out the cooldown.

Note

Additional assistance: Troubleshooting and FAQ.

Related

• Model selection, Picking providers, model refs, and failover behavior.

• CLI backends, Claude CLI backend configuration and operational specifics.

• Prompt caching, How prompt caching functions across different providers.

• OAuth and auth, Authentication specifics and credential sharing rules.