Anthropic
Use Anthropic Claude in OpenClaw: supports API keys or setup-token auth.
Anthropic builds the Claude model family and provides access via API. In OpenClaw, you can authenticate with an API Key or setup-token.
Option A: Anthropic API Key
Best for: Standard API access and pay-as-you-go billing.
Create an API Key in the Anthropic Console.
#
CLI Setup
openclaw onboard 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. Note: this feature only works with API Key auth; subscription auth does not apply caching configuration.
#
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 caching (requires beta flag) |
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-5": {
params: { cacheRetention: "long" },
},
},
},
},
}#
Default Behavior
When using Anthropic API Key auth, OpenClaw automatically applies ''cacheRetention: "short"'' (5-minute caching) to all Anthropic models. You can explicitly set ''cacheRetention'' in your config to override.
#
Legacy Parameters (Compatibility)
The legacy ''cacheControlTtl'' is still preserved for compatibility with historical configs:
- ''"5m"'' maps to ''short''
- ''"1h"'' maps to ''long''
Recommend migrating to the new ''cacheRetention'' parameter.
OpenClaw includes the ''extended-cache-ttl-2025-04-11'' beta flag in Anthropic API requests; if you override provider headers, please preserve this flag (see ''/gateway/configuration'').
Option B: Claude setup-token
Best for: Using your Claude subscription.
#
How to get a setup-token
The setup-token is generated by the Claude Code CLI, not created in 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 on the gateway host:
openclaw models auth setup-token --provider anthropic
If the token was generated on a different machine, paste it on the gateway host:
openclaw models auth paste-token --provider anthropic
#
CLI Setup
openclaw onboard --auth-choice setup-token
#
Config Snippet
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}Notes
- Generate and paste with ''claude setup-token'', or run ''openclaw models auth setup-token'' on the gateway host.
- If you see "OAuth token refresh failed …" on your Claude subscription, re-authenticate with setup-token. See ''/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription''.
- See ''/concepts/oauth'' for auth details and reuse rules.
Troubleshooting
401 / token suddenly invalid
- Claude subscription auth may have expired or been revoked. Re-run ''claude setup-token'' and paste on the ''gateway host''.
- If Claude CLI login is 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 stored per agent. New agents don't inherit the primary agent's key.
- Re-run onboarding for that agent, or paste 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 the auth profile currently in use.
- Re-run onboarding, or paste setup-token / API key for that profile.
No available auth profile (all in cooldown/unavailable)
- Run ''openclaw models status --json'' to see ''auth.unusableProfiles''.
- Add another Anthropic profile or wait for cooldown to end.
More: ''/gateway/troubleshooting'' & ''/help/faq''.