Skip to main content

​
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"

​
Config snippet

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

​
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:
ValueCache DurationDescription
noneNo cachingDisable prompt caching
short5 minutesDefault for API Key auth
long1 hourExtended cache (requires beta flag)
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": {
          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.

​
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).

​
Option B: 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

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

​
Config snippet

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

​
Notes

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