我在 Open Claw 中配置 Anthropic 模型的经验分享

概述

大家好，今天我想和大家聊聊如何在 OpenClaw 中配置 Anthropic 的 Claude 模型家族。根据我的实战经验，OpenClaw 主要支持两种认证方式：API Key 和 Claude Setup-Token。选择哪种方式，完全取决于你的使用场景和订阅模式。

认证方式的选择与配置

方式 A：使用 Anthropic API Key（我的推荐方案）

这种方式最适合标准的 API 访问和按使用量计费的场景，流程清晰直接。

1. 获取你的 API Key

首先，你需要前往 Anthropic 的控制台获取密钥：
https://console.anthropic.com/settings/keys

2. 通过 CLI 快速设置

拿到 Key 后，在终端里运行这个命令，按照提示操作即可：

openclaw auth add

3. 在配置文件中体现

最终，你的配置文件里需要包含类似下面的片段：

auth:
  anthropic_api_key: ${ANTHROPIC_API_KEY:-secretref-xxx}

---

方式 B：使用 Claude Setup-Token（订阅用户的最佳路径）

如果你已经是 Claude 的订阅用户，我个人更推荐这种方式，它和 Claude 桌面应用的体验结合得更紧密。

如何获取 Setup-Token

这个过程稍微有点绕，但操作一次就明白了：

1. 在任何一台机器上，使用 Claude Code CLI 生成 token：

claude setup-token

2. 将生成的 token 粘贴到运行 OpenClaw 的机器上：

# 交互式粘贴，跟着提示走就行
openclaw models auth setup-token --provider anthropic

# 或者，如果你已经复制好了 token 字符串，可以直接传入
openclaw models auth paste-token

3. 如果你是在另一台机器（比如你的笔记本电脑）上生成的 token：
   那么你只需要在运行 OpenClaw gateway 的主机上执行上述的 setup-token 命令，把 token 粘贴过去。

对应的 CLI 设置命令

# 交互式添加，系统会引导你
openclaw auth add

# 或者，明确指定使用 setup-token 方式
openclaw models auth setup-token --provider anthropic

配置代码片段（setup-token）

使用 Setup-Token 时，配置文件的写法略有不同：

agents:
  default:
    auth:
      - provider: anthropic
        setup_token: ${ANTHROPIC_SETUP_TOKEN:-secretref-xxx}

我踩过的坑和注意事项

• 机器绑定：Setup-Token 是和生成它的机器绑定的。如果你在其他机器生成了 token，需要手动粘贴到运行 OpenClaw gateway 的主机上。
• 重新登录：如果你用 CLI 登录了不同的机器，记得在 gateway host 上重新运行一次 setup-token。
• 查看规则：如果对认证流程有疑问，可以随时查看详细规则：/config/auth。

---

故障排除：我遇到过的那些问题

配置过程中难免会遇到一些小麻烦，这里我整理了几个常见问题和解决方法。

401 错误 / Token 突然失效

• 原因：Claude 订阅的 auth token 可能过期或被撤销了。
• 解决：重新运行 claude setup-token 生成一个新的，然后粘贴到 gateway host。

如果 CLI 登录了不同机器

• 现象：认证失效。
• 解决：必须在 gateway host 重新运行 setup-token，或者从旧机器复制 auth token 过来。

报错：未找到 API Key / 提供程序 "anthropic"

• 检查项：
  1. 检查配置文件中的 agent 名称是否正确。
  2. 确认 auth profiles 是否已正确设置。

报错：无凭据找到/配置文件认证失败

• 诊断：运行 openclaw models status 查看当前活跃的 profiles。
• 解决：确认你的 auth profiles 配置无误。

报错：无可用 auth profile

• 深入检查：运行 openclaw models status --json 可以查看更详细的 auth 状态（JSON格式）。
• 解决：根据状态信息，在配置文件中添加或修正 auth profile。

---

探索 Thinking 模式（Claude 4.6 的亮点）

Anthropic Claude 4.x 模型一个很酷的功能是支持“思考”过程，OpenClaw 可以原生地支持这个特性。

默认行为

• 只要模型支持，即使不显式配置，thinking 模式通常也是默认开启的。
• 它支持两种扩展模式：
  • Adaptive thinking（自适应）：模型自己决定思考深度。
  • Extended thinking（扩展）：进行更长时间的思考。

如何配置

很简单，在模型配置里加一个 thinking 参数就行：

agents:
  default:
    models:
      - id: anthropic/claude-opus-4-6
        thinking: enabled

---

利用 Prompt Caching（提示缓存）提升效率

OpenClaw 支持 Anthropic 的提示缓存功能，这能有效减少重复提示的令牌消耗，提升响应速度。需要注意的是，这个功能仅限 API 方式使用，subscription auth 不适用。

配置 cacheExhaustion 参数

这个参数控制缓存多久失效：

值	缓存持续时间	说明
never	无缓存	完全禁用缓存
short	5 分钟	短期缓存，适合对话类场景
long	1 小时	长期缓存，但回收时会丢失标记

配置示例

agents:
  default:
    models:
      - id: anthropic/claude-opus-4-6
        cache_exhaustion: long

更精细的每 Agent 缓存控制

你可以在全局设置一个基线，然后在特定的 agent 里覆盖它，非常灵活：

agents:
  - id: test
    models:
      - id: anthropic/claude-opus-4-6
        cache_exhaustion: long
      - id: anthropic/claude-sonnet-4-6
        cache_exhaustion: never  # 对这个模型禁用缓存

记住配置的优先级顺序：
1. 最具体：agents[x].models[N].cache_exhaustion
2. 其次：agents[x].cache_exhaustion
3. 最后：providers/anthropic.cacheExhaustion

---

关于 Bedrock Claude 模型的一个特别说明

如果你通过 AWS Bedrock（amazon-bedrock/anthropic.claude）使用 Claude 模型，需要特殊处理：

• 如果不是使用 Anthropic 官方的认证，系统会强制使用 claude_exhaustion 的 long 值。
• 即使使用 Anthropic API key，为了 Bedrock 回退兼容，也需要发送 cacheExhaustion: "short"。

---

处理旧版参数（兼容性提醒）

如果你在旧的配置中看到了 cacheExhaustionMode 参数，别担心，它仍然被支持：
- fast 会自动映射到 short
- slow 会自动映射到 long

不过，我建议你尽快迁移到新的 cache_exhaustion 参数，写法更统一。

---

尝鲜：1M 上下文窗口（Anthropic Beta 功能）

Anthropic 的 1M 上下文窗口目前还处于 beta 阶段，但已经在 OpenClaw 中可以按模型启用了：

agents:
  default:
    models:
      - id: anthropic/claude-opus-4-6
        context_window: 1m

开启这个功能后，max_tokens 参数会自动调整以支持 1M 上下文窗口模型。

重要前提和注意事项

• API 版本：仅支持 2025-08-07 之后版本的 Anthropic API。
• Beta Header：需要显式设置 Header：anthropic-beta: output-1m-context-tokens-2025-08-07（OpenClaw 通常会帮你处理）。
• 使用权限：即使你的账户有足够信用额度，也需要 Anthropic 允许你使用 1M 上下文。
• 自动映射：如果设置了不兼容的 beta header，Anthropic 可能会自动进行映射。

---

配置示例汇总（抄作业时间）

看了这么多，我们来整合几个完整的配置例子，方便你直接参考。

完整配置示例（使用 API Key）

providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}

agents:
  default:
    models:
      - id: anthropic/claude-opus-4-6
        thinking: enabled
        cache_exhaustion: long

完整配置示例（使用 Setup-Token）

agents:
  default:
    auth:
      - provider: anthropic
        setup_token: ${ANTHROPIC_SETUP_TOKEN}
    models:
      - id: anthropic/claude-opus-4-6
        thinking: enabled
        context_window: 1m

多 Agent 差异化配置示例

agents:
  - id: coding  # 编程助手 Agent
    models:
      - id: anthropic/claude-opus-4-6
        cache_exhaustion: long  # 代码提示可以长期缓存
  - id: chat    # 通用聊天 Agent
    models:
      - id: anthropic/claude-sonnet-4-6
        cache_exhaustion: never  # 聊天对话禁用缓存，保持新鲜感

---

我常用的命令清单

日常维护和排查时，这几个命令非常有用：

# 快速查看整体认证状态
openclaw models status

# 详细检查 auth profiles 配置
openclaw models status --check

# 实时探测认证是否有效
openclaw models status --probe

# 添加新的认证（交互式）
openclaw auth add

# 专门用于 Setup-token 登录
openclaw models auth setup-token --provider anthropic

# 查看已安装的 providers 列表
openclaw plugins list

---

相关文档

• Open Claw 切换模型操作手册
• 官方文档 - Anthropic 配置

---

最后更新：2026-03-08