Qclaw接入Sub2API中转站AI模型

Sub2API 中转 接入Qclaw 两次踩坑全记录
日期：2026-06-01　环境：QClaw / Windows
用于自己下一次配置时不再犯错

---

一、背景

目标很简单：在 QClaw 里通过一个自建的 Sub2API 中转（地址 https://chickin.cloud/）调用 claude-opus-4-8 模型。

结果一路踩了 5 个坑，从「报 401」到「不报错但没响应」，再到莫名其妙的「499 tool 消息错误」。最后定位到一个藏得很深的配置覆盖问题才彻底解决。

下面按发生顺序，逐个记录错误现象 → 问题根因 → 解决办法。

1. 下载安装Qclaw
   https://qclaw.qq.com/
   全部默认就可以

2. 新增模型
   
   
   
   
   再点击确认

---

二、错误清单

❌ 错误 1：API Key 报 401 Unauthorized

现象
调用 Claude 4.8 时持续返回 401，但自认为 key 没问题。

排查

• 先确认中转服务器是否在线：curl https://chickin.cloud/ 返回 200，是一个 Sub2API（New API 系列）网关，服务正常。
• 用一个无效 key 测试它的 Anthropic 端点，返回：

  {"code":"INVALID_API_KEY","message":"Invalid API key"}  // HTTP 401
  

问题根因
401 不是 Anthropic 官方返回的，而是 Sub2API 中转层拒绝了请求。也就是说，401 的来源是中转平台的认证校验，而非模型本身。这一步把排查方向从「Anthropic 账号」收窄到了「中转配置 + key 传递方式」。

后续验证
拿到真实 key 后实测，发现 key 本身完全有效（见错误 3 的验证），所以 401 实际上是后面几个配置问题的连锁表现，而不是 key 失效。

---

❌ 错误 2：改完不报 401 了，但「没有任何响应」

现象
把 provider 的 api 协议改成 openai-completions 后，401 消失了，但调用后石沉大海，没有返回。

排查过程（关键验证）
直接用真实 key 测试中转的 OpenAI 兼容端点：

curl -X POST https://chickin.cloud:1234/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d @request.json

⚠️ 小插曲：一开始在 Windows PowerShell 里用 -d "{...}" 内联 JSON，因为引号转义/编码问题一直报 400。改成 -d @文件 从文件读取后立刻成功。这说明 key 和接口都没问题，是 shell 转义在捣乱。

成功返回：

{"choices":[{"message":{"content":"Hey! What are you working on today?",
  "reasoning_content":"The user is greeting me..."}}]}

问题根因
注意返回里多了一个非标准字段 reasoning_content（Claude 的思考过程）。OpenAI 兼容格式下，Sub2API 把 Claude 的 thinking 塞进了 reasoning_content，而 QClaw 的 OpenAI 解析器不认识这个字段，流式解析卡住 → 表现为「无响应」。

---

❌ 错误 4：开了 reasoning 还是不行

现象
尝试在模型配置里加 reasoning: true，重启后依然无响应。

问题根因
方向是对的（确实需要让 QClaw 知道有思考块），但没解决根本矛盾：OpenAI 兼容格式 + 非标准 reasoning_content 字段的组合，本身就不被 OpenClaw 正确支持。换句话说，这只是在错误的赛道上微调。

---

❌ 错误 5：499 报错 —— role 'tool' must be a response to a preceding message with 'tool_calls'

现象
切回 anthropic-messages 协议并加上 authHeader: true 后，调用报出：

499 Messages with role 'tool' must be a response to a preceding
message with 'tool_calls'  <invalid_request_error>

排查（真正的转折点）
此前我一直在改 provider 级的 api 字段，但每次重启都不生效。于是直接打开源文件 openclaw.json 逐行读，终于发现：

"custom-1780278826838": {
  "api": "anthropic-messages",      // ← provider 级（我一直在改这里）
  "models": [{
    "id": "claude-opus-4-8",
    "api": "openai-completions",    // ← 模型级！偷偷覆盖了上面
    ...
  }]
}

问题根因（核心）
OpenClaw 的规则是「模型级配置覆盖 provider 级」。 模型定义里藏着一个 api: "openai-completions"，把我在 provider 层做的所有改动全部「吃掉」了。于是实际生效的一直是 OpenAI 格式——OpenClaw 按 OpenAI 规范发出了带 tool 角色的消息，但前面没有配套的 tool_calls，Sub2API 的消息校验直接拒绝，返回 499。

这就是「为什么改了那么多次都没用」的真相：真正生效的那一层，从头到尾就没被改到。

---

三、最终解决方案

一次性把三层配置对齐，问题彻底解决：

文件路径**C:\Users\用户名\.qclaw\openclaw.jsn**(记得打开被隐藏的文件夹)

"custom-1780278826838": {
  "baseUrl": "https://chickin.cloud:1234/",
  "apiKey": "sk-xxxx",
  "api": "anthropic-messages",   // ① 用 Anthropic 原生格式（Sub2API 完美支持）
  "authHeader": true,            // ② 强制用 Authorization: Bearer
  "models": [{
    "id": "claude-opus-4-8",
    "name": "claude-opus-4-8",
    "reasoning": true            // ③ 正确处理思考块
    // ④ 删掉模型级的 api 覆盖，让它继承 provider
  }]
}

四个关键点：

1. api: "anthropic-messages" —— 实测中转支持 Anthropic 原生 /v1/messages 端点，且流式返回结构标准（message_start / content_block_delta / message_stop），比 OpenAI 兼容格式稳得多。
2. authHeader: true —— 这个中转只认 Authorization: Bearer，不认 Anthropic 官方标准的 x-api-key。用 x-api-key 会报 400「Failed to parse request body」。这是中转的非标准行为，必须靠实测才能发现。
3. reasoning: true —— 让 QClaw 正确解析 Claude 的 thinking 内容。
4. 移除模型级 api 覆盖 —— 让模型继承 provider 的协议，避免「改了不生效」。

验证结果：用 custom-1780278826838/claude-opus-4-8 跑测试，3 秒返回 “hello”，15.3k tokens 输入、1 token 输出。✅ 彻底打通。

---

四、经验总结

1. 多层配置一定要查全。 QClaw 的 model 级会覆盖 provider 级。排查时别只看一层，更别只信 config.get 返回的「已合并结果」——直接读源文件最可靠。这一条如果一开始就做，能少绕三圈。

2. 中转网关的认证方式可能不标准。 Sub2API 支持 Anthropic 原生格式，却要求用 Authorization: Bearer 而非 x-api-key。这种非标准行为只能靠 curl 逐一实测确认，不能想当然。

3. 优先用 Anthropic 原生格式而非 OpenAI 兼容格式。 后者下中转返回的 reasoning_content、tool 消息结构很容易和客户端解析器冲突（无响应、499 等）。原生格式的流式结构更规范。

4. Windows 下 curl 传 JSON 用 -d @文件。 内联 -d "{...}" 在 PowerShell 里极易被引号/编码搞坏，误报 400，浪费排查时间。

5. 「问题很多」往往只是「一个根因的多种表象」。 这次从 401 → 无响应 → 499，看似五个独立故障，根子其实是同一个：真正生效的配置层一直没被修改到。

---