Anthropic Claude Provider Setup Guide

Anthropic develops the Claude model family. Two authentication paths are available in OpenClaw:

API key: access to the Anthropic API, billed by usage
Claude CLI: reuse a Claude Code login that already exists, by way of the executable installed on the same host

Choose a model route

Every Claude model appears once per route in the model picker. API and Claude CLI are not interchangeable billing options: anthropic/* is the standard model identity and can run on either runtime, while claude-cli/* explicitly picks the native Claude runtime. If a configured anthropic/* model already runs through Claude CLI, the picker leaves out its matching claude-cli/* entry, unless the agent's model policy or a Gateway role permits that claude-cli/* entry but not the anthropic/* one.

API / API · OpenClaw relies on the Anthropic API connection you configured.
Claude CLI / Claude CLI · native runs through Claude Code, with its native login or a saved account you have chosen.
Configured route indicates the picker has no resolved runtime to display. The provider name on its own does not prove API or subscription billing. An Anthropic Default row carries this label too when it is about to clear a pinned session runtime: the current session route does not describe the configured route being restored.

Hovering or moving keyboard focus onto a model reveals route details in the web picker. Telegram /models displays route guidance before selection and labels models once their runtime is known. Model IDs and explicit runtime choices stay as they are.

Check the selected account, not just the runtime. An API key chosen explicitly for Claude CLI still bills through the API separately. A Claude CLI selection will not quietly fall back to the direct API when the executable cannot run.

Claude Haiku 5.5

Choose anthropic/claude-haiku-5-5 to use the API, or claude-cli/claude-haiku-5-5 to use an existing Claude Code login. Haiku 5.5 backs both the haiku alias and Anthropic's default utility model; references to Haiku 4.5 explicitly still work.

Text and image input are both accepted by Haiku 5.5, which has a 1M context window and allows up to 128K output tokens. Thinking is adaptive at medium effort by default. The levels offered are off, low, medium, high, xhigh, and max; minimal maps to low. Unsupported sampling parameters are dropped by OpenClaw, and signed thinking is kept for same-model replay. Native fast mode, Priority Tier, and server-side fallback are not enabled for this model.

For prompts up to 100K tokens, API pricing is $0.10 / $0.50 per million input / output tokens, rising to $0.50 / $2.50 beyond that threshold. Cache reads and writes follow the matching tier. Subscription accounting stays in place with Claude CLI. The new tokenizer and account-bound thinking requirements are covered in Anthropic's Haiku 5.5 migration guide.

Usage and cost tracking

OpenClaw identifies which Anthropic credential is present and picks the matching usage surface:

Credentials managed by OpenClaw for subscription/setup show quota windows plus an optional extra-usage budget.
Native Claude CLI logins remain under Claude's exclusive refresh control, so OpenClaw does not poll their quota endpoint.
ANTHROPIC_ADMIN_KEY or ANTHROPIC_ADMIN_API_KEY displays 30 days of provider-reported organization cost and Messages API usage in Control UI Usage, covering daily spend, token/cache totals, top models, and cost categories.
An sk-ant-admin... credential stored in the Anthropic provider profile is recognized automatically as an Admin API key.

Admin API cost history is sourced from Anthropic's Usage and Cost API. That figure is actual provider billing, distinct from the estimated cost OpenClaw derives from sessions.

Warning

Claude Code keeps ownership of its existing login and subscription; OpenClaw neither persists nor refreshes that login. Agent SDK and claude -p usage currently count against the limits of the signed-in subscription. Separate pay-as-you-go billing applies to API-key auth, which is the better fit for shared automation or predictable production spend.

Anthropic's current support articles may alter this behavior without an OpenClaw release:

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

API key

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

Get your API key

Generate an API key in the Anthropic Console.

Run onboarding

openclaw onboard
# choose: Anthropic API key

Alternatively, supply the key directly:

openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Verify the model is available

openclaw models list --provider anthropic

Config example

{
  env: { vars: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" } },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } },
}

Claude CLI

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

Install Claude CLI and log in

OpenClaw talks straight to the installed Claude Code executable. Confirm that Claude Code is installed and current:

claude --version
claude auth status --text

When Claude is not logged in, authenticate once as the Gateway user:

claude auth login

Should the installed build be incompatible, update Claude Code and restart OpenClaw so the gateway launches the new binary:

claude update

Run onboarding

openclaw onboard
# choose: Claude CLI

Ordinary agent turns go through OpenClaw's direct CLI transport to the installed, authenticated Claude Code executable. OpenClaw relies on a non-secret route marker and never reads, persists, refreshes, selects, or forwards the native login tokens. The login and token refresh lifecycle belong to Claude. At Gateway startup, the native login check is shared across agent workspaces that use the same config and environment. Checks use claude auth status --json; an explicit logged-out response blocks the native route, whereas a timeout or unreadable response lets Claude attempt the request. Captures expire after one minute. When a selected native login is unavailable, spawn admission rechecks it right away, so no Gateway restart is needed after signing in.

For native-login users, the model picker reads Claude Code's own model menu in the background, without sending a prompt or using an inference turn. Unique native model IDs appear as anthropic/<id> on the Claude CLI runtime, along with the effort levels Claude Code reports. Models that permit thinking to be disabled also offer /think off, separately from those effort levels. off is not offered for models with mandatory adaptive thinking. Account and organization restrictions therefore shape the menu. Metadata is added by the hosted OpenClaw catalog only to those exact IDs; it cannot add native models. New native models need no OpenClaw upgrade and no catalog edit.

Until the first discovery finishes, only models already configured or selected can be used through the native route. Pickers never wait on the subprocess. Configured and selected IDs that already exist stay listed and runnable, including older IDs missing from the menu; deprecated rows remain hidden. Request fresh discovery with openclaw models list --refresh --provider anthropic. API-only users, and users holding both API and native credentials, keep their existing API catalog behavior.

When a menu refresh fails temporarily, the picker retains the last accepted menu for the same authentication state. A successful refresh replaces that menu, including when access becomes more restrictive. Switching authentication discards the retained menu.

New sessions pick saved subscription credentials by account order and use protected file-descriptor forwarding, including tokens saved with openclaw models auth paste-token --provider anthropic. API keys saved for the anthropic provider need an explicit account selection before CLI forwarding. Saved subscription accounts also make configured Claude CLI models available in the picker without a native claude auth login; switching models keeps the configured Claude CLI runtime. Existing sessions hold onto their account until you pick another or delete its saved profile. Native-tool approvals stay under OpenClaw control. Schema-valid native calls pass through OpenClaw's shared tool policy before native approval. Isolated side-question completions and paired-node execution keep the supervised CLI path.

Consecutive agent turns reuse the same warm Claude Code subprocess when their authenticated session and execution policy match. Should that process end or the gateway restart, the next turn resumes the persisted Claude Code session.

An explicit Claude CLI model selection stays on that runtime across resumed turns. If the executable cannot run, the selection fails rather than switching to direct Anthropic API access. Choosing an API route, or forwarding an API key through an explicit account selection, remains a separate billing choice.

Verify the model is available

openclaw models list --provider anthropic

Note

The Claude CLI backend's setup and runtime details live in CLI Backends.

Warning

Reusing Claude CLI assumes the OpenClaw process runs on the same host where the Claude CLI login exists. Docker installs can persist a container home and sign in to Claude Code inside it; see Claude CLI backend in Docker. Other container installs, Podman among them, do not mount the host ~/.claude into setup or runtime. In that case use an Anthropic API key, or pick a provider whose OAuth OpenClaw manages, such as OpenAI Codex.

Get a setup token

On any machine with Claude Code installed, run claude setup-token. The output is a long-lived token that begins with sk-ant-oat01-.

To paste it during onboarding in the macOS app, pick Anthropic setup-token under Connect with an API key or token, or run:

openclaw models auth login --provider anthropic --method setup-token

Requests sent straight to the Messages API with a setup token declare a maintained Claude Code client version, or the installed CLI version if that one is newer. Anthropic relies on that identity to gate newer models. If the CLI check is missing, older, or fails, OpenClaw's maintained version floor applies. Discovery is shared with the CLI backend and cached until the process restarts; requests made with an API key skip the check.

Config example

The preferred approach is the standard Anthropic model ref combined with a CLI runtime override:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5" },
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Legacy claude-cli/claude-opus-4-7 model refs remain functional for compatibility, but new configs should keep provider/model selection as anthropic/* and place the execution backend in provider/model runtime policy.

Billing and `claude -p`

At present Anthropic counts Agent SDK and non-interactive CLI invocations as programmatic usage:

The June 15, 2026 support update from Anthropic paused the separate Agent SDK credit plan announced earlier.
Usage of the Claude Agent SDK under a subscription plan, claude -p, and third-party apps still draws on the signed-in subscription's usage limits.
While Anthropic revises that plan, the monthly Agent SDK credit announced earlier is not available.
Logins through Console/API keys are billed pay-as-you-go through the API and do not get the subscription Agent SDK credit.

Anthropic may alter Claude Code billing and rate-limit behavior without any OpenClaw release. Where billing predictability matters, consult claude auth status, /status, and the docs Anthropic links.

Tip

For shared production automation, reach for an Anthropic API key rather than Claude CLI. Subscription-style options from OpenAI Codex, Qwen Cloud, MiniMax, and Z.AI / GLM are also supported by OpenClaw.

Use Claude Opus 5.5

Once either auth route above is configured, pick the standard model ref:

openclaw models set anthropic/claude-opus-5-5

This model is selected by the bare opus alias and by the explicit aliases opus-5.5 / opus-5-5. New API and Claude CLI setups default to Opus 5.5; models already pinned to a version and authored aliases stay as they are.

With Claude CLI authentication, keep the standard ref and choose the CLI runtime:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5-5" },
      models: {
        "anthropic/claude-opus-5-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Both the API and Claude CLI catalogs expose a 1,000,000-token context window and a 128,000-token output limit. API pricing runs $4/$20 per million input/output tokens, with $0.20 for cache reads and $5 for five-minute cache writes. Consult Anthropic's Opus 5.5 specifications.

Adaptive thinking is always on for Opus 5.5. OpenClaw defaults to medium and offers low, medium, high, xhigh, and max. Stored off and minimal settings map to low; a stored adaptive falls back to the medium default. To lower thinking effort, use /think low. Manual thinking budgets, custom sampling parameters, assistant prefills, and Priority Tier are all omitted by OpenClaw.

Forced tool choices turn into auto; state in the prompt when a particular tool must run. Opus 5.5 also ties retained thinking to its conversation prefix. The append-only context and retained-thinking repair that OpenClaw applies is described under Tool calls and retained thinking. For model-switching and response-shape changes, see Anthropic's migration guide.

Use Claude Sonnet 5.5

Once either auth route above is configured, pick the standard model ref:

openclaw models set anthropic/claude-sonnet-5-5

This model is selected by the bare sonnet alias and by the explicit aliases sonnet-5.5 / sonnet-5-5. Fresh API and Claude CLI setups still default to Opus 5.5, so Sonnet 5.5 must be selected explicitly. Models already pinned to a version and authored aliases stay as they are. To keep Sonnet 5, use sonnet-5.

With Claude CLI authentication, keep the standard ref and choose the CLI runtime:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-5-5" },
      models: {
        "anthropic/claude-sonnet-5-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Both the API and Claude CLI catalogs expose a 1,000,000-token context window and a 128,000-token output limit. Image and PDF input are supported by Sonnet 5.5. API pricing runs $2/$10 per million input/output tokens, with $0.20 for cache reads and $2.50 for five-minute cache writes, matching Sonnet 5's rates. Consult Anthropic's Sonnet 5.5 specifications.

Sonnet 5.5 defaults to adaptive thinking at high effort. OpenClaw accepts off, low, medium, high, xhigh, and max. The /think off value passes Anthropic's between_tools setting: up-front thinking is turned off, yet notes exchanged between tool calls still come back as plain text. Any new /think minimal or /think adaptive directives are rejected, and the error lists the supported choices; a stored minimal is mapped to low, while a stored adaptive falls back to the high default. To get that default back, use /think default. Manual thinking budgets, custom sampling parameters, and assistant prefills are all omitted by OpenClaw. Neither native fast mode nor Priority Tier is available on Sonnet 5.5.

A forced tool choice is converted to auto, even when /think off is in play; if a specific tool has to run, say so in the prompt. Retained thinking on Sonnet 5.5 is tied to the conversation prefix. The append-only context handling and retained-thinking repair that OpenClaw performs are covered in Tool calls and retained thinking. When a session switches to Sonnet 5.5, reasoning from Sonnet 5 or Claude 4.x models carries over, but reasoning from Opus 5, Opus 5.5, Fable, or Mythos does not. No other model can read Sonnet 5.5 reasoning. Requests made directly with an API key can opt into Anthropic's safety fallback to Sonnet 5 when a request is declined for cyber or frontier_llm, and the price stays the same. Anthropic's migration guide documents model switching and the response-shape changes.

Use Claude Fable 5.1

Once either auth route above is configured, pick the standard model ref:

openclaw models set anthropic/claude-fable-5-1

When authenticating through Claude CLI, keep the same ref and choose the CLI runtime:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-fable-5-1" },
      models: {
        "anthropic/claude-fable-5-1": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Both the API and Claude CLI catalogs provide a 1,000,000-token context window and a 128,000-token output limit. Adaptive thinking is always on for Fable 5.1. OpenClaw starts at medium, and native low, medium, high, xhigh, and max effort levels are selectable. Under API-key billing, input and output stay at $10/$50 per million tokens; cache reads are billed at $0.25 per million tokens, a quarter of what Fable 5 charges. Anthropic's Fable 5.1 specifications has the details.

The bare fable alias now resolves to anthropic/claude-fable-5-1. Choosing fable-5 or anthropic/claude-fable-5 explicitly still lands on Fable 5; OpenClaw leaves those selections as they are rather than pointing them at Fable 5.1.

Tool calls and retained thinking

Tool use on Fable 5.1 can be automatic or disabled, but not forced. When thinking is on, OpenClaw's Anthropic adapter turns a forced tool choice into auto. If a particular tool must run, state that in the prompt; Anthropic's migration guide explains more.

On Fable 5.1, retained thinking is bound to the system prompt, tools, and conversation history that precede it. Altering that prefix can invalidate thinking blocks that come later. For direct Anthropic API-key Messages routes, OpenClaw turns on inHistorySystemUpdates for Opus 4.8, Opus 5/5.5, Sonnet 5/5.5, Fable 5/5.1, and Mythos 5/5.1. The full system prompt is pinned, and prompt sections that change, get added, or get removed are appended as system messages following the current user turn. As a result, workspace instructions, skills, and permission changes all leave the earlier prefix intact. A new prefix series begins whenever the provider, model, transport, or selected personal profile changes, or when the session is compacted. Following a Gateway restart, the stored series picks up where it left off and any refreshed sections arrive as appended updates. Changes to the dynamic suffix travel the same update path.

Runtime context on these routes is also kept append-only, as turn-scoped system messages with no user-message delimiters. OpenClaw sends clear_at: "next_user_message" together with the mid-conversation-system-clear-at-2026-08-21 beta: earlier carriers remain in the transcript, though they cost no input tokens once the next user message arrives. Persistent prompt updates require no beta header. For their user turn, operator system messages come after all other context, tool results included. If replay leaves out a Talk consult prompt, OpenClaw places a neutral user anchor (.) ahead of any stranded system updates. Content, order, and lifetime are preserved this way, and the pinned system prompt stays untouched. Turn-scoped messages are also cleared by tool results and queued extension context, so after those continuations OpenClaw renews the runtime context of the current user turn.

OAuth, proxies, Bedrock, Vertex, and Foundry behave as before. Models that bind the prefix, such as Fable 5.1, Opus 5.5, and Sonnet 5.5, keep hidden user-role runtime-context carriers plus inline inbound metadata, which preserves consecutive user turns on the Messages API; Bedrock Converse, by contrast, still merges consecutive user turns. Inside those carriers sits the delimited context body, with interpretation guidance appearing once in the stable system prompt. Routes that have neither capability keep transient carriers and merge user turns normally. Where thinking does not bind the prefix, transient carriers are the cheaper option on routes without in-history system updates: old carriers cost nothing in later context and avoid repeated cache-read charges.

Direct Anthropic API-key requests that use adaptive thinking send the thinking-binding-controls-2026-08-01 beta and thinking.block_binding.prefix_mismatch_behavior: "drop_block". Anthropic discards invalidated replayed thinking on the server, and OpenClaw writes a warning that gives the count and up to five affected paths. None of these controls are sent for OAuth, proxies, Bedrock, Vertex, Foundry, or for budget-based, disabled, or between_tools thinking. Client-side compaction strips stale thinking signatures; if a provider confirms a thinking rejection, one retry without prior thinking may still be attempted, and a successful repair is persisted. Adaptive mode stays on, though a response may come back with no thinking block at all. Integrations that construct Messages API requests themselves should follow Anthropic's preserved-thinking rules.

When contextPruning.mode: "cache-ttl" is set, direct Anthropic API-key requests use server-side tool-result clearing. Neither Anthropic's server-side clearing nor its compaction ever invalidates Fable 5.1 thinking: the prefix check runs against the history the client sent, before those server edits. Anthropic's context-editing contract has the details. On other eligible routes, a client-side prune counts as a one-time prefix edit. OpenClaw keeps that projection for subsequent requests, so pruning does not revert to the original bytes and invalidate freshly created thinking. Earlier thinking touched by a client-side edit is handled by drop_block wherever the binding controls above apply, or by the existing rejection-and-repair path in other cases.

Thinking on Fable 5.1 is bound to the model that generated it as well. If a session moves from Fable 5.1 to any other model (Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Fable 5, or older), the visible conversation continues without Fable's earlier reasoning; Anthropic drops those blocks without billing, and OpenClaw's embedded runtime leaves them out of the replay to achieve the same outcome. Going the other direction keeps compatible reasoning: Fable 5.1 can read thinking produced by Opus 5, Sonnet 5, Opus 4.8, and Fable 5, so a session that moves onto Fable 5.1 replays that history intact. Sonnet 5.5 reasoning, however, is unreadable to it. Switching away and then back does not bring back the pre-switch Fable reasoning: the switch alters the system prompt, which invalidates every earlier Fable block. On direct API-key routes Anthropic drops those blocks server-side and OpenClaw logs the drop; elsewhere, organizations that enforce the prefix check reject the request once, and the embedded runtime retries without prior thinking. Changing the thinking level via /think produces the same result. When reasoning continuity matters, choose the model and thinking level at the start of the session.

Sonnet 5.5 keeps prior Sonnet 5 and Claude 4.x reasoning when a session moves onto it, but reasoning from Opus 5, Opus 5.5, Fable, and Mythos is dropped. Moving away from Sonnet 5.5 drops its reasoning on every other model.

Claude sessions across computers

A Claude Code group is added to the regular sessions sidebar by the bundled Anthropic plugin. Rows open in the usual Chat pane. Non-archived Claude Code sessions are discovered on the Gateway and on connected node hosts:

Claude CLI sessions are sourced from valid project-index records. Where a transcript is unindexed, a bounded metadata fallback picks up concurrent non-sidechain interactive (cli) and headless Agent SDK CLI (sdk-cli) sessions under ~/.claude/projects/. Gateway-side discovery also picks up bidirectional stream-json (sdk-ts) sessions; the native macOS node reader does not.
Claude Desktop sessions rely on the Desktop title, activity time, and archive state when its metadata points at the same Claude Code session ID.
Because a CLI-only session carries no archive flag, it stays visible for as long as its transcript exists.

When a Claude Code session has a title of its own (/rename), that title wins over both the automatic title and the first prompt. Matching session colors are imported through /color; colors that were cleared or are not recognized are left unset. Discovery examines only a limited prefix and tail of each transcript, which means recently appended metadata in large transcripts still gets picked up without the full history being read. Any metadata falling outside those windows may not be available. Rows originating from Desktop keep their Desktop title and stay colorless.

During routine discovery, no more than 64 MiB of transcript metadata is read across 10,000 files. Should either cap be hit, the last page of discovered results reports DISCOVERY_TRUNCATED rather than presenting the inventory as complete. An exact session ID search locates matching transcripts without regard to that frontier; reading, continuing, and opening a known session in a terminal all rely on the same bounded lookup. The per-file metadata windows and the usual path, sidechain, and archive checks continue to apply.

Discovery needs no extra OpenClaw configuration. The Anthropic plugin ships bundled and is enabled by default; when the local Claude projects directory is present, a native macOS node advertises the read-only Claude session commands ($CLAUDE_CONFIG_DIR/projects/ if CLAUDE_CONFIG_DIR is set, otherwise ~/.claude/projects/, which matches Gateway-side discovery). The first time those commands show up, approve the node pairing upgrade.

Rows in the sidebar are grouped by their Gateway or paired-node host, and each host's newest bounded page appears as soon as that computer responds. Reconciliation runs again after host-connectivity changes, whenever the page becomes visible, and every two minutes while it stays visible, so sessions created in Claude outside OpenClaw show up without a reload. While the page is hidden, discovery pauses. To append the next page for every host that has more history, use Load more sessions beneath a catalog group; appended rows remain visible and get re-fetched to the same depth on each refresh. Catalog clients rely on sessions.catalog.list; opening a row relies on sessions.catalog.read.

On the Gateway these refreshes cost little: rather than re-reading ~/.claude/projects/ and the Desktop session store on every poll, the plugin watches them for changes, so an unchanged tree causes no disk access and a change triggers a re-read of only the affected project directory. As a backstop, the whole tree is re-read at most once every five minutes, and if the platform offers no file watcher, the plugin falls back to scanning per request. Desktop metadata is also refreshed every 60 seconds so custom-group changes made outside the watched session store are picked up. Desktop metadata caching retains only bounded catalog fields and PR summaries; unused MCP configurations and launch snapshots are dropped after each read. Gateway enumeration keeps every caller isolated, and the plugin reuses its watched filesystem snapshot across those enumerations.

What the catalog shows depends on the authenticated Gateway profile. Admin connections see all discovered Claude rows, and solo or shared-secret Gateways stay unfiltered. On a multi-user Gateway, a non-admin sees only the rows their durable profile has already adopted; Claude CLI and Desktop rows discovered on a host but not attributed stay hidden. This privacy control operates inside a single trusted Gateway domain; see Multi-user mode.

Terminal takeover resolves claude from the login-shell PATH of the user owning the host, ahead of the service/daemon PATH. As a result, sessions launched from the app match the Claude CLI an operator would get in an ordinary terminal.

Choosing a row loads the newest transcript page first. Load older transcript items advances through an opaque byte cursor, reading another bounded section of the JSONL file rather than the whole history. User, assistant, reasoning, tool-call, and tool-result content is preserved as usual. If a single item exceeds the node/Gateway safety ceiling, it is explicitly marked as truncated.

Typing in the normal composer on a Gateway-local claude-cli row invokes sessions.catalog.continue. OpenClaw re-resolves the local catalog record, then creates or reuses a model-locked native session, imports no more than 200 visible items or 512 KiB, and seeds the Claude CLI binding. The first turn resumes via --fork-session; because Claude gives the fork a new session ID, subsequent turns run on the fork and the source session is left untouched.

The new OpenClaw session inherits the catalog title and color. When an already adopted session is continued, any title or color changes made in OpenClaw are preserved.

A headless node host can make its Claude CLI rows continuable too: enable the node-local setting below and restart the node host.

{
  nodeHost: {
    agentRuns: {
      claude: { enabled: true },
    },
  },
}

Only when the setting is enabled and its local claude executable resolves does the node advertise agent.cli.claude.run.v1. OpenClaw re-resolves the catalog record on that node, imports the same bounded history, and binds the adopted session to the node and to the working directory the catalog reports. Every turn runs the node's actual claude -p process against that node's Claude files and login. The node's exec approval policy still applies, and the Gateway has no way to force the opt-in.

Node continuation v1 is one-shot only. It leaves out Gateway loopback MCP config and Gateway skills plugin arguments, does not reseed from a Gateway transcript, and rejects attachments and images. Claude Desktop rows stay view-only. Native macOS app nodes also stay view-only until the app advertises the run command.

Note

Paired-node Claude sessions stay read-only unless the headless node explicitly advertises agent.cli.claude.run.v1. OpenClaw never changes Claude Desktop metadata and never archives Claude sessions. Catalog list and read rely on operator.read, whereas continuation relies on operator.write. For node-backed rows, paired-node command advertisement and Gateway node policy are still additional requirements.

The node command and security boundary are covered in Nodes: Claude sessions and transcripts.

Live model discovery

Once an Anthropic API key is configured, OpenClaw refreshes the Claude catalog from Anthropic's models endpoint, so models published later show up without an OpenClaw release. Models that the shipped catalog already covers keep their published metadata and pricing.

Every listed row carries the thinking and effort capabilities Anthropic advertises for it (adaptive thinking, whether thinking can be turned off, and xhigh/max effort) as params.claudeCapabilities on the catalog row. Request shaping and the thinking levels offered follow from those capabilities, so a new model receives the request shape it accepts on its very first turn. Rows lacking them (shipped models missing from the listing, configured rows, and catalogs saved before discovery ran) fall back to OpenClaw's model-id rules. An unknown model whose listing has no capability data stays hidden. Discovery is advisory: with no API key, or if the endpoint cannot be reached, the shipped catalog is used unchanged.

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

Bare family aliases roll forward: opus currently resolves to anthropic/claude-opus-5-5, and sonnet resolves to anthropic/claude-sonnet-5-5. An OpenClaw upgrade can move either alias to a newer model generation. To opt out, pin a version: opus-5, sonnet-5, claude-opus-5, claude-sonnet-5, and other explicit versioned selections each keep their own model.

By default, anthropic/claude-opus-5 uses adaptive thinking at high effort. Turn thinking off with /think off, or pick the model's higher native effort levels with /think xhigh|max. Because Anthropic does not support manual thinking budgets, custom sampling parameters, assistant prefills, or Priority Tier on Opus 5, OpenClaw omits all of them for this model. The catalog publishes its 1,000,000-token context window, 128,000-token output limit, image input, and $5/$25 input/output pricing.

anthropic/claude-sonnet-5 shares those adaptive-thinking defaults and request restrictions. Its catalog pricing is Anthropic's standard $2/$10 input/output per million tokens. Anthropic canceled the September 2026 increase it had previously scheduled; see current model pricing.

anthropic/claude-fable-5-1 and anthropic/claude-fable-5 always use adaptive thinking. For both versions, OpenClaw defaults to medium effort. Since Anthropic does not permit thinking to be disabled on these models, stored off and minimal settings are mapped to low effort instead. Caller-selected sampling parameters are also omitted by OpenClaw for both Fable versions.

Fable effort controls provide low, medium, high, xhigh, and max, in line with Anthropic's effort levels. Adaptive thinking is always on and is not offered as a separate effort choice. Stored adaptive selections that already exist resolve to OpenClaw's medium default. Custom anthropic-messages providers share the same profile, including model IDs that carry routing namespaces such as Claude Gateway/claude-fable-5-1.

anthropic/claude-mythos-5 is a limited-access model. It keeps the same contract as the others: adaptive thinking is always on, and there are five effort levels. OpenClaw uses high by default, translates stored off and minimal settings into low, and drops any sampling parameters the caller picked. The catalog lists its 1,000,000-token context window, its 128,000-token output limit, image input support, and $10/$50 pricing for input and output.

On Opus 5.5, Sonnet 5.5, Fable, and Mythos, any new /think minimal or /think adaptive directive is refused, and the supported choices are returned instead. Where you would have written minimal, use /think low; to accept the model's default effort, use /think default. Settings stored earlier are handled by the remapping described above.

Thinking stays off by default in OpenClaw for Claude Opus 4.8. If you turn adaptive thinking on explicitly through /think high|xhigh|max, OpenClaw transmits Anthropic's effort values for Opus 4.8. For the Claude 4.6 models (Opus 4.6 and Sonnet 4.6), the default is adaptive.

You can override this per message with /think:<level>, or through model params:

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

Note

Related Anthropic docs:

Adaptive thinking

Extended thinking

Safety refusal fallback (Claude Opus, Sonnet 5.5, and Fable)

Warning

A safety-classifier refusal on Claude Opus 5.5, Opus 5, Sonnet 5.5, Fable 5.1, or Fable 5 may be routed to a different Claude model. For direct API-key requests, OpenClaw opts into Anthropic's recommended routing per category. Billing for a fallback-served turn goes to the model that answered. If your policy demands that every turn stay on the model you requested, avoid these models when the automatic fallback path is active.

Why this exists

For Opus 5.5, Opus 5, Sonnet 5.5, and Fable, classifiers respond with stop_reason: "refusal" to requests in restricted domains. With no fallback in place, the turn fails with an error, even where Anthropic recommends a model for that refusal category.

How it works

On every direct API-key request to anthropic/claude-opus-5-5, anthropic/claude-opus-5, anthropic/claude-sonnet-5-5, anthropic/claude-fable-5-1, or anthropic/claude-fable-5, OpenClaw transmits the server-side-fallback-2026-07-01 beta header together with fallbacks: "default". The recommended model for the reported refusal category is chosen by Anthropic. For cyber and frontier_llm declines, Sonnet 5.5 falls back to Sonnet 5.
The fallback fires only on a safety-classifier decline. Rate limits, overloads, and server errors are handled exactly as they were before, through OpenClaw's normal model failover.
The rescue occurs within the same call. A decline that arrives before any output is invisible except for added latency, and the serving model produces the entire answer. When the decline happens mid-stream, the partial text already received is preserved as the prefix the fallback model continues from; the declined model's reasoning and tool calls are dropped under Anthropic's replay rules (they must not be echoed back or executed).
Should the recommended model also decline, the turn reports the refusal as an error. OpenClaw does not retry a final refusal, nor does it move on to another configured model.

Because the fallback takes place at the Anthropic API level, the serving model need not appear in your configured OpenClaw fallback chain.

Observability and billing

For a fallback-served turn, a provider_fallback diagnostic is recorded on the assistant message, naming fromModel and toModel, and the message's responseModel shows which model answered.
Anthropic charges the fallback attempt at the serving model's rates. OpenClaw prices known Opus 4.8 fallback-served turns at Opus 4.8 rates. For Sonnet 5.5 fallback-served turns on Sonnet 5, the requested cost is kept, since the rates match.
On a mid-stream decline, Anthropic additionally bills the primary-model partial that was already streamed. That portion appears in the API's per-attempt usage, but OpenClaw's per-turn estimate does not include it.

Scope

This applies to anthropic/claude-opus-5-5, anthropic/claude-opus-5, anthropic/claude-sonnet-5-5, anthropic/claude-fable-5-1, and anthropic/claude-fable-5 when API-key auth is used against api.anthropic.com. OAuth (including reuse of a Claude CLI subscription), proxy base URLs, Bedrock, Vertex, and Foundry requests are unaffected, and refusals there still surface as errors.

For the underlying behavior, see Anthropic's refusals and fallback guide.

Prompt caching

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

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

Per-agent cache overrides

Start from model-level params as your baseline, then override individual agents through agents.entries.*.params:

{
  agents: {
    ownership: "explicit",
    defaults: {
      systemAgent: { agentId: "research" },
      authInheritance: { agentId: "research" },
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
    entries: {
      research: { workspace: "~/.openclaw/workspace" },
      alerts: { params: { cacheRetention: "none" } },
    },
  },
  talk: { agentId: "research" },
}

Config merge order:

agents.defaults.models["provider/model"].params
agents.entries.*.params (matching id, overrides by key)

This way, one agent can hold a long-lived cache while another agent on the same model turns caching off for bursty traffic with little reuse.

Bedrock Claude notes

Anthropic Claude models running on Bedrock (amazon-bedrock/*anthropic.claude*) accept cacheRetention pass-through once configured.
Certain Nova models support explicit caching as an opt-in: you must set cacheRetention to short or long to create system/message checkpoints with a five-minute TTL. Leaving retention unset means no checkpoints are added. OpenClaw maintainers have not yet verified Nova explicit caching live against AWS. All other non-Claude models stay at cacheRetention: "none"; model IDs, AWS limits, and the gap in live acceptance proof are covered in Bedrock prompt caching.
When no explicit value is supplied, API-key smart defaults also populate cacheRetention: "short" for Claude-on-Bedrock refs.

Advanced configuration

Fast mode

For Claude Opus 5.5, Opus 5, and Opus 4.8, the shared /fast toggle in OpenClaw relies on Anthropic's native fast mode when traffic goes directly to api.anthropic.com via an API key.

Command	Maps to
`/fast on`	`speed: "fast"` plus `fast-mode-2026-02-01`
`/fast off`	Standard speed; no `speed` field

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {
          params: { fastMode: true },
        },
      },
    },
  },
}

Note

Native fast mode is a research preview that can raise output-token throughput by up to 2.5x. Pricing is $8/$40 per million input/output tokens for Opus 5.5, and $10/$50 for Opus 5 and Opus 4.8. OpenClaw's cost estimate applies the same 2x multiplier to cache pricing.

Only direct api.anthropic.com requests made with an API key get native fast mode. Requests using OAuth/subscription tokens, Claude CLI, proxies, Bedrock, Vertex, or Foundry never receive the beta or speed field.

Your account must have fast-mode access plus a fast-mode rate limit above zero. If the separate fast quota is exhausted or set to zero, Anthropic returns a fast-specific 429.

For other direct Anthropic models, /fast keeps the existing Priority Tier mapping: enabled means service_tier: "auto", disabled means service_tier: "standard_only".

When both are set, explicit serviceTier or service_tier params take precedence over /fast.

Neither native fast mode nor Priority Tier is available on Claude Sonnet 5.5 and Sonnet 5, so OpenClaw leaves both fields out.

The Control UI disables Fast choices that are confirmed no-ops, which covers Sonnet 5.5, Sonnet 5, and requests governed by an explicit service tier. Saved Fast preferences can still be cleared; existing controls are preserved when route or auth facts are unknown.

Server-side compaction

For direct api.anthropic.com requests authenticated with an API key, OpenClaw turns on Anthropic server-side compaction by default on the models Anthropic documents for threshold compaction: Claude Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Mythos Preview, Opus 5.5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5.5, Sonnet 5, Sonnet 4.6, and Haiku 5.5. To disable it for a single model:

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

Set anthropicServerCompaction: true to opt another direct Claude model in. Memory flush turns never rely on server-side compaction, which lets them pull durable memories out of history that has not been summarized.

OpenClaw attaches the compact-2026-01-12 beta header and submits an Anthropic context_management compaction edit. Summarization instructions inside that edit tell Claude to avoid calling tools while summarizing, since a tool call during summarization yields an empty compaction block. Whenever compaction runs, OpenClaw collects the streamed summary and saves it, along with the provider's opaque compaction metadata, as hidden replay state. Both persist across session reopening and are sent first on the next matching request. Summary text and opaque metadata are kept without secret masking so they can be replayed. The full transcript stays local; only the outbound history preceding the checkpoint is left out. An empty compaction block is never saved as a checkpoint, so the next request sends the same history as before and OpenClaw's client-side compaction remains usable. Should Anthropic reject a stored checkpoint, that turn surfaces the provider error and the turn after it reverts to the full local history.

If anthropicCompactThreshold is left out, OpenClaw falls back to max(50000, floor(budget * 0.7)), where the budget equals the model's contextTokens cap when one is set, and its contextWindow otherwise. With the default trigger, Anthropic compacts earlier than local preflight compaction would. When a trigger lands inside the local compaction reserve, such as the 50000 minimum on a small window, local compaction may run first; the only effect is that server compaction is skipped, never an overflow. Supplying an explicit anthropicServerCompaction: true postpones the outer pre-run check until the trigger; checkpoint safety guards can still compact locally first. To pick a different input-token trigger:

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

Any configured threshold under 50000 is clamped to 50000.

Warning

Anthropic server-side compaction is a beta feature. It works only for direct Anthropic API requests authenticated with an API key. OAuth/subscription tokens, Claude CLI, proxies, Bedrock, Vertex, and Foundry are excluded. OpenClaw does not send pause_after_compaction.

See Anthropic's compaction guide.

Media understanding (image and PDF)

Image and PDF understanding is registered by the bundled Anthropic plugin. OpenClaw resolves media capabilities automatically from the configured Anthropic auth, so no extra config is required.

Property	Value
Default model	`claude-opus-5-5`
Supported input	Images, PDF documents

Whenever an image or PDF is attached to a conversation, OpenClaw routes it through the Anthropic media understanding provider without manual steps.

1M context window

Claude Haiku 5.5, Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Mythos 5, Fable 5.1, and Fable 5 each have an exact 1,000,000-token input window and accept up to 128,000 output tokens. On Claude 4.x models with adaptive thinking, Anthropic's 1M context window is also GA: Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. OpenClaw sizes these models on its own, so params.context1m is unnecessary:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {},
        "anthropic/claude-sonnet-5-5": {},
        "anthropic/claude-sonnet-5": {},
        "anthropic/claude-mythos-5": {},
        "anthropic/claude-opus-4-8": {},
      },
    },
  },
}

Older configs may retain params.context1m: true; for these models it does nothing, and OpenClaw no longer sends the retired context-1m-2025-08-07 beta header in any case. Older anthropicBeta config entries holding that value get dropped while request headers are resolved, and unsupported older Claude models keep their normal context window.

Claude CLI (claude-cli/*) maintains a separate context budget. With older models like Sonnet 4.6, API availability alone does not pick the CLI's extended context. OpenClaw relies on CLI-owned metadata and configured limits; an eligible [1m] model ref or params.context1m: true selects a 1M budget. Whether extended context is actually available still depends on the installed CLI and your account; see Claude Code extended context.

Warning

Long-context access is required on your Anthropic credential. OAuth/subscription token auth keeps its required Anthropic beta headers, but if the retired 1M beta header lingers in older config, OpenClaw strips it.

Claude Opus 5 1M context

anthropic/claude-opus-5 and its claude-cli variant come with a 1M context window by default; params.context1m: true is not required.

Troubleshooting

OpenClaw allows up to 10 seconds for claude auth status --json, which covers startup on hosts that are slow. Being logged out is not implied by a timeout. Execute that command as the Gateway user on the same host, then try setup again. Should it return loggedIn: false, execute claude auth login beforehand.

Claude CLI OAuth session expired or could not be refreshed

As the Gateway user on the Gateway host, run the following commands:

claude auth status --text
claude auth login
openclaw gateway restart

401 errors / token suddenly invalid

Anthropic token auth can expire and may be revoked. Prefer an Anthropic API key for new setups.

No API key found for provider "anthropic"

At runtime, agents read shared auth profiles, and an agent-local profile takes precedence over a shared profile carrying the same ID. Where a usable shared Anthropic profile exists, a new agent needs no separate API key.

Inspect the affected agent using openclaw models status --agent <agentId>. When no usable credential can be found, either configure an Anthropic API key on the Gateway host or set up auth for that agent.

Read-through differs from copying: profiles that are non-portable are still usable from the shared store. Copy flows that are explicit follow the agent copy portability policy.

Native Claude CLI logins stay under Claude Code's ownership rather than the shared OpenClaw auth store. That route is covered by the Claude CLI setup; native OAuth tokens must not be copied into OpenClaw.

No credentials found for profile "anthropic:default"

Execute openclaw models status to find out which auth profile is active. Either re-run onboarding or configure an API key for that profile path.

No available auth profile (all in cooldown)

For auth.unusableProfiles, inspect openclaw models status --json. Cooldowns from Anthropic rate limits may be scoped to a model, so a sibling Anthropic model can remain usable. Wait out the cooldown or add a second Anthropic profile.

Note

Further assistance: Troubleshooting and FAQ.

Model selection, How providers, model refs, and failover behavior are chosen.
CLI backends, Setup and runtime details for the Claude CLI backend.
Prompt caching, The way prompt caching operates across providers.
OAuth and auth, Credential reuse rules and auth details.
Claude Max API proxy, A community proxy that exposes Claude subscription credentials as an OpenAI-compatible endpoint.
Anthropic plugin reference, Anthropic models, Claude CLI, and the native Claude session catalog.

Choose a model route

Claude Haiku 5.5

Usage and cost tracking

Getting started

Get your API key

Run onboarding

Verify the model is available

Config example

Install Claude CLI and log in

Run onboarding

Verify the model is available

Get a setup token

Config example

Billing and claude -p

Use Claude Opus 5.5

Use Claude Sonnet 5.5

Use Claude Fable 5.1

Tool calls and retained thinking

Claude sessions across computers

Live model discovery

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

Safety refusal fallback (Claude Opus, Sonnet 5.5, and Fable)

Why this exists

How it works

Observability and billing

Scope

Prompt caching

Per-agent cache overrides

Bedrock Claude notes

Advanced configuration

Fast mode

Server-side compaction

Media understanding (image and PDF)

1M context window

Claude Opus 5 1M context

Troubleshooting

Claude CLI login could not be verified

Claude CLI OAuth session expired or could not be refreshed

401 errors / token suddenly invalid

No API key found for provider "anthropic"

No credentials found for profile "anthropic:default"

No available auth profile (all in cooldown)

Related

Billing and `claude -p`