上个月我把本地的 AI 助手从 ChatGPT 套壳客户端换成了 OpenClaw，原因很简单——我想在一个界面里同时用 Claude Opus 4.7 和 GPT-5.5，还能自己管 prompt 模板。结果光是把 Claude 接进去这一步，就折腾了大半天。官方文档写得挺简略，好几个配置项藏得很深，搜了一圈也没找到完整的中文教程。所以干脆自己写一篇，把踩过的坑都记下来。
OpenClaw 接入 Claude 的核心步骤就三步：拿到兼容 OpenAI 格式的 API Key、在 OpenClaw 后台填入 base_url 和 Key、配置模型参数。整个过程 10 分钟能搞定，前提是你别像我一样在 base_url 末尾多加了个斜杠。
先说结论
| 项目 | 说明 |
|---|---|
| OpenClaw 版本 | v2.3.1+（低于这个版本不支持 Anthropic 原生协议切换） |
| 支持的 Claude 模型 | Opus 4.7 / Sonnet 4.6 / Haiku 4.5 |
| 接入方式 | OpenAI 兼容格式（推荐）/ Anthropic 原生格式 |
| 配置耗时 | 约 10 分钟 |
| 踩坑概率 | 中等，主要集中在 base_url 和 model name 拼写 |
环境准备
你需要这几样东西：
一台能跑 OpenClaw 的机器。我用的是阿里云 2C4G 的 ECS，Ubuntu 22.04，Docker 部署。热榜上那篇 127.9 元搭 OpenClaw 的帖子写得挺清楚，照着来就行。
一个能调 Claude 的 API Key。这里有两条路——直接用 Anthropic 官方 Key，或者用聚合平台的 Key。我两种都试了，后面分别讲。
SSH 工具和一个趁手的编辑器，改配置文件用。
方案一：通过 Anthropic 官方 Key 直连
最直接的方式。去 console.anthropic.com 创建 API Key，然后在 OpenClaw 后台操作。
打开 OpenClaw 的管理面板，一般是 http://你的IP:3000，进入「渠道管理」→「添加新渠道」。
关键配置：
# OpenClaw 渠道配置
渠道类型: Anthropic
名称: claude-official（随便起）
Base URL: https://api.anthropic.com
密钥: sk-ant-api03-xxxxxxxxxxxx
模型: claude-opus-4-7-20260401, claude-sonnet-4-6-20260301, claude-haiku-4-5-20260201
这里有个坑——模型名称必须用 Anthropic 官方的完整 ID，不能写 claude-opus-4.7 这种简写。我一开始写的 claude-opus-4.7，调用直接返回 404：
{"error":{"type":"not_found_error","message":"model: claude-opus-4.7 not found"}}
改成 claude-opus-4-7-20260401 就好了。这个命名规则挺反人类的，版本号用横杠不用点，后面还跟日期。
填完保存，去「令牌管理」创建一个 Token，拿到 sk-xxxxxxx 格式的 OpenClaw 内部 Key。
测试一下：
from openai import OpenAI
client = OpenAI(
api_key="sk-你的OpenClaw令牌",
base_url="http://你的IP:3000/v1"
)
response = client.chat.completions.create(
model="claude-opus-4-7-20260401",
messages=[{"role": "user", "content": "用一句话解释量子纠缠"}],
max_tokens=200
)
print(response.choices[0].message.content)
如果返回正常内容，说明通了。
但这个方案有个现实问题：Anthropic 官方对部分地区的访问延迟比较高，我测下来 P95 在 1800ms 左右，体验不太行。官方 Key 的并发限制也比较紧，免费 Tier 只有 5 RPM，升到 Build Tier 也就 50 RPM。
方案二：通过聚合 API 平台接入（推荐）
这是我最后稳定在用的方案。聚合平台延迟低，不用自己处理各家 API 的格式差异，改个 base_url 就完事。
我对比过 OpenRouter 和 ofox.ai 这类聚合服务，OpenRouter 会在每次调用上加 5.5% 的手续费，ofox.ai 是 0% 加价直接对齐 Anthropic 官方定价，走的 AWS Bedrock 官方通道。对我这种每天调用量不大但积少成多的独立开发者来说，手续费差距一个月下来能差出好几十刀，挺烦人的。
OpenClaw 后台配置：
渠道类型: OpenAI（注意：选 OpenAI 兼容格式，不是 Anthropic）
名称: claude-via-aggregator
Base URL: https://api.ofox.ai/v1
密钥: 你在聚合平台拿到的 Key
模型: claude-opus-4-7-20260401, claude-sonnet-4-6-20260301
graph LR
A[你的应用] -->|OpenAI SDK| B[OpenClaw 网关]
B -->|OpenAI 兼容协议| C[聚合 API 平台]
C -->|Anthropic 官方通道| D[Claude Opus 4.7]
C -->|Anthropic 官方通道| E[Claude Sonnet 4.6]
C -->|OpenAI 官方通道| F[GPT-5.5]
跑通之后测了一下延迟，P95 在 320ms 左右，比直连 Anthropic 官方快了不少。主要是位置的问题。
测试代码和方案一完全一样，只是 OpenClaw 后端走了不同的渠道，对调用方透明。
踩坑记录
坑 1：base_url 末尾多了斜杠
我最开始填的是 https://api.ofox.ai/v1/，注意末尾多了个 /。OpenClaw 拼接路径的时候会变成 https://api.ofox.ai/v1//chat/completions，双斜杠直接 404。
Error: Request failed with status code 404
URL: https://api.ofox.ai/v1//chat/completions
删掉末尾斜杠就好了。这个问题我排查了 40 分钟，因为 OpenClaw 的日志默认不打印完整 URL，得去 Docker 容器里看 nginx 的 access log 才发现。
坑 2：模型映射没配对
OpenClaw 有个「模型映射」功能，可以把用户请求的模型名映射到实际的模型 ID。比如用户传 claude-4-sonnet，映射到 claude-sonnet-4-6-20260301。
但如果你在渠道配置里填的模型列表和映射规则对不上，请求会直接被 OpenClaw 拦截，返回：
{"error":{"message":"该令牌无权使用模型 claude-4-sonnet","type":"one_api_error"}}
解决办法：要么在令牌设置里把对应模型加到白名单，要么干脆把令牌的模型权限设成「不限制」。我选了后者，反正是自己用。
坑 3：max_tokens 默认值问题
Claude 的 API 有个特殊要求：必须显式传 max_tokens 参数，不传会报错。但 OpenClaw 在转发请求的时候，如果客户端没传这个参数，有些版本不会自动补上默认值。
报错长这样：
{"type":"error","error":{"type":"invalid_request_error","message":"max_tokens: required"}}
两种解法：一是在代码里每次都传 max_tokens=4096；二是升级 OpenClaw 到 v2.3.1 以上，新版本会自动补默认值。我建议直接升版本。
坑 4：Streaming 模式下的超时
用流式输出的时候，如果 Claude 的回复比较长（比如让它写 2000 字的文章），OpenClaw 默认的 nginx 超时时间 60 秒可能不够。表现是回复到一半突然断掉，没有报错，连接直接关了。
在 OpenClaw 的 Docker Compose 里加一行环境变量：
environment:
- RELAY_TIMEOUT=300
或者直接改 nginx 配置：
proxy_read_timeout 300s;
proxy_send_timeout 300s;
改完重启容器，问题解决。
完整的调用示例
贴一个我实际在用的 Python 脚本，支持流式输出和错误重试：
from openai import OpenAI
import time
client = OpenAI(
api_key="sk-你的OpenClaw令牌",
base_url="http://你的IP:3000/v1"
)
def chat_with_claude(prompt, model="claude-sonnet-4-6-20260301", retries=3):
for attempt in range(retries):
try:
stream = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}],
max_tokens=4096,
stream=True
)
full_response = ""
for chunk in stream:
if chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
print(content, end="", flush=True)
full_response += content
print() # 换行
return full_response
except Exception as e:
print(f"\n第 {attempt+1} 次请求失败: {e}")
if attempt < retries - 1:
time.sleep(2 ** attempt) # 指数退避
return None
# 用 Sonnet 处理日常任务
result = chat_with_claude("帮我写一个 Python 装饰器，实现函数调用结果的 LRU 缓存，支持设置 TTL")
# 复杂推理任务切 Opus
result = chat_with_claude(
"分析这段代码的时间复杂度，并给出优化方案...",
model="claude-opus-4-7-20260401"
)
小结
整个配置过程其实不复杂，核心就是渠道类型别选错、模型名称用完整 ID、base_url 末尾别加斜杠。我现在日常写代码基本都在 OpenClaw 里切着用——简单任务丢给 Sonnet 4.6，需要深度推理的时候切 Opus 4.7，体验还挺顺滑的。
有一点我也不确定是不是最佳实践：我把 OpenClaw 的负载均衡设成了「优先级」模式而不是「轮询」，这样同一个模型配多个渠道的时候，会优先走延迟最低的那个。目前用下来没出问题，但样本量不大，不好说长期稳定性怎么样。
如果你也在折腾 OpenClaw，遇到别的坑可以评论区聊。
