Anthropic (Claude)

Anthropic 开发了 Claude 模型系列，并通过 API 提供访问。在 OpenClaw 中，你可以用 API key 或 setup-token 来认证。

方式 A：Anthropic API key

适合场景： 标准 API 访问和按用量计费。 在 Anthropic Console 中创建你的 API key。

CLI 设置

openclaw onboard
# 选择：Anthropic API key

# 或者非交互式
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

配置示例

{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}

Prompt 缓存（Anthropic API）

OpenClaw 支持 Anthropic 的 prompt 缓存功能。这是 仅限 API 的功能；订阅认证不支持缓存设置。

配置

在模型配置中使用 cacheRetention 参数：

{
  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 标志；如果你覆盖了 provider 头部，记得保留它（参见 Gateway 配置）。

方式 B：Claude setup-token

适合场景： 使用你的 Claude 订阅。

如何获取 setup-token

Setup-token 由 Claude Code CLI 创建，不是在 Anthropic Console 中。你可以在任何机器上运行：

claude setup-token

把 token 粘贴到 OpenClaw（向导中选择：Anthropic token (paste setup-token)），或者在 gateway 主机上运行：

openclaw models auth setup-token --provider anthropic

如果你在另一台机器上生成了 token，可以粘贴它：

openclaw models auth paste-token --provider anthropic

CLI 设置

# 在引导过程中粘贴 setup-token
openclaw onboard --auth-choice setup-token

配置示例

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
}

注意事项

• 用 claude setup-token 生成 token 并粘贴，或者在 gateway 主机上运行 openclaw models auth setup-token。
• 如果在 Claude 订阅上看到”OAuth token refresh failed …”错误，用 setup-token 重新认证。参见故障排除。
• 认证详情和复用规则在 OAuth 概念中。

故障排除

401 错误 / token 突然失效

• Claude 订阅认证可能过期或被撤销。重新运行 claude setup-token 并粘贴到 gateway 主机。
• 如果 Claude CLI 登录在另一台机器上，在 gateway 主机上使用 openclaw models auth paste-token --provider anthropic。

找不到 provider “anthropic” 的 API key

• 认证是按 agent 的。新 agent 不会继承主 agent 的密钥。
• 为该 agent 重新运行引导，或在 gateway 主机上粘贴 setup-token / API key，然后用 openclaw models status 验证。

找不到 profile anthropic:default 的凭据

• 运行 openclaw models status 查看哪个认证 profile 是活动的。
• 重新运行引导，或为该 profile 粘贴 setup-token / API key。

没有可用的认证 profile（全部在冷却/不可用）

• 检查 openclaw models status --json 中的 auth.unusableProfiles。
• 添加另一个 Anthropic profile 或等待冷却结束。

更多信息：Gateway 故障排除和常见问题。