Connect Anthropic Claude to OpenClaw: API Setup Guide

Ever felt the frustration of getting a powerful model like Claude ready for your workflow, only to get stuck on authentication tokens or configuration flags? Setting up your environment shouldn’t feel like a chore. Whether you are looking for high-speed API access or want to use your existing Claude subscription, getting Anthropic’s models running in OpenClaw is straightforward once you know the paths available to you.

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

This is the best choice for standard API access and usage-based billing. You can 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 this per-message using /think:<level> or by adjusting your model parameters: agents.defaults.models["anthropic/<model>"].params.thinking.

For more context, check out these resources:

• Adaptive thinking
• Extended thinking

Fast mode (Anthropic API)

OpenClaw’s shared /fast toggle also supports direct public Anthropic traffic. This includes 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"
• The default configuration looks like this:

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

Keep these limits in mind:

• 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 (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.
• This ensures consistent behavior across different cloud providers.

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 subscription setup-tokens (sk-ant-oat-*). If you configure context1m: true with subscription auth, OpenClaw logs a warning and falls back to the standard context window by skipping the context1m beta header while keeping the required OAuth betas.

Option B: Claude CLI as the message provider

This is the best choice 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 must be installed on the gateway host.
• The binary must be available on your PATH or configured with an absolute command path.
• Claude CLI must be already authenticated on that same host.
• OpenClaw auto-loads the bundled Anthropic plugin at gateway startup when your config explicitly references claude-cli/... or claude-cli backend config.

claude auth status

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
• Direct local execution for your primary model

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

This is the best choice 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 and reuse rules are available in /concepts/oauth.
• Ensure your environment variables are correctly set before starting the gateway.

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.

Next Steps

• Learn more about Gateway Troubleshooting
• Check out the FAQ

Need more help? Talk to the AI Setup Assistant.