1. 从零搭建 QQ 机器人时最容易卡住的三个环节OpenClaw 是一个把大模型能力接到即时通讯渠道里的智能体网关你可以把它理解成一个“消息路由器 模型调度器”QQ 用户发来的消息先到 OpenClawOpenClaw 再决定调用哪个模型、用哪套提示词、返回什么内容。它适合想给自己的社群、客服号或兴趣群做自动化助手的开发者也适合已经在用 Claude Code、Codex 这类编码工具、想顺手把 AI 能力延伸到 QQ 场景的人。但真正动手时第一次搭建的人往往不是卡在“模型不会用”而是卡在三个很具体的地方AppID 申请下来后不知道哪些字段要填进配置、插件装完了openclaw channels里看不到 qqbot、配置文件写对了但机器人上线后消息不回传。这篇就按“申请凭证 → 装插件 → 写配置 → 启动验证 → 排错”的顺序走一遍配置片段可以直接复制路径和字段名保持和实际一致。需要提前说明的是QQ 开放平台的机器人创建、实名认证、IP 白名单这些属于平台侧操作按官方控制台提示走即可本文重点放在 OpenClaw 侧的插件安装、配置文件骨架和验证动作上。另外如果你后续要接多个模型或多个渠道调用凭证会越来越多建议从一开始就用统一通道管理后面会讲到怎么用 TaoToken 把 Key 和 API 地址收敛到一处。先确认环境OpenClaw 服务已能正常启动服务器有公网 IP默认端口 18789 已放行Node.js 与包管理器版本满足插件要求。QQ 侧需要一个完成实名认证的账号用于在开放平台创建机器人并拿到 AppID 与 AppSecret。这两样东西是后面所有配置的核心先拿到手再往下走。2. TaoToken 前置把模型调用凭证统一收口在写 QQ 机器人配置之前先把模型这一侧的凭证理清楚。OpenClaw 本身是网关它要真正回复消息得能调到一个模型服务。很多人第一次搭的时候模型 Key 直接硬编码在配置里接第二个渠道时又复制一份结果 Key 散落在三四个文件里改一次要翻半天。我的做法是先把模型通道统一到一个入口再让 OpenClaw 指向这个入口。TaoToken 在这里扮演的就是“统一 Key / API 通道”的角色。你可以在它的控制台里创建 API Key然后把 OpenClaw 的模型请求地址指向https://taotoken.net/api模型 ID 按你实际要用的填。这样做的直接好处是QQ 机器人、编码工具、其他渠道共用同一套凭证换模型或轮换 Key 时只改一处不用每个配置文件都动一遍。具体操作路径是这样先到控制台创建 API Key地址是https://taotoken.net/console创建完在 API Keys 页面复制出来页面是https://taotoken.net/api-keys。如果你不确定该用哪个模型 ID可以先去模型对话页面试一下地址https://taotoken.net/chat确认模型能正常返回再写进配置。接入文档在https://taotoken.net/doc字段含义和请求格式以文档为准。这里有个容易忽略的点OpenClaw 的模型配置和渠道配置是两套东西。渠道配置qqbot负责“消息怎么进来、怎么出去”模型配置负责“消息交给谁处理”。两者都写对机器人才能完整跑通。所以下面第 3 节的配置片段里我会把模型侧的 Base URL、Key、Model ID 和渠道侧的 AppID、AppSecret 放在一起讲避免你只配了一半。如果你打算长期跑编码类或 Agent 类任务比如让 QQ 机器人背后接一个能写代码、能调工具的智能体可以了解一下 Coding Plan地址https://taotoken.net/coding-plan。它的定位是给长期编码和 Agent 场景用的套餐和按量调用是两种思路按自己的使用频率选就行。凭证准备好之后进入下一节的配置文件环节。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文最需要照着做的地方。OpenClaw 的配置分两层一层是网关主配置通常是~/.openclaw/config.toml另一层是渠道或插件的 settings常见为~/.openclaw/settings.json或插件目录下的配置文件。不同版本路径可能略有差异以你本地openclaw config path输出为准但字段结构是一致的。先装插件。Linux / Mac 用户走 npm 方式openclaw plugins install openclaw-china/channels openclaw china setupWindows 用户如果 npm 装完识别不到可以走源码方式git clone https://github.com/BytePioneer-AI/openclaw-china.git cd openclaw-china pnpm install pnpm build openclaw plugins install -l ./packages/channels装完先别急着启动把配置写好。下面是config.toml的骨架重点是模型段和渠道段要同时存在# ~/.openclaw/config.toml [model] # 统一走 TaoToken 的 API 通道 base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_id 你的模型ID [gateway] port 18789 host 0.0.0.0 [channels.qqbot] enabled true app_id 你的AppID client_secret 你的AppSecret对应的settings.json里放渠道策略和插件级参数路径按你实际安装位置调整{ channels: { qqbot: { enabled: true, appId: 你的AppID, clientSecret: 你的AppSecret, dmPolicy: open, groupPolicy: allowlist, requireMention: true } }, plugins: { channels: { qqbot: { sandbox: true } } } }字段说明用表格对照更清楚字段作用建议值base_url模型请求地址https://taotoken.net/apiapi_key模型调用凭证控制台创建的 Keymodel_id使用的模型按实际填写app_idQQ 机器人唯一标识开放平台复制client_secretQQ 机器人密钥开放平台复制dmPolicy私聊策略open / pairing / allowlistgroupPolicy群聊策略open / allowlist / disabledrequireMention群聊是否需 true 更安全注意app_id和client_secret属于敏感信息不要提交到公开仓库。建议用环境变量注入或在部署时用密钥管理服务替换。配置写完后重启网关openclaw gateway restart openclaw channelsopenclaw channels的输出里qqbot 那一行状态应该是 running。如果显示 stopped 或根本没出现先别怀疑模型去第 5 节对照报错排查。配置这一步的核心原则是模型段和渠道段都要有字段名大小写要和插件读取的一致config.toml用下划线、settings.json用驼峰这是很多人第一次踩的坑。4. 启动后验证机器人上线与消息回传配置写完、网关重启完接下来要验证两件事机器人是否真的上线以及消息能不能回传。这两步分开测出问题时才好定位。先看通道状态。执行openclaw channels正常输出类似NAME STATUS TYPE qqbot running channel如果 qqbot 是 running说明插件加载成功、凭证被读取到了。这一步只证明“通道起来了”不证明“消息能通”。接着做上线验证在 QQ 开放平台的沙箱配置里把测试用的 QQ 号加为成员然后用这个号添加机器人为好友。添加成功后机器人应该出现在好友列表里这是“上线”的直观标志。然后测消息回传。先发一条最简单的你好如果机器人回复了内容说明“QQ → OpenClaw → 模型 → OpenClaw → QQ”整条链路通了。如果没回复先用命令行直接测通道绕开 QQ 客户端openclaw message send 测试消息 --to qq:private:你的QQ号这条命令如果能在 QQ 里收到消息说明出站通道没问题问题在入站消息进不来如果这条也收不到说明凭证或白名单有问题。再测模型侧是否正常可以单独发一次模型请求确认base_url和api_key有效。把“通道”和“模型”分开验证是排障时最省时间的做法。群聊场景要多一步默认requireMention true时群里必须 机器人才会触发。测试时在群里发机器人 你好看是否有回复。如果私聊通、群聊不通八成就是这个配置在起作用不是故障。沙箱环境下建议先把私聊跑通再开群聊变量少、好定位。验证通过后建议做一次“冷启动复测”把网关停掉再启动重新执行openclaw channels和发消息确认配置是持久化的、不是靠某次交互式命令临时生效的。很多人第一次配完能用重启服务器后就失效就是因为配置只写在了内存或临时文件里没落到config.toml和settings.json。5. 常见报错排查401、local proxy failed 与 choices 读取失败这一节按真实会遇到的报错来对。先记住一个原则报错信息里出现401、unauthorized、invalid api key这类词基本是模型凭证问题出现local proxy failed、connection refused、timeout基本是网络或地址问题出现reading choices、undefined is not an object基本是返回结构不符合预期通常是模型 ID 或接口地址不对。报错现象可能原因处理方式401 UnauthorizedKey 错误或过期重新在控制台创建 Key更新api_keylocal proxy failed地址不通或端口未放行检查base_url、服务器出网、18789 端口reading choices of undefined返回体不是预期结构核对model_id与接口地址是否匹配OAuth / token 相关报错凭证类型用错确认用的是 API Key 而非其他凭证qqbot 状态 stopped插件未加载或字段名错重装插件核对大小写机器人无响应IP 白名单未配把服务器公网 IP 加入白名单群聊无反应未 机器人群里 机器人或调requireMention重点说三个。第一个是401最常见的原因是 Key 复制时带了空格或者用了已经轮换掉的旧 Key。处理方式是到https://taotoken.net/api-keys重新创建一个粘贴时注意首尾不要有空白字符。第二个是local proxy failed这个报错容易让人以为是代理问题其实多数是base_url写错或服务器出网受限。确认地址是https://taotoken.net/api然后在服务器上直接curl一下这个地址看是否有响应。第三个是reading choices这个报错说明请求发出去了、也收到响应了但响应体里没有choices字段通常是model_id填了一个不存在的模型或者接口路径不对。回到模型对话页面确认模型可用再填回配置。还有一个和 QQ 侧强相关的机器人提示“去火星了”或完全无响应先查 IP 白名单。开放平台只允许白名单内的 IP 调用服务器换了公网 IP 后如果没更新白名单就会表现为无响应。这个不是 OpenClaw 的问题但排查时很容易绕远路。如果你用的是 Claude Code 这类工具配合 OpenClaw凭证配置要写全三件套Base URL、Key、Model ID缺一个都可能报 OAuth 或鉴权类错误。Base URL 用https://taotoken.net/apiKey 用控制台创建的Model ID 按实际填。三样对齐之后鉴权类报错基本会消失。6. 凭证管理与后续接入建议把机器人跑通只是第一步后面真正费时间的是凭证和配置的维护。我的经验是模型凭证和渠道凭证分开管理模型侧统一走一个入口渠道侧按平台各自配置。这样换模型时不动渠道换渠道时不动模型两边解耦。模型侧的统一入口就是前面说的 TaoToken。控制台在https://taotoken.net/consoleAPI Keys 在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc。需要试模型效果就去模型对话页面https://taotoken.net/chat。如果你后面要接的不只是 QQ还有别的渠道或编码工具这套统一凭证的价值会更明显——不用每个工具都配一遍 Key。渠道侧的建议是app_id和client_secret不要写死在代码里用环境变量或部署平台的密钥管理注入。沙箱环境和正式环境的凭证分开测试时用沙箱上线前再切正式。IP 白名单变更后记得同步更新服务器迁移时这是最容易漏的一步。最后给一个实用技巧把openclaw channels和一次命令行发消息做成一个自检脚本每次改完配置跑一遍。通道状态 出站消息两条都过基本就说明配置没写坏。这比每次手动去 QQ 里发消息快得多尤其是在反复调groupPolicy、requireMention这些参数的时候。需要长期跑编码或 Agent 类任务的话可以看看 Coding Plan地址https://taotoken.net/coding-plan按自己的调用频率决定是否合适。凭证和配置都稳定之后QQ 机器人就可以从沙箱切到正式环境交给真实用户用了。
