mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-03 21:24:05 +00:00
13 KiB
13 KiB
summary, read_when, title
| summary | read_when | title | |
|---|---|---|---|
| Use Anthropic Claude via API keys or Claude CLI 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
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.
Anthropic's current public docs:
- 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" } } },
}
```
<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. 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:
- Until June 15, 2026, subscription-plan handling follows Anthropic's active
Claude Code rules for the signed-in account.
- Starting June 15, 2026, subscription-plan `claude -p` usage draws from the
user's monthly Agent SDK credit first, then from usage credits at standard
API rates if usage credits are enabled.
- Console/API-key logins use pay-as-you-go API billing and do not receive
the subscription Agent SDK credit.
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 4.8 and 4.6)
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" },
},
},
},
},
}
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" },
},
},
},
},
}
```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.
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>
| 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.
```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>