openclaw/docs/providers/anthropic.md

summary, read_when, title

summary	read_when	title
Use Anthropic Claude via API keys or Claude CLI in OpenClaw	You want to use Anthropic models in OpenClaw	Anthropic

Anthropic builds the Claude model family. OpenClaw supports two auth routes:

• API key — direct Anthropic API access with usage-based billing (anthropic/* models)
• Claude CLI — reuse an existing Claude Code login on the same host

OpenClaw's Claude CLI backend runs the installed Claude Code CLI in non-interactive print mode. Anthropic's current Claude Code docs describe `claude -p` as Agent SDK/programmatic usage. Anthropic's June 15, 2026 support update paused the announced Agent SDK billing change. For now, Anthropic says Claude Agent SDK, `claude -p`, and third-party app usage still draw from a subscription's usage limits. The previously announced monthly Agent SDK credit is not available while Anthropic revises that plan.

Interactive Claude Code still draws from the signed-in Claude plan limits. API key auth remains direct pay-as-you-go API billing. For long-lived gateway hosts, shared automation, and predictable production spend, use an Anthropic API key.

Check Anthropic's current support articles before relying on subscription billing behavior:

• Claude Code CLI reference
• Use the Claude Agent SDK with your Claude plan
• Use Claude Code with your Pro or Max plan
• Use Claude Code with your Team or Enterprise plan
• Manage Claude Code costs

Getting started

**Best for:** standard API access and usage-based billing.

<Steps>
  <Step title="Get your API key">
    Create an API key in the [Anthropic Console](https://console.anthropic.com/).
  </Step>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard
    # choose: Anthropic API key
    ```

    Or pass the key directly:

    ```bash
    openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
    ```
  </Step>
  <Step title="Verify the model is available">
    ```bash
    openclaw models list --provider anthropic
    ```
  </Step>
</Steps>

### Config example

```json5
{
  env: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-8" } } },
}
```

**Best for:** reusing an existing Claude CLI login without a separate API key.

<Steps>
  <Step title="Ensure Claude CLI is installed and logged in">
    Verify with:

    ```bash
    claude --version
    ```
  </Step>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard
    # choose: Claude CLI
    ```

    OpenClaw detects and reuses the existing Claude CLI credentials.
  </Step>
  <Step title="Verify the model is available">
    ```bash
    openclaw models list --provider anthropic
    ```
  </Step>
</Steps>

<Note>
Setup and runtime details for the Claude CLI backend are in [CLI Backends](/gateway/cli-backends).
</Note>

<Warning>
Claude CLI reuse expects the OpenClaw process to run on the same host as the
Claude CLI login. Docker installs can persist a container home and log in to
Claude Code there; see
[Claude CLI backend in Docker](/install/docker#claude-cli-backend-in-docker).
Other container installs such as [Podman](/install/podman) do not mount host
`~/.claude` into setup or runtime; use an Anthropic API key there, or choose
a provider with OpenClaw-managed OAuth such as
[OpenAI Codex](/providers/openai).
</Warning>

### Config example

Prefer the canonical Anthropic model ref plus a CLI runtime override:

```json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-8" },
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}
```

Legacy `claude-cli/claude-opus-4-7` model refs still work for
compatibility, but new config should keep provider/model selection as
`anthropic/*` and put the execution backend in provider/model runtime policy.

### Billing and `claude -p`

OpenClaw uses Claude Code's non-interactive `claude -p` path for Claude CLI
runs. Anthropic currently treats that path as Agent SDK/programmatic usage:

- Anthropic's June 15, 2026 support update paused the previously announced
  separate Agent SDK credit plan.
- For now, subscription-plan Claude Agent SDK, `claude -p`, and third-party
  app usage still draw from the signed-in subscription's usage limits.
- The previously announced monthly Agent SDK credit is not available while
  Anthropic revises that plan.
- Console/API-key logins use pay-as-you-go API billing and do not receive
  the subscription Agent SDK credit.

See Anthropic's [Agent SDK plan
article](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan)
for the pause notice, and the Claude Code plan articles for
[Pro/Max](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan)
and
[Team/Enterprise](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)
subscription behavior.

Anthropic can change Claude Code billing and rate-limit behavior without an
OpenClaw release. Check `claude auth status`, `/status`, and
Anthropic's linked docs when billing predictability matters.

<Tip>
For shared production automation, use an Anthropic API key instead of
Claude CLI. OpenClaw also supports subscription-style options from
[OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen),
[MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/zai).
</Tip>

Thinking defaults (Claude Fable 5, 4.8, and 4.6)

anthropic/claude-fable-5 always uses adaptive thinking and defaults to high effort. Because Anthropic does not allow thinking to be disabled for this model, /think off and /think minimal use low effort. OpenClaw also omits custom temperature values for Fable 5 requests.

Claude Opus 4.8 keeps thinking off by default in OpenClaw. When you explicitly enable adaptive thinking with /think high|xhigh|max, OpenClaw sends Anthropic's Opus 4.8 effort values; Claude 4.6 models default to adaptive.

Override per-message with /think:<level> or in model params:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-8": {
          params: { thinking: "high" },
        },
      },
    },
  },
}

Related Anthropic docs: - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) - [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)

Safety refusal fallback (Claude Fable 5)

Using Claude Fable 5 means also using Claude Opus 4.8. Fable 5 ships with safety classifiers that can decline a request, and Anthropic's sanctioned recovery is to have `claude-opus-4-8` serve that turn. OpenClaw opts into this automatically for direct API-key requests, so some Fable turns are answered and billed as Claude Opus 4.8. If your policy or budget cannot accept Opus-served turns, do not select `anthropic/claude-fable-5`.

Why this exists

Fable 5 classifiers return stop_reason: "refusal" on requests in restricted domains, and they also false-positive on benign-adjacent work (security tooling, life sciences, or even asking the model to reproduce its raw reasoning). Without a fallback, the turn dies with an error even though another Claude model would happily serve it — Anthropic's own refusal message tells API integrators to configure a fallback model.

How it works

1. For every direct API-key request to anthropic/claude-fable-5, OpenClaw sends Anthropic's server-side fallback opt-in: the server-side-fallback-2026-06-01 beta header plus fallbacks: [{"model": "claude-opus-4-8"}]. Claude Opus 4.8 is the only fallback target Anthropic permits for Fable 5.
2. Only a safety-classifier decline triggers the fallback. Rate limits, overloads, and server errors behave exactly as before and go through OpenClaw's normal model failover.
3. The rescue happens inside the same call. A decline before any output is invisible apart from latency; the whole answer comes from Opus 4.8. On a mid-stream decline the partial text is kept as the prefix the fallback model continues from, while the declined model's reasoning and tool calls are discarded per Anthropic's replay rules (they must not be echoed back or executed).
4. If Claude Opus 4.8 declines as well, the turn surfaces the refusal as an error, exactly like before this feature.

The fallback happens at the Anthropic API level, so claude-opus-4-8 does not need to be in your configured model list or fallback chain — a Fable-capable API key can always serve Opus.

Observability and billing

• A fallback-served turn records a provider_fallback diagnostic on the assistant message naming fromModel and toModel, and the message's responseModel reports claude-opus-4-8.
• Anthropic bills per attempt: a decline before output is free, and the rescue bills at Claude Opus 4.8 rates (currently half of Fable 5 rates). OpenClaw's per-turn cost estimate prices fallback-served turns at Opus rates to match.
• A mid-stream decline additionally bills the already-streamed Fable partial on Anthropic's side; that portion is reported in the API's per-attempt usage but not folded into OpenClaw's per-turn estimate.

Scope

Applies to anthropic/claude-fable-5 with API-key auth against api.anthropic.com. OAuth (Claude CLI subscription reuse), proxy base URLs, Bedrock, Vertex, and Foundry requests are unchanged and still surface refusals as errors there.

Verified live: a benign prompt asking Fable 5 to reproduce its raw chain of thought is declined with category: "reasoning_extraction" when sent without fallbacks, and the same prompt through OpenClaw returns a normal Opus-served answer with the provider_fallback diagnostic attached.

See Anthropic's refusals and fallback guide for the underlying behavior.

Prompt caching

OpenClaw supports Anthropic's prompt caching feature for API-key auth.

Value	Cache duration	Description
"short" (default)	5 minutes	Applied automatically for API-key auth
"long"	1 hour	Extended cache
"none"	No caching	Disable prompt caching

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

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

```json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } },
    ],
  },
}
```

Config merge order:

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 for bursty/low-reuse traffic.

- 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. - API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock refs when no explicit value is set.

Advanced configuration

OpenClaw's shared `/fast` toggle supports direct Anthropic traffic (API-key and OAuth to `api.anthropic.com`).

| Command | Maps to |
|---------|---------|
| `/fast on` | `service_tier: "auto"` |
| `/fast off` | `service_tier: "standard_only"` |

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

<Note>
- Only injected for direct `api.anthropic.com` requests. Proxy routes leave `service_tier` untouched.
- Explicit `serviceTier` or `service_tier` params override `/fast` when both are set.
- On accounts without Priority Tier capacity, `service_tier: "auto"` may resolve to `standard`.

</Note>

The bundled Anthropic plugin registers image and PDF understanding. OpenClaw auto-resolves media capabilities from the configured Anthropic auth — no additional config is needed.

| Property        | Value                 |
| --------------- | --------------------- |
| Default model   | `claude-opus-4-8`     |
| Supported input | Images, PDF documents |

When an image or PDF is attached to a conversation, OpenClaw automatically
routes it through the Anthropic media understanding provider.

Anthropic's 1M context window is available on GA-capable Claude 4.x models such as Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. OpenClaw sizes those models at 1M automatically:

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {},
      },
    },
  },
}
```

Older configs can keep `params.context1m: true`, but OpenClaw no longer sends
the retired `context-1m-2025-08-07` beta header. Older `anthropicBeta` config
entries with that value are ignored during request header resolution and
unsupported older Claude models stay on their normal context window.

`params.context1m: true` also applies to the Claude CLI backend
(`claude-cli/*`) for eligible GA-capable Opus and Sonnet models, preserving
the runtime context window for those CLI sessions to match the direct-API
behavior.

<Warning>
Requires long-context access on your Anthropic credential. OAuth/subscription token auth keeps its required Anthropic beta headers, but OpenClaw strips the retired 1M beta header if it remains in older config.
</Warning>

`anthropic/claude-opus-4-8` and its `claude-cli` variant have a 1M context window by default — no `params.context1m: true` needed.

Troubleshooting

Anthropic token auth expires and can be revoked. For new setups, use an Anthropic API key instead. Anthropic auth is **per agent** — new agents do not inherit the main agent's keys. Re-run onboarding for that agent (or configure an 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 configure an API key for that profile path. Check `openclaw models status --json` for `auth.unusableProfiles`. Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic model may still be usable. Add another Anthropic profile or wait for cooldown. More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).

Related

Choosing providers, model refs, and failover behavior. Claude CLI backend setup and runtime details. How prompt caching works across providers. Auth details and credential reuse rules.