OpenClaw 集成 Anthropic Claude 完全指南

核心能力：在 OpenClaw 中无缝接入 Anthropic 的 Claude 系列模型（包括最新的 Claude 4.6）。 认证方式：支持 API Key（按量付费）和 Setup-Token（订阅用户复用额度）。 高级特性：自适应思维 (Adaptive Thinking)、提示词缓存 (Prompt Caching)、1M 超长上下文。

🔑 一、认证方式选择

OpenClaw 提供两种连接 Anthropic 的方式，请根据你的账户类型选择：

🚀 二、快速开始配置

方案 A：使用 API Key (推荐生产环境)

1. 获取密钥

登录 Anthropic Console -> Settings -> API Keys -> Create Key。

2. 一键配置 (CLI)

# 交互式配置
openclaw onboard
# 选择 "Anthropic API key" 并粘贴密钥

# 或非交互式 (适合脚本/CI)
export ANTHROPIC_API_KEY="sk-ant-..."
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

3. 配置文件 (openclaw.json)

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

方案 B：使用 Setup-Token (订阅用户)

如果你已经购买了 Claude Pro 或 Team 订阅，可以通过此方式让 OpenClaw 复用你的额度，无需额外支付 API 费用。

1. 生成 Token

在任意机器上安装官方 Claude CLI，运行：

claude setup-token

系统会输出一串以 sk-ant-st-... 开头的长字符串。

2. 导入到 OpenClaw

情况 A：在同一台机器 (Gateway 主机)

openclaw models auth setup-token --provider anthropic

情况 B：在不同机器生成 (复制粘贴)

# 在 Gateway 主机运行
openclaw models auth paste-token --provider anthropic
# 然后粘贴刚才生成的 token

情况 C：通过 Onboarding 向导

openclaw onboard --auth-choice setup-token

3. 配置文件

Setup-Token 模式下，通常不需要在 env 中配置 Key，只需指定模型：

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

🧠 三、高级功能配置

1. 自适应思维 (Adaptive Thinking) - Claude 4.6 专属

Claude 4.6 模型默认开启 Adaptive Thinking，模型会根据问题难度自动调整思考深度。

• 默认行为：自动适应。
• 手动覆盖：
  • 对话中：使用 /think:<level> 指令 (如 /think:high)。
  • 配置中：{ "agents": { "defaults": { "models": { "anthropic/claude-opus-4-6": { "params": { "thinking": "enabled" // 或 "disabled", "adaptive" } } } } } }

2. 提示词缓存 (Prompt Caching) 💰

仅限 API Key 用户。通过缓存重复的系统提示词或长文档，可显著降低延迟和成本。

缓存策略 (cacheRetention)

配置示例

{
  "agents": {
    "defaults": {
      "models": {
        // 全局默认：长缓存
        "anthropic/claude-opus-4-6": {
          "params": { "cacheRetention": "long" }
        }
      }
    },
    "list": [
      { 
        "id": "research-agent", 
        // 继承全局 long 缓存
      },
      { 
        "id": "alert-agent", 
        // 特定 Agent 禁用缓存 (突发流量，无复用价值)
        "params": { "cacheRetention": "none" } 
      }
    ]
  }
}

注意：

• 订阅用户 (Setup-Token) 不支持 缓存配置，该参数会被忽略。
• 旧参数 cacheControlTtl (5m, 1h) 仍兼容，但建议迁移至 cacheRetention。

3. 1M 超长上下文 (Beta) 📚

Anthropic 提供了 1M Token 上下文窗口，但目前处于 Beta 阶段，需要显式开启。

开启方法

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

OpenClaw 会自动添加 anthropic-beta: context-1m-2025-08-07 请求头。

⚠️ 重要限制

• 仅限 API Key：目前 Anthropic 不支持 在 OAuth/Subscription (Setup-Token) 账号上开启 1M 上下文。如果使用 Token 认证，此配置将被自动忽略或报错。
• 额外费用：即使有订阅，1M 上下文通常也需要开启 "Extra Usage" 并按量付费。
• 错误处理：如果额度不足，会收到 HTTP 429: Extra usage is required。

🛠️ 四、故障排查 (Troubleshooting)

❌ 错误：401 Unauthorized / Token suddenly invalid

• 原因：Setup-Token 已过期或被撤销（常见于订阅用户修改密码或登出）。
• 解决：
  1. 重新运行 claude setup-token 获取新 Token。
  2. 在 Gateway 主机运行 openclaw models auth paste-token --provider anthropic 更新。

❌ 错误：No API key found for provider "anthropic"

• 原因：Auth 是基于 Agent 的。新建的 Agent 没有继承默认配置。
• 解决：
  • 对该 Agent 重新运行 openclaw onboard。
  • 或者检查 agents.list 中是否漏配了模型引用。
  • 运行 openclaw models status 查看当前认证状态。

❌ 错误：No credentials found for profile anthropic:default

• 原因：默认 Profile 未配置。
• 解决：运行 openclaw models status 确认活跃 Profile，重新执行 Onboarding。

❌ 错误：Extra usage is required for long context requests

• 原因：开启了 context1m: true 但账户余额不足或未开通超额用量。
• 解决：
  • 在 Anthropic 控制台充值或开启 "Extra Usage"。
  • 或者在配置中移除 context1m: true 降级到标准上下文 (200k)。

❌ 错误：OAuth token refresh failed

• 原因：订阅用户的 OAuth 刷新机制失效。
• 解决：放弃 OAuth 自动刷新，直接使用 Setup-Token 方式重新认证（参考上文方案 B）。

💡 五、最佳实践总结

1. 生产环境首选 API Key：稳定性高，支持缓存和 1M 上下文，便于成本核算。
2. 个人开发用 Setup-Token：省钱，但需注意 Token 有效期，且无法使用高级缓存和超长上下文功能。
3. 精细化缓存管理：
   • 对“知识库问答”类 Agent 设置 cacheRetention: "long"。
   • 对“即时报警/通知”类 Agent 设置 cacheRetention: "none" 以节省写入成本。
4. 监控状态：定期运行 openclaw models status --json 检查 auth.unusableProfiles，防止因认证失效导致服务中断。

通过合理配置，你可以让 OpenClaw 充分发挥 Claude 4.6 的强大推理能力，构建从简单聊天到复杂长文档分析的全场景应用。