​

Anthropic (Claude)

​

Option A: Anthropic API key

​

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-6" } } },
}

​

Thinking defaults (Claude 4.6)

• Anthropic Claude 4.6 models default to adaptive thinking in OpenClaw when no explicit thinking level is set.
• Supported thinking levels: off, minimal, low, medium, high, xhigh, adaptive. xhigh is model-gated (OpenAI/Codex models only — not offered on Anthropic); adaptive lets the model decide per request.
• Thinking level resolution, highest priority first:
  1. Per-message directive: /think:<level>
  2. Per-model: agents.defaults.models["anthropic/<model>"].params.thinking
  3. Global default: agents.defaults.thinkingDefault (any provider)
  4. Built-in fallback: adaptive for Claude 4.6, low for other reasoning models, off otherwise
• Related Anthropic docs:
  • Adaptive thinking
  • Extended thinking

​

Prompt caching (Anthropic API)

​

Configuration

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

​

Defaults

​

Per-agent cacheRetention overrides

{
  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
    ],
  },
}

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

​

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

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

​

1M context window (Anthropic beta)

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

​

Option B: Direct OAuth token (ANTHROPIC_OAUTH_TOKEN)

export ANTHROPIC_OAUTH_TOKEN="sk-ant-oat-..."
openclaw gateway run

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

• This env var bypasses the auth-profiles.json store; no openclaw models auth commands are needed.
• openclaw models status shows this auth as OAuth (env).
• Prompt caching is API-only; ANTHROPIC_OAUTH_TOKEN uses OAuth auth, so prompt caching defaults to "none" (same behavior as a stored setup-token). Set cacheRetention explicitly if your account supports it.

​

Option C: Claude setup-token

​

Where to get a setup-token

claude setup-token

openclaw models auth setup-token --provider anthropic

openclaw models auth paste-token --provider anthropic

​

CLI setup (setup-token)

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

​

Config snippet (setup-token)

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

​

Notes

• Three auth options: API key (Option A), OAuth token env var (Option B / ANTHROPIC_OAUTH_TOKEN), or setup-token (Option C).
• 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#oauth-token-refresh-failed-anthropic-claude-subscription.
• Auth details + reuse rules are in /concepts/oauth.

​

Troubleshooting

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

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

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

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