Anthropic

Anthropic (Claude)

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

选项 A：Anthropic API 密钥

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

CLI 设置

openclaw onboard
# choose: Anthropic API key

# or non-interactive
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Claude CLI 配置代码片段

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

Thinking 默认值 (Claude 4.6)

当未明确设置思考级别时，Anthropic Claude 4.6 模型在 OpenClaw 中默认为 adaptive thinking。
您可以在模型参数中逐条消息（/think:<level>）覆盖或进行全局设置： agents.defaults.models["anthropic/<model>"].params.thinking。
相关 Anthropic 文档：
- 自适应思考
- 扩展思考

快速模式 (Anthropic API)

OpenClaw 的共享 /fast 切换开关也支持直接面向公共 Anthropic 的流量，包括发送到 api.anthropic.com 的使用 API 密钥和 OAuth 认证的请求。

/fast on 映射到 service_tier: "auto"
/fast off 映射到 service_tier: "standard_only"
配置默认值：

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

重要限制：

OpenClaw 仅针对直接的 api.anthropic.com 请求注入 Anthropic 服务层级。如果您通过代理或网关路由 anthropic/*，/fast 将保持 service_tier 不变。
显式的 Anthropic serviceTier 或 service_tier 模型参数会在两者均已设置时覆盖 /fast 的默认值。
Anthropic 在响应中的 usage.service_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 来覆盖此设置。

按代理覆盖 cacheRetention

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

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // baseline for most agents
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
    ],
  },
}

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

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

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

Bedrock Claude 说明

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

旧版参数

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

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

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

OpenClaw 在 OpenClaw Anthropic 请求中包含 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。

注意：当使用订阅 setup-token (sk-ant-oat-*) 时，Anthropic 目前会拒绝 context-1m-* beta 请求。如果您使用订阅身份验证配置 context1m: true， OpenClaw 将记录警告并通过跳过 context1m beta 标头同时保留所需的 OAuth beta，回退到标准上下文窗口。

选项 B：使用 Claude CLI 作为消息提供商

最适合： 已安装 Claude CLI 并使用 Claude 订阅登录的单用户网关主机。

此路径使用本地 claude 二进制文件进行模型推理，而不是直接调用 Anthropic API。OpenClaw 将其视为 CLI 后端提供商，模型引用如下所示：

claude-cli/claude-sonnet-4-6
claude-cli/claude-opus-4-6

工作原理：

OpenClaw 在 网关主机上启动 claude -p --output-format json ...。
第一轮对话发送 --session-id <uuid>。
后续回合通过 --resume <sessionId> 重用已存储的 Claude 会话。
您的聊天消息仍然通过正常的 OpenClaw 消息管道，但实际模型回复由 Claude CLI 生成。

要求

网关主机上安装了 Claude CLI 且在 PATH 中可用，或配置了绝对命令路径。
Claude CLI 已在同一主机上进行身份验证：

claude auth status

当您的配置显式引用 claude-cli/... 或 claude-cli 后端配置时， OpenClaw 会在网关启动时自动加载捆绑的 Anthropic 插件。

配置代码片段

{
  agents: {
    defaults: {
      model: {
        primary: "claude-cli/claude-sonnet-4-6",
      },
      models: {
        "claude-cli/claude-sonnet-4-6": {},
      },
      sandbox: { mode: "off" },
    },
  },
}

如果 claude 二进制文件不在网关主机的 PATH 上：

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

您将获得

复用本地 CLI 的 Claude 订阅身份验证
正常的 OpenClaw 消息/会话路由
跨轮次的 Claude CLI 会话连续性

从 Anthropic 身份验证迁移到 Claude CLI

如果您目前使用 setup-token 或 API 密钥配合 anthropic/...，并希望将同一网关主机切换到 Claude API：

openclaw models auth login --provider anthropic --method cli --set-default

或者在新手引导中：

openclaw onboard --auth-choice anthropic-cli

作用如下：

验证 Claude CLI 已在网关主机上登录
将默认模型切换为 claude-cli/...
将 Anthropic 默认模型回退（如 anthropic/claude-opus-4-6）重写为 claude-cli/claude-opus-4-6
向 agents.defaults.models 添加匹配的 claude-cli/... 条目

它不做的是：

删除您现有的 Anthropic 身份验证配置文件
移除主默认模型/允许列表路径之外的每一个旧的 anthropic/... 配置引用

这使得回滚变得简单：如果需要，将默认模型改回 anthropic/...。

重要限制

这不是 Anthropic API 提供商。它是本地 CLI 运行时。
对于 OpenClaw 后端运行，工具在 CLI 端被禁用。
文本输入，文本输出。没有 OpenClaw 流式传输切换。
最适合个人网关主机，而不是共享的多用户计费设置。

更多详情：/gateway/cli-backends

选项 C：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）

# Paste a setup-token during setup
openclaw onboard --auth-choice setup-token

配置片段（setup-token）

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

注意

使用 claude setup-token 生成 setup-token 并粘贴它，或者在网关主机上运行 openclaw models auth setup-token。
如果您在 Claude 订阅上看到 “OAuth token refresh failed …”，请使用 setup-token 重新进行身份验证。参见 /gateway/故障排除。
身份验证详情和重用规则位于 /concepts/oauth。

故障排除

401 错误 / 令牌突然无效

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

未找到提供商 “anthropic” 的 API 密钥

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

No credentials found for profile anthropic:default

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

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

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

更多信息：/gateway/故障排除和 /help/faq。