openclaw/docs/providers/anthropic.md

summary, read_when, title

summary	read_when	title
Use Anthropic Claude via API keys, setup-token, or Claude CLI in OpenClaw	You want to use Anthropic models in OpenClaw You want setup-token instead of API keys You want to reuse Claude CLI subscription auth on the gateway host	Anthropic

Anthropic (Claude)

Anthropic builds the Claude model family and provides access via an API. In OpenClaw you can authenticate with an API key or a setup-token.

Option A: Anthropic API key

Best for: standard API access and usage-based billing. Create your API key in the Anthropic Console.

CLI setup

openclaw onboard
# choose: Anthropic API key

# or non-interactive
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Claude CLI config snippet

{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

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:<level>) or in model params: agents.defaults.models["anthropic/<model>"].params.thinking.
• Related Anthropic docs:
  • Adaptive thinking
  • Extended thinking

Fast mode (Anthropic API)

OpenClaw's shared /fast toggle also supports direct Anthropic API-key traffic.

• /fast on maps to service_tier: "auto"
• /fast off maps to service_tier: "standard_only"
• Config default:

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

Important limits:

• This is API-key only. Anthropic setup-token / OAuth auth does not honor OpenClaw fast-mode tier injection.
• 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.
• 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 (Anthropic API)

OpenClaw supports Anthropic's prompt caching feature. This is API-only; subscription 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 (requires beta flag)

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

Defaults

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.

Per-agent cacheRetention overrides

Use model-level params as your baseline, then override specific agents via agents.list[].params.

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // baseline for most agents
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
    ],
  },
}

Config merge order for cache-related params:

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.

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.

Legacy parameter

The older cacheControlTtl parameter is still supported for backwards compatibility:

• "5m" maps to short
• "1h" maps to long

We recommend migrating to the new cacheRetention parameter.

OpenClaw includes the extended-cache-ttl-2025-04-11 beta flag for Anthropic API requests; keep it if you override provider headers (see /gateway/configuration).

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.

{
  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.

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 a subscription account 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 OAuth/subscription tokens (sk-ant-oat-*). OpenClaw automatically skips the context1m beta header for OAuth auth and keeps 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.

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 json ... on the gateway host.
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:

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

{
  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:

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

What you get

• Claude subscription auth reused from the local CLI
• Normal OpenClaw message/session routing
• Claude CLI session continuity across turns

Migrate from Anthropic auth to Claude CLI

If you currently use anthropic/... with a setup-token or API key and want to switch the same gateway host to Claude CLI:

openclaw models auth login --provider anthropic --method cli --set-default

Or in onboarding:

openclaw onboard --auth-choice anthropic-cli

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

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.
• Tools are disabled on the OpenClaw side for CLI backend runs.
• Text in, text out. No OpenClaw streaming handoff.
• Best fit for a personal gateway host, not shared multi-user billing setups.

More details: /gateway/cli-backends

Option C: Claude setup-token

Best for: using your Claude subscription.

Where to get a setup-token

Setup-tokens are created by the Claude Code CLI, not the Anthropic Console. You can run this on any machine:

claude setup-token

Paste the token into OpenClaw (wizard: Anthropic token (paste setup-token)), or run it on the gateway host:

openclaw models auth setup-token --provider anthropic

If you generated the token on a different machine, paste it:

openclaw models auth paste-token --provider anthropic

CLI setup (setup-token)

# Paste a setup-token during setup
openclaw onboard --auth-choice setup-token

Config snippet (setup-token)

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Notes

• Generate the setup-token with claude setup-token and paste it, or run openclaw models auth setup-token on the gateway host.
• If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See /gateway/troubleshooting.
• Auth details + reuse rules are in /concepts/oauth.

Troubleshooting

401 errors / token suddenly invalid

• Claude subscription auth can expire or be revoked. Re-run claude setup-token and paste it into the gateway host.
• If the Claude CLI login lives on a different machine, use openclaw models auth paste-token --provider anthropic on the gateway host.

No API key found for provider "anthropic"

• Auth is per agent. New agents don’t inherit the main agent’s keys.
• Re-run onboarding for that agent, or paste a setup-token / API key on the gateway host, then verify with openclaw models status.

No credentials found for profile anthropic:default

• Run openclaw models status to see which auth profile is active.
• Re-run onboarding, or paste a setup-token / API key for that profile.

No available auth profile (all in cooldown/unavailable)

• Check openclaw models status --json for auth.unusableProfiles.
• Add another Anthropic profile or wait for cooldown.

More: /gateway/troubleshooting and /help/faq.