Anthropic (Claude)

Anthropic 是 Claude 系列模型的开发者，通过 API 提供访问。在 OpenClaw 中，你可以用 API 密钥或 setup-token 完成认证。

方式 A：Anthropic API 密钥

适合场景： 标准 API 访问、按量计费。在 Anthropic Console 创建你的 API 密钥即可。

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

思考模式默认值（Claude 4.6）

在 OpenClaw 中，Anthropic Claude 4.6 系列模型未显式设置思考级别时，默认使用 adaptive（自适应）思考模式。
可以按消息覆盖（/think:<level>），也可以在模型参数中设置： agents.defaults.models["anthropic/<model>"].params.thinking。
相关 Anthropic 文档：
- Adaptive thinking
- Extended thinking

快速模式（Anthropic API）

OpenClaw 的 /fast 开关也支持直连 Anthropic API 密钥的流量。

/fast on 对应 service_tier: "auto"
/fast off 对应 service_tier: "standard_only"
配置默认值：

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

需要注意的限制：

仅限 API 密钥。Anthropic setup-token / OAuth 认证不会触发 OpenClaw 的快速模式层级注入。
OpenClaw 仅对直连 api.anthropic.com 的请求注入 Anthropic service tier。如果你把 anthropic/* 路由到代理或网关，/fast 不会修改 service_tier。
Anthropic 在响应的 usage.service_tier 中返回实际使用的层级。对于没有 Priority Tier 容量的账户，service_tier: "auto" 可能仍然解析为 standard。

提示缓存（Anthropic API）

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

配置

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

值	缓存时长	说明
`none`	不缓存	关闭提示缓存
`short`	5 分钟	API 密钥认证的默认值
`long`	1 小时	延长缓存（需要 beta 标志）

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

默认行为

使用 Anthropic API 密钥认证时，OpenClaw 自动为所有 Anthropic 模型应用 cacheRetention: "short"（5 分钟缓存）。你可以在配置中显式设置 cacheRetention 来覆盖。

按 Agent 覆盖 cacheRetention

用模型级参数做基线，再通过 agents.list[].params 为特定 Agent 覆盖。

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // 大多数 Agent 的基线
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // 仅该 Agent 覆盖
    ],
  },
}

缓存相关参数的合并顺序：

agents.defaults.models["provider/model"].params
agents.list[].params（按 id 匹配，按 key 覆盖）

这样你可以让一个 Agent 保持长期缓存，而另一个同模型的 Agent 关掉缓存，避免在突发性 / 低复用流量上产生不必要的写入开销。

Bedrock Claude 说明

Bedrock 上的 Anthropic Claude 模型（amazon-bedrock/*anthropic.claude*）支持 cacheRetention 透传。
非 Anthropic 的 Bedrock 模型在运行时会被强制设为 cacheRetention: "none"。
Anthropic API 密钥的智能默认值也会为 Bedrock 上的 Claude 模型引用注入 cacheRetention: "short"（未显式设置时）。

旧参数

旧的 cacheControlTtl 参数仍然兼容：

"5m" 对应 short
"1h" 对应 long

建议迁移到新的 cacheRetention 参数。

OpenClaw 在 Anthropic API 请求中自动包含 extended-cache-ttl-2025-04-11 beta 标志；如果你覆盖了 provider headers，请保留该标志（参见 /gateway/configuration）。

1M 上下文窗口（Anthropic beta）

Anthropic 的 1M 上下文窗口需要 beta 准入。在 OpenClaw 中，对支持的 Opus/Sonnet 模型设置 params.context1m: true 即可启用。

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { context1m: true },
        },
      },
    },
  },
}

OpenClaw 会将其映射为 Anthropic 请求中的 anthropic-beta: context-1m-2025-08-07。

只有对该模型显式设置 params.context1m 为 true 时才会激活。

前提条件：Anthropic 必须允许该凭据使用长上下文（通常是 API 密钥计费账户，或启用了 Extra Usage 的订阅账户）。否则 Anthropic 会返回： HTTP 429: rate_limit_error: Extra usage is required for long context requests。

注意：Anthropic 目前拒绝通过 OAuth/订阅 token（sk-ant-oat-*）发起的 context-1m-* beta 请求。OpenClaw 会自动为 OAuth 认证跳过 context1m beta header，保留必需的 OAuth beta。

方式 B：Claude setup-token

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

获取 setup-token

Setup-token 由 Claude Code CLI 生成，不是在 Anthropic Console 创建的。你可以在任意机器上执行：

claude setup-token

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

openclaw models auth setup-token --provider anthropic

如果是在另一台机器上生成的 token，可以这样粘贴：

openclaw models auth paste-token --provider anthropic

CLI 配置（setup-token）

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

配置示例（setup-token）

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

补充说明

用 claude setup-token 生成 token 后粘贴，或在网关主机上运行 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 并在网关主机上粘贴。
如果 Claude CLI 登录在另一台机器上，在网关主机上使用 openclaw models auth paste-token --provider anthropic。

No API key found for provider “anthropic”

认证是按 Agent 的。新 Agent 不会继承主 Agent 的密钥。
为该 Agent 重新运行 onboarding，或在网关主机上粘贴 setup-token / API 密钥，然后用 openclaw models status 验证。

No credentials found for profile anthropic:default

运行 openclaw models status 查看当前激活的认证 profile。
重新运行 onboarding，或为该 profile 粘贴 setup-token / API 密钥。

No available auth profile (all in cooldown/unavailable)

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

更多信息：/gateway/troubleshooting 和 /help/faq。