1. OpenClaw Gateway 接入 QQ 的真实场景与统一 Key 需求OpenClaw 是一个开源、本地优先、模型无关的 AI 智能体执行网关你可以把它理解成一个「消息调度中枢」QQ、飞书、网页端发来的消息先进入 Gateway由它决定调用哪个模型、执行哪些本地技能再把结果原路返回。它本身不绑定任何一家模型厂商模型调用走的是 OpenAI 兼容协议这就给「统一 Key 管理」留出了空间。我这次要解决的场景很具体在一台 Linux 云服务器上跑 OpenClaw Gateway把 QQ 机器人接进来同时让所有模型调用都走 TaoToken 的统一 Key。为什么不用官方直连因为 OpenClaw 里会配置多个模型对话、生图、搜索摘要如果每个都单独申请 Key、单独记额度维护成本很高而统一 Key 的好处是——一个 Base URL、一个 Key、一个 Model ID 列表切换模型只改一个字段排查问题时也只需要看一处日志。适合谁跟做已经装好 Node.js 22、能在终端里跑命令、想让 QQ 机器人具备多模型能力的开发者。如果你还没装 OpenClaw本文的配置片段同样适用于任何 OpenAI 兼容客户端因为核心就是 Base URL Key Model ID 三件套。先说清楚链路QQ 开放平台把用户消息推送到你配置的回调地址OpenClaw Gateway 收到后按openclaw.json里的模型配置发起请求请求打到 TaoToken 的 API 端点模型返回内容再由 Gateway 回传给 QQ。整条链路里唯一需要你手动维护的凭证就是 TaoToken 的 Key。我实测下来最容易卡住的不是模型调用而是 QQ 插件加载和 Gateway 重启这两步。下面按「前置准备 → 配置片段 → 验证 → 排障」的顺序展开每一步都给可复制的命令和参数。2. TaoToken 统一 Key 前置准备与 OpenClaw 环境确认在动 OpenClaw 配置之前先把两件事做完拿到 TaoToken 的 Key确认 OpenClaw 的版本和插件目录。2.1 获取 TaoToken API Key访问 TaoToken 控制台创建 API Key路径是 console 页面下的 api-keys 管理。创建后你会得到一串以sk-开头的密钥这就是后面所有模型调用的唯一凭证。注意两点一是 Key 只在创建时完整显示一次复制后妥善保存二是不同模型共用同一个 Key不需要为每个模型单独申请。TaoToken 的 API 端点是https://taotoken.net/api这是 OpenAI 兼容协议的入口OpenClaw 里填 Base URL 时用这个地址注意不要带任何查询参数。模型对话功能可以在模型对话页面直接验证 Key 是否可用接入文档在 doc 页面有完整的参数说明。2.2 确认 OpenClaw 与 Node.js 版本OpenClaw 要求 Node.js 22 及以上。先确认版本node -v # 期望输出 v22.x.x 或更高如果版本不够用 nvm 切换nvm install 22 nvm use 22 nvm alias default 22然后确认 OpenClaw 已安装并能识别 Gatewayopenclaw --version openclaw gateway statusgateway status会告诉你网关是否在运行。如果显示未启动用openclaw gateway start拉起。这里有个细节OpenClaw 的配置文件默认在~/.openclaw/openclaw.json插件目录在~/.openclaw/plugins后面改配置和装 QQ 插件都围绕这两个路径。2.3 确认 QQ 机器人插件依赖QQ 接入依赖腾讯官方的tencent-connect/openclaw-qqbot插件。先看全局 npm 目录里有没有npm list -g tencent-connect/openclaw-qqbot如果没有输出或报错说明没装后面第 3 节会给安装命令。这里先记下全局 node_modules 的路径因为 OpenClaw 加载本地插件时需要绝对路径npm root -g # 例如输出 /www/server/nvm/versions/node/v22.22.2/lib/node_modules把这个路径记下来插件安装后完整路径就是npm root -g/tencent-connect/openclaw-qqbot。2.4 为什么用统一 Key 而不是多 KeyOpenClaw 的模型配置支持多个 provider每个 provider 有自己的 baseUrl 和 apiKey。如果对话用一家、生图用另一家配置里就会出现多组凭证。统一 Key 的做法是所有 provider 的 baseUrl 都指向https://taotoken.net/apiapiKey 都填同一个 TaoToken Key只是 model 字段不同。这样切换模型时只改 model不动凭证额度、限流、日志也集中在一处看。对于长期跑 Agent 任务的场景建议配合 Coding Plan 使用因为 Agent 会频繁发起多轮请求统一计费比分散申请更可控。如果你只是想先验证模型能不能通用模型对话页面手动发一条消息最快。3. 可复制的 OpenClaw Gateway 与 QQ 回调配置片段这一节是全文的核心所有片段都可以直接复制。配置分三块OpenClaw 的模型配置、QQ 插件安装、QQ 开放平台侧的回调参数。3.1 openclaw.json 模型配置片段打开~/.openclaw/openclaw.json找到models或providers字段不同版本字段名略有差异以你本地文件为准。把模型 provider 改成下面这样{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5, contextWindow: 200000 }, { id: gpt-4o-mini, name: GPT-4o mini, contextWindow: 128000 } ] } }, defaultModel: claude-sonnet-4-5 }三个关键字段对照字段值说明baseUrlhttps://taotoken.net/apiOpenAI 兼容入口不带查询参数apiKeysk-开头TaoToken 控制台创建的统一 Keymodel id如 claude-sonnet-4-5按需替换需与平台支持的模型 ID 一致注意baseUrl结尾不要加/v1OpenClaw 会自己拼接路径如果你本地版本要求带/v1以openclaw gateway status的报错为准调整。改完配置后必须重启网关openclaw gateway restart3.2 安装并加载 QQ 机器人插件先装插件如果npm install报网络或权限错误加-g全局安装npm install -g tencent-connect/openclaw-qqbot装完后用绝对路径加载到 OpenClawopenclaw plugins install /www/server/nvm/versions/node/v22.22.2/lib/node_modules/tencent-connect/openclaw-qqbot把路径替换成你npm root -g的实际输出。加载后确认openclaw plugins list列表里出现openclaw-qqbot就说明插件已识别。如果没出现检查路径是否指向插件根目录含package.json的那一层。3.3 QQ 开放平台回调参数进入 QQ 开放平台机器人列表扫码后创建机器人。创建完成后平台会给你三个关键参数AppID、AppSecret、Token。这三个值要填进 OpenClaw 的 QQ 插件配置里通常插件会引导你依次输入或者写入~/.openclaw/plugins/openclaw-qqbot/config.json{ appId: 你的AppID, appSecret: 你的AppSecret, token: 你的Token, sandbox: false }回调地址Webhook填你服务器的公网地址加插件默认路径例如https://你的域名/qqbot/callback。如果 Gateway 前面有反向代理确保代理把该路径转发到 OpenClaw 监听的端口。QQ 侧要求回调地址可公网访问且支持 HTTPS本地开发可以用内网穿透工具临时映射但生产环境建议直接部署在有证书的服务器上。3.4 三件套一致性检查配置完成后确认三件套在 OpenClaw 和 QQ 插件里是一致的Base URLhttps://taotoken.net/api模型调用Keysk-开头的 TaoToken Key模型调用Model IDclaude-sonnet-4-5或你选定的模型模型调用QQ 侧的 AppID/AppSecret/Token 是另一套凭证只用于 QQ 平台鉴权不要和 TaoToken Key 混用。两套凭证各管一段链路排查时要分清是哪一段出的问题。4. 验证一条消息从 QQ 到模型再返回配置写完不算完必须跑通一条完整消息。验证分两步先在 Gateway 本地验证模型调用再从 QQ 侧发真实消息。4.1 本地验证模型调用在终端里直接用 OpenClaw 的 TUI 发一条消息绕过 QQ 插件先确认模型链路通openclaw chat 用一句话介绍你自己如果返回了模型输出说明 Base URL、Key、Model ID 三件套正确。如果报 401说明 Key 无效或没生效如果报 model not found说明 Model ID 写错了。这一步通过后再测 QQ。4.2 从 QQ 发消息验证全链路在 QQ 里给机器人发一条消息比如「现在几点」或「帮我列一下当前目录」。观察三个地方第一OpenClaw Gateway 日志里应该出现收到 QQ 消息的记录openclaw gateway logs --follow第二日志里紧接着应该有向taotoken.net/api发起请求的记录包含 model 字段。第三QQ 里收到模型返回的回复。如果日志显示收到 QQ 消息但没有模型请求说明插件加载了但配置没生效检查openclaw plugins list和插件 config.json。如果日志显示模型请求发出但报错看错误码定位是 Key 问题还是模型 ID 问题。4.3 成功结果的判断标准一条消息完整跑通的标志是QQ 发出 → Gateway 日志出现 inbound → 日志出现 outbound 到 taotoken.net/api → QQ 收到回复。四个环节缺一不可。我实测时第一次卡在第三步日志显示请求发出但返回reading choices错误后来发现是模型 ID 写成了平台不支持的名称换成claude-sonnet-4-5后正常。验证通过后你可以给机器人设置身份和职责比如「你是我的运维助手只回答服务器相关问题」这些在 OpenClaw 的 agent 配置里改。长期跑任务的话建议把默认模型设成上下文窗口大的那个避免多轮对话被截断。5. 本篇常见错误排查401、local proxy failed、reading choices这一节按真实报错对照排查。以下错误都是我或身边朋友实际遇到过的按出现频率排序。5.1 401 Unauthorized现象本地openclaw chat或 QQ 消息返回 401。原因通常是三类Key 复制时带了空格或换行Key 已过期或被删除配置改了但没重启 Gateway。排查步骤先确认 Key 字符串首尾无空白再在模型对话页面手动发一条消息验证 Key 本身可用。如果页面能通但 OpenClaw 不通说明是配置没生效执行openclaw gateway restart后重试。还有一种情况是 baseUrl 写成了带/v1的地址导致路径重复改成https://taotoken.net/api即可。5.2 local proxy failed现象Gateway 日志出现local proxy failed或连接被拒绝。这个错误通常和网络出口有关。先确认服务器能访问taotoken.netcurl -I https://taotoken.net/api如果 curl 不通说明服务器网络策略或 DNS 有问题检查安全组出站规则和/etc/resolv.conf。如果 curl 通但 OpenClaw 报 proxy failed检查 OpenClaw 配置里有没有残留的 proxy 字段把它删掉让请求直连。注意不要在配置里填任何本地代理地址OpenClaw 直连 API 端点即可。5.3 reading choices 报错现象日志显示Cannot read properties of undefined (reading choices)。这是典型的响应结构不符合预期。原因一般是模型 ID 写错平台返回了错误对象而不是标准的 choices 数组。排查确认 model id 与平台支持的名称完全一致大小写敏感。另一个可能是 baseUrl 指向了非 OpenAI 兼容端点导致返回格式不对。把 baseUrl 固定为https://taotoken.net/apimodel 换成文档里列出的名称。5.4 OAuth 相关报错现象出现 OAuth token 失效或授权失败。OpenClaw 某些版本会用 OAuth 方式管理部分凭证。如果你混用了 OAuth 和 API Key 两种方式可能冲突。排查确认模型 provider 用的是 apiKey 字段而不是 oauth 字段如果之前配过 OAuth清掉相关缓存后重启。对于 TaoToken 统一 Key 方案全程用 apiKey 即可不需要 OAuth。5.5 QQ 插件加载失败现象openclaw plugins install报路径不存在或plugins list里没有 qqbot。先确认npm root -g输出的路径下确实有tencent-connect/openclaw-qqbot目录且目录里有package.json。如果 npm 装到了本地而非全局用-g重装。加载时路径要写到插件根目录不要写到node_modules上一层。加载成功后必须重启 Gateway 才能生效。5.6 配置改了不生效OpenClaw 的配置在 Gateway 启动时读取改完openclaw.json或插件 config.json 后必须openclaw gateway restart。如果重启后仍不生效检查是否有多个配置文件比如项目目录下还有一份以openclaw gateway status显示的配置路径为准。6. 统一 Key 管理多模型的后续用法与接入入口跑通 QQ 接入后统一 Key 的价值才真正体现出来。你可以在openclaw.json里配多个模型全部指向同一个 TaoToken Key然后按任务类型切换日常对话用轻量模型复杂推理用大上下文模型生图任务单独配一个模型 ID。切换时只改defaultModel字段不用动凭证。对于长期跑 Agent 的场景建议用 Coding Plan 管理额度因为 Agent 会发起大量多轮请求统一计费比分散申请更清晰。如果你需要更细的 Key 权限控制可以在 console 里创建多个 Key 分别用于不同环境但 Base URL 和 Model ID 的对应关系保持不变。接入过程中如果遇到本文没覆盖的报错优先查接入文档里面有完整的参数说明和错误码对照。验证模型是否可用直接用模型对话页面发消息最快不用每次都重启 Gateway。需要新建或轮换 Key 时去 api-keys 页面操作轮换后记得同步更新openclaw.json并重启网关。最后给一个实用技巧把openclaw gateway logs --follow常驻在一个终端窗口QQ 侧发消息时实时看日志能第一时间定位是 QQ 插件、Gateway 还是模型调用出的问题。三段链路分开看排查效率会高很多。
