🧠 Using Claude with OpenClaw
Connect Anthropic's Claude models to your agent — an API key for production, or the Claude CLI for a quick local path.
Two ways to authenticate
Anthropic builds the Claude model family. OpenClaw supports two routes to it — pick based on where the agent runs.
Anthropic API key
- Recommended for production. Direct Anthropic API access with usage-based billing.
- Works on any host — VPS, container, or laptop — because nothing depends on a local login.
- Best for long-lived gateway hosts, shared automation, and predictable spend.
- Uses
anthropic/*model refs and supports prompt caching.
Claude CLI
- Reuses an existing Claude Code login on the same host — no separate API key.
- Great for local experiments on a machine where you already run Claude Code.
- OpenClaw runs the installed CLI in non-interactive
claude -pmode. - Not available in container installs (host
~/.claudeisn't mounted).
For shared or always-on automation, use an Anthropic API key. Claude CLI auth tokens expire and can be revoked, and subscription claude -p billing can change without an OpenClaw release. API keys give you stable, pay-as-you-go billing you control.
Path A — Anthropic API key
The clean production path. Onboarding stores the key in an auth profile so it isn't pasted into config.
Get an API key
Create a key in the Anthropic Console. Keep it secret — anyone with the key can spend on your account.
Run onboarding
The wizard walks you through provider selection. Choose Anthropic API key when prompted.
openclaw onboard
# choose: Anthropic API keyAlready have the key in your environment? Pass it directly:
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"Verify the model is available
openclaw models list --provider anthropicIf something looks off later, openclaw models status shows which auth profile is active.
Path B — Claude CLI
Reuse an existing Claude Code login without managing a second credential. Same-host only.
Confirm Claude CLI is installed and logged in
claude --versionCheck sign-in and plan with claude auth status.
Run onboarding and pick Claude CLI
openclaw onboard
# choose: Claude CLIOpenClaw detects and reuses the existing Claude CLI credentials. The OpenClaw process must run on the same host as the Claude CLI login.
Verify the model is available
openclaw models list --provider anthropicSetting the default model
Onboarding sets a sensible default for you. To change it by hand, edit ~/.openclaw/openclaw.json and set a provider/model ref under agents.defaults.model.primary.
{
env: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-8" } } },
}If you authenticated with the Claude CLI, keep the model ref as anthropic/* and point that model at the CLI runtime instead of inventing a separate provider:
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-8" },
models: {
"anthropic/claude-opus-4-8": {
agentRuntime: { id: "claude-cli" },
},
},
},
},
}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 runtime policy. See the full walkthrough in the Quick Start guide.
Opus vs Sonnet — choosing a model
OpenClaw sizes GA-capable Claude 4.x models at a 1M context window automatically. The real trade-off is depth versus cost.
Opus — depth
Use anthropic/claude-opus-4-8 (or claude-opus-4-6) for hard reasoning, multi-step tool use, and agents that act on real systems. It costs more per token but makes fewer expensive mistakes when the agent has reach.
Sonnet — value
Use anthropic/claude-sonnet-4-6 for high-volume chat, routing, summaries, and tasks where latency and cost matter more than maximum reasoning depth. It's the sensible default for chatty channels.
Mix per agent
In multi-agent setups, run a smart Opus orchestrator with cheaper Sonnet workers. Set a primary default, then override model on individual agents in agents.list[].
A note on security
An OpenClaw agent can read files, run tools, and act through connected accounts. Model choice is a safety decision, not just a cost one.
For any agent that uses tools, prefer the strongest current-generation Claude you can afford. Weaker or older models are more easily steered by prompt injection in fetched web pages, emails, or documents — and a tool-using agent that gets steered can take real actions. The cost gap between Sonnet and Opus is small next to the cost of an agent doing the wrong thing with broad access. Pair a capable model with tight permissions — see the Security guide.
No API key found for provider "anthropic", re-run onboarding for that agent, then confirm with openclaw models status.