Anthropic
在 OpenClaw 中使用 Anthropic Claude：支持 API Key 或 setup-token
Anthropic 构建了 Claude 模型家族，并通过 API 提供访问。在 OpenClaw 中，你可以使用 API Key 或 setup-token 进行鉴权。
方案 A：Anthropic API Key
适用： 标准 API 访问与按量计费。
在 Anthropic Console 创建 API Key。
#
CLI 设置
openclaw onboard openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
#
配置片段
{
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}Prompt caching（Anthropic API）
OpenClaw 支持 Anthropic 的 prompt caching 功能。注意：该功能 仅适用于 API Key；订阅鉴权不会生效缓存配置。
#
配置
在模型配置中使用 ''cacheRetention'' 参数：
| 值 | 缓存时长 | 说明 |
| -- | ---- |
| ''none'' | 不缓存 | 禁用 prompt caching |
| ''short'' | 5 分钟 | API Key 鉴权的默认值 |
| ''long'' | 1 小时 | 扩展缓存（需要 beta flag 支持） |
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-5": {
params: { cacheRetention: "long" },
},
},
},
},
}#
默认行为
当使用 Anthropic API Key 鉴权时，OpenClaw 会自动为所有 Anthropic 模型应用 ''cacheRetention: "short"''（5 分钟缓存）。你可以在配置中显式设置 ''cacheRetention'' 进行覆盖。
#
旧参数（兼容）
旧版 ''cacheControlTtl'' 仍保留以兼容历史配置：
- ''"5m"'' 对应 ''short''
- ''"1h"'' 对应 ''long''
建议迁移到新的 ''cacheRetention'' 参数。
OpenClaw 会在 Anthropic API 请求中包含 ''extended-cache-ttl-2025-04-11'' beta flag；如果你覆盖 provider headers，请保留该 flag（见 ''/gateway/configuration''）。
方案 B：Claude setup-token
适用： 使用你的 Claude 订阅。
#
如何获取 setup-token
setup-token 由 Claude Code CLI 生成，而不是在 Anthropic Console 中创建。你可以在 任意机器 上运行：
claude setup-token
将 token 粘贴到 OpenClaw（向导：Anthropic token（粘贴 setup-token）），或在 gateway 主机上运行：
openclaw models auth setup-token --provider anthropic
如果 token 是在另一台机器上生成的，可在 gateway 主机上粘贴：
openclaw models auth paste-token --provider anthropic
#
CLI 设置
openclaw onboard --auth-choice setup-token
#
配置片段
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}备注
- 用 ''claude setup-token'' 生成并粘贴，或在 gateway 主机上运行 ''openclaw models auth setup-token''。
- 如果你在 Claude 订阅上看到 "OAuth token refresh failed …"，请重新用 setup-token 认证。见 ''/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription''。
- 鉴权细节与复用规则见 ''/concepts/oauth''。
故障排除
401 / token 突然失效
- Claude 订阅鉴权可能过期或被撤销。重新运行 ''claude setup-token'' 并在 ''gateway 主机'' 上粘贴。
- 如果 Claude CLI 登录在另一台机器上，在 gateway 主机上使用 ''openclaw models auth paste-token --provider anthropic''。
No API key found for provider "anthropic"
- 鉴权是 按 agent 存储的。新 agent 不会继承主 agent 的 key。
- 为该 agent 重新跑 onboarding，或在 gateway 主机上粘贴 setup-token / API key，然后用 ''openclaw models status'' 验证。
''No credentials found for profile ''anthropic:default''''
- 运行 ''openclaw models status'' 查看当前使用的 auth profile。
- 重新跑 onboarding，或为该 profile 粘贴 setup-token / API key。
No available auth profile（全部处于 cooldown/unavailable）
- 运行 ''openclaw models status --json'' 查看 ''auth.unusableProfiles''。
- 添加另一个 Anthropic profile 或等待 cooldown 结束。
更多内容：''/gateway/troubleshooting'' 与 ''/help/faq''。