1. 为什么 OpenClaw 接 QQ Bot 总卡在配置这一步OpenClaw 是一个把大模型能力接到聊天通道里的网关型工具你可以把它理解成一个「消息路由器」QQ 那边来一条消息它负责转给模型再把模型的回复送回 QQ。它适合想自己搭一个 QQ 机器人、又不想从零写消息协议的人。而 QQ Bot 接入是 OpenClaw 里最容易被配置文件劝退的环节——settings.json 和 config.toml 两个文件、字段名对不上、Key 不知道往哪塞跑起来日志一片红。我实测下来绝大多数失败不是代码问题而是配置骨架没搭对要么通道没启用要么模型通道的 Key 写错了位置要么 QQ 侧的回调地址和本地端口对不上。这篇就聚焦「配置落地」这一件事给你两份可以直接复制的配置骨架再走一遍从启动到消息回传的完整验证。核心思路是把模型调用统一收敛到一个 Key 通道上OpenClaw 只认这一个出口QQ Bot 只负责收发职责分清之后排查就简单了。下面所有配置都以本地调试为前提端口、路径你按自己环境改。涉及模型通道的部分我用 TaoToken 作为统一出口来演示因为它一个 Key 能覆盖多种模型省得你在配置里堆一堆不同厂商的 Key。2. 前置准备统一 Key 通道与 OpenClaw 环境在动配置文件之前先把两件事准备好OpenClaw 本体以及一个能用的统一 Key。OpenClaw 的安装按官方方式走即可Node.js 建议 v20 以上npm install -g openclaw openclaw --version装完先别急着配 QQ先确认网关能起来openclaw gateway status如果提示未初始化跑一次openclaw gateway start让它生成默认目录配置文件一般落在~/.openclaw/config/下。接着是 Key。TaoToken 的定位是统一模型通道你注册后在控制台创建一个 API Key后面 OpenClaw 里所有模型请求都走这个 Key。创建入口在这里控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完在 API Keys 页面能看到以sk-开头的字符串复制保存。接口基址用https://taotoken.net/api注意这个地址后面不加任何参数。如果你对可用模型和调用方式还不熟可以先去模型对话页面试一条模型对话体验https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite环境层面还有两个容易忽略的点。一是 QQ Bot 侧通常需要一个能接收 HTTP 回调或 WebSocket 的本地服务本地调试时确保端口没被占用二是如果你用 NapCat 这类框架做 QQ 侧适配它和 OpenClaw 是两个进程配置里要写清楚谁连谁。这两点后面配置里都会体现。3. 可复制配置settings.json 与 config.toml 骨架OpenClaw 的配置分两层config.toml管网关和通道settings.json管模型通道和运行时参数。很多人只改了一个文件结果模型通道没生效消息进来了但回不出去。先看config.toml路径一般是~/.openclaw/config/config.toml# ~/.openclaw/config/config.toml [gateway] host 127.0.0.1 port 8765 debug true log_level info # QQ Bot 通道本地调试用 napcat 适配 [channels.qqbot] enabled true type napcat auto_reply true [channels.qqbot.endpoint] host 127.0.0.1 port 3000 ws_path /onebot/v11/ws [channels.qqbot.account] uin 你的QQ号 # 模型通道统一指向 TaoToken [models] default taotoken/glm-4.7 reasoning taotoken/glm-4.7 provider taotoken base_url https://taotoken.net/api几个字段说明一下。type napcat表示 QQ 侧走 NapCat 的 OneBot v11 协议ws_path是 WebSocket 路径NapCat 默认就是/onebot/v11/ws如果你改过要同步。base_url固定写https://taotoken.net/api不要带斜杠结尾之外的任何东西。再看settings.json路径一般是~/.openclaw/config/settings.json{ runtime: { logLevel: info, sessionDir: ~/.openclaw/sessions }, modelChannel: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, defaultModel: glm-4.7, timeoutMs: 60000 }, channels: { qqbot: { enabled: true, replyPrefix: , maxReplyLength: 1500 } } }apiKey就是你在控制台创建的那串sk-开头的 Key。timeoutMs给到 60 秒模型推理慢的时候不至于被网关提前掐断。maxReplyLength是防止模型输出太长把 QQ 消息撑爆1500 字符对大多数场景够用。如果你更习惯用环境变量管理密钥可以把apiKey留空改成在启动前导出export TAOTOKEN_API_KEYsk-你的密钥然后在settings.json里把apiKey写成${TAOTOKEN_API_KEY}。这样配置文件可以进版本库密钥不落地。4. 启动与消息回传验证配置写完按顺序启动。先起 QQ 侧适配以 NapCat 为例再起 OpenClaw 网关。# 终端 1启动 NapCat cd ~/NapCatQQ npm start # 终端 2启动 OpenClaw 网关 openclaw gateway start openclaw gateway statusgateway status正常会显示 running 和版本号。接着看日志确认 QQ 通道连上了openclaw gateway logs --tail50你要找的关键行是类似QQBot connected: accountxxxxx和model channel ready: taotoken。前者说明 QQ 侧握手成功后者说明模型通道的 Key 被正确加载。两条都出现链路基本就通了。然后做消息回传验证。用另一个 QQ 号给机器人发一条消息比如「你好」。预期流程是NapCat 收到消息 → 通过 WebSocket 推给 OpenClaw → OpenClaw 调 TaoToken 的模型接口 → 拿到回复 → 原路返回 QQ。如果几秒内收到回复说明整条链路跑通。想更精确地确认模型调用没问题可以单独打一条接口请求绕开 QQ 直接验证 Key 通道curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d { model: glm-4.7, messages: [{role: user, content: 只回复两个字收到}] }返回里有正常的choices结构就说明 Key 和基址都对。这一步能帮你快速区分「是模型通道的问题」还是「是 QQ 通道的问题」——如果 curl 通但 QQ 不回问题一定在 QQ 侧配置。5. 本篇常见错排查配置跑不通时按下面几个高频点对号入座基本能覆盖八成情况。网关起不来端口被占。报错通常是address already in use。查一下 8765 被谁占了lsof -i :8765要么杀掉占用进程要么把config.toml里的gateway.port改成别的。QQ 通道连不上日志刷重连。先确认 NapCat 的 WebSocket 服务真的在监听curl http://127.0.0.1:3000/status如果这个都不通说明 NapCat 没起来或端口不对跟 OpenClaw 无关。通了但 OpenClaw 还连不上检查ws_path是否和 NapCat 配置一致OneBot v11 默认是/onebot/v11/ws。消息进来了但机器人不回。这种多半是模型通道没生效。看日志里有没有model channel ready没有的话就是settings.json的apiKey没读到。常见原因是 Key 写成了占位符没替换或者用了环境变量但启动终端没导出。另外确认base_url是https://taotoken.net/api多写或少写路径都会 404。返回 401 或鉴权失败。Key 本身的问题。去控制台确认 Key 没被删、没超额重新复制一次。注意别把 Key 前后的空格带进去。回复超时。把timeoutMs调大同时看是不是模型选了个响应慢的。本地调试阶段先用默认模型验证链路别一上来就上重推理模型。改了配置不生效。OpenClaw 不会热加载所有字段改完config.toml或settings.json后要重启网关openclaw gateway restart这一步很多人忘改完直接测结果测的还是旧配置。6. 把 Key 通道固定下来后面就省心了配置这件事一次搭对骨架后面加通道、换模型都是小改。我的建议是把模型出口统一收敛到 TaoToken 这一个 Key 上OpenClaw 里只维护一份base_url和apiKeyQQ Bot 侧只管收发消息。这样出问题时排查路径很短curl 通不通决定是不是模型通道的锅日志里有没有 connected 决定是不是 QQ 侧的锅。如果你后面要长期跑编码类或 Agent 类任务单次调用按量计费可能不如包月划算可以看看 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入过程中遇到鉴权、通道字段这类具体报错对照接入文档查字段定义最快接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteKey 管理和新建入口在 API Keys 页面API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后留一个我踩过的坑本地调试时gateway.host别急着写0.0.0.0先用127.0.0.1把链路跑通确认没问题再放开监听范围否则端口暴露出去又没配鉴权容易出意外。配置骨架就这两份文件复制过去改掉 QQ 号和 Key重启网关发条消息链路就活了。