OpenClaw 🦞

Anthropic

Anthropic (Claude)

Anthropic 构建了 Claude 模型系列，并通过 API 提供访问。在 OpenClaw 中，你可以使用 API 密钥或 setup-token 进行身份验证。

选项 A：Anthropic API 密钥

最适合： 标准 API 访问和按使用量计费。 在 Anthropic 控制台中创建你的 API 密钥。

CLI 设置

openclaw onboard
# 选择：Anthropic API 密钥

# 或非交互式
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）

  • 当未设置显式思考级别时，Anthropic Claude 4.6 模型在 OpenClaw 中默认为 adaptive 思考。
  • 你可以按消息覆盖（/think:<level>）或在模型参数中覆盖：agents.defaults.models["anthropic/<model>"].params.thinking。
  • 相关 Anthropic 文档：

提示缓存（Anthropic API）

OpenClaw 支持 Anthropic 的提示缓存功能。这是 仅限 API；订阅身份验证不遵守缓存设置。

配置

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

值缓存持续时间描述
none无缓存禁用提示缓存
short5 分钟API 密钥身份验证的默认值
long1 小时扩展缓存（需要 beta 标志）
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

默认值

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

每个代理的 cacheRetention 覆盖

使用模型级参数作为基线，然后通过 agents.list[].params 覆盖特定代理。

{
  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" } }, // 仅为此代理覆盖
    ],
  },
}

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

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

这允许一个代理保持长期缓存，而同一模型上的另一个代理禁用缓存以避免在突发/低重用流量上产生写入成本。

Bedrock Claude 注意事项

  • Bedrock 上的 Anthropic Claude 模型（amazon-bedrock/*anthropic.claude*）在配置时接受 cacheRetention 传递。
  • 非 Anthropic Bedrock 模型在运行时强制为 cacheRetention: "none"。
  • Anthropic API 密钥智能默认值也为 Claude-on-Bedrock 模型引用种子 cacheRetention: "short"（当未设置显式值时）。

遗留参数

较旧的 cacheControlTtl 参数仍受支持以保持向后兼容性：

  • "5m" 映射到 short
  • "1h" 映射到 long

我们建议迁移到新的 cacheRetention 参数。

OpenClaw 为 Anthropic API 请求包含 extended-cache-ttl-2025-04-11 beta 标志；如果你覆盖提供商标头，请保留它（参见 /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 密钥计费，或启用了额外使用量的订阅账户）。否则 Anthropic 返回：HTTP 429: rate_limit_error: Extra usage is required for long context requests。

注意：Anthropic 目前在使用 OAuth/订阅令牌（sk-ant-oat-*）时拒绝 context-1m-* beta 请求。OpenClaw 自动为 OAuth 身份验证跳过 context1m beta 标头，并保留所需的 OAuth betas。

选项 B：Claude setup-token

最适合： 使用你的 Claude 订阅。

在哪里获取 setup-token

Setup-token 由 Claude Code CLI 创建，而不是 Anthropic 控制台。你可以在 任何机器 上运行此命令：

claude setup-token

将令牌粘贴到 OpenClaw 中（向导：Anthropic 令牌（粘贴 setup-token）），或在网关主机上运行：

openclaw models auth setup-token --provider anthropic

如果你在不同机器上生成了令牌，请粘贴它：

openclaw models auth paste-token --provider anthropic

CLI 设置（setup-token）

# 在入职期间粘贴 setup-token
openclaw onboard --auth-choice setup-token

配置片段（setup-token）

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

注意事项

故障排除

401 错误/令牌突然无效

  • Claude 订阅身份验证可能会过期或被撤销。重新运行 claude setup-token 并将其粘贴到 网关主机。
  • 如果 Claude CLI 登录位于不同的机器上，请在网关主机上使用 openclaw models auth paste-token --provider anthropic。

未找到提供商"anthropic"的 API 密钥

  • 身份验证是 每个代理 的。新代理不会继承主代理的密钥。
  • 为该代理重新运行入职，或在网关主机上粘贴 setup-token / API 密钥，然后使用 openclaw models status 验证。

未找到配置文件 anthropic:default 的凭据

  • 运行 openclaw models status 查看哪个身份验证配置文件处于活动状态。
  • 重新运行入职，或为该配置文件粘贴 setup-token / API 密钥。

没有可用的身份验证配置文件（全部在冷却/不可用）

  • 检查 openclaw models status --json 中的 auth.unusableProfiles。
  • 添加另一个 Anthropic 配置文件或等待冷却。

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