1. 为什么要在 QQ 里接一个 AI 智能体OpenClaw 是一个可以长期常驻运行的 AI 智能体网关它能对接多种大语言模型并把你平时用的即时通讯软件变成 AI 的入口。简单说你不需要每次都打开网页或终端直接在 QQ 里发一句话背后的智能体就能帮你整理邮件、生成周报、查资料甚至写代码。它适合需要把即时通讯平台接入 AI 能力的开发者也适合想给自己或小团队搭一个「随叫随到助手」的人。我这次要落地的是 OpenClaw 连接 QQ 的完整配置。整条链路分两段一段在 QQ 开放平台侧创建机器人、拿 AppID 和 AppSecret、配 IP 白名单、加沙箱成员另一段在 OpenClaw 侧装 QQ 插件、写 config.toml 或 settings.json、重启网关、验证消息收发。中间还有一个容易被忽略的环节——模型通道。OpenClaw 本身只是网关真正回你消息的是背后的大模型所以我会用 TaoToken 的统一 Key 和 API 通道把模型这一层也一起打通这样你只需要维护一份凭证不用在多个平台之间来回切换。下面按「先备料、再配置、后验证、最后排障」的顺序走每一步都给可复制的命令和配置骨架。你照着做基本能一次跑通。2. 前置准备OpenClaw 环境与 TaoToken 统一 Key2.1 OpenClaw 服务状态确认先确认你的 OpenClaw 已经正常部署。云端部署建议不低于 2 核 2GB 内存、40GB 存储这个配置跑 QQ 消息交互绰绰有余。Windows 和 Linux 的检查方式不同# Windows 查看服务状态 openclaw status # Linux 查看服务状态 systemctl status openclaw # 容器化部署查看 docker ps | grep openclaw记录三个关键信息服务器公网 IP、OpenClaw 端口默认 18789、OpenClaw 访问 Token控制台可查。公网 IP 后面配 QQ 白名单要用端口要确保安全组放行。2.2 为什么用 TaoToken 统一 KeyOpenClaw 支持多种模型来源但如果你每个模型都单独配一套 Key配置文件会变得很难维护。TaoToken 提供统一的 API 通道你只需要一个 Key就能在 OpenClaw 里切换不同模型。它的 API 地址是https://taotoken.net/api兼容常见的 OpenAI 风格调用方式填进 OpenClaw 的模型配置里即可。先去控制台创建一个 API Key位置在 API Keys 页面。创建后复制保存这个 Key 就是后面 config.toml 里api_key字段要填的值。如果你还没决定用哪个模型可以先到模型对话页面试几条消息确认通道正常再写进配置。2.3 QQ 开放平台凭证QQ 开放平台账号和普通 QQ 号是两套体系不能直接用 QQ 号登录需要单独注册并完成实名认证。注册流程包括邮箱验证、超级管理员信息填写、人脸认证通过后登录平台。登录后进入「机器人」页签创建机器人填名称、简介、头像。创建完成后进入管理页面左侧「开发管理」里点「生成」验证管理员身份后拿到两个核心凭证AppID机器人 IDAppSecret机器人密钥首次查看后务必保存关闭后无法再次查看然后在同一页面的 IP 白名单模块点「编辑」填入 OpenClaw 部署服务器的公网 IP。这一步不做后面调用 QQ 机器人 API 会直接失败。如果你部署在家里本机没有固定公网 IP需要先查当前宽带的公网出口 IP 再填内网地址如 192.168.x.x 是无效的因为 QQ 服务器访问不到你的内网。最后进「沙箱配置」点「添加成员」把要跟机器人聊天的 QQ 号加进去被添加的成员用手机 QQ 扫码确认。目前 QQ 机器人的群聊配置处于系统维护状态只支持单聊这点先接受别在群聊上浪费时间。3. 可复制配置config.toml 与 settings.json 骨架3.1 安装并启用 QQ 插件先看插件列表里有没有 QQ 相关插件openclaw plugins list2026 年 2 月 1 日之后的版本一般已预装 QQ 插件。如果没有手动安装# 进入 OpenClaw 根目录 cd C:\Users\Surface\.openclaw # 安装到本地 npm install sliverp/qqbotlatest # 查看是否安装成功 dir node_modules\sliverp # 创建 extensions 目录 mkdir C:\Users\Surface\.openclaw\extensions -Force # 复制插件到 extensions无管理员权限时用复制方式 Copy-Item -Recurse C:\Users\Surface\.openclaw\node_modules\sliverp\qqbot C:\Users\Surface\.openclaw\extensions\qqbot # 启用插件 openclaw plugins enable qqbot3.2 config.toml 模型通道配置OpenClaw 的模型通道写在 config.toml 里把 TaoToken 的 API 地址和 Key 填进去。下面是一个可复制的骨架注意把api_key换成你自己的[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model claude-3-5-sonnet [channels.qqbot] enabled true app_id 你的QQ AppID app_secret 你的QQ AppSecret markdown_support falsemarkdown_support false这一行很关键。QQ 机器人默认不允许发送原生 markdown如果不关掉发消息时会报不允许发送原生 markdown的错误后面排障章节会细说。3.3 settings.json 通道配置如果你用的是 JSON 配置方式结构对应如下{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-3-5-sonnet }, channels: { qqbot: { enabled: true, appId: 你的QQ AppID, appSecret: 你的QQ AppSecret, markdownSupport: false } } }两种配置方式选一种即可不要同时改否则容易出现字段覆盖。改完保存重启网关openclaw gateway restart # 查看 QQ 通道状态 openclaw channels status看到connected或running就说明通道起来了。4. 验证请求从 QQ 发消息到日志确认4.1 基础对话验证打开手机 QQ找到已添加的机器人好友发一句「你好」或「自我介绍」。如果机器人以 AI 方式回复说明模型通道和 QQ 通道都通了。这一步同时验证了两件事TaoToken 的 Key 有效QQ 凭证和白名单正确。4.2 查看实时日志在服务器上开一个终端实时看日志openclaw logs当你在 QQ 发消息时日志里应该出现收到消息并处理的记录。如果看到QQ机器人凭证验证通过、通道连接成功这类信息基础对接就完成了。4.3 进阶功能测试基础对话通了之后可以试更复杂的指令确认模型能力也正常测试类型示例指令预期效果文档生成帮我生成一份工作周报模板输出周报格式文件解析发送 Word 文档并说解析这份会议纪要提取核心要点定时提醒每天早上 9 点提醒我打卡设置定时任务并推送信息查询帮我查一下今天的天气返回天气信息如果这些都能正常返回说明整条链路从 QQ 到 OpenClaw 再到 TaoToken 模型通道全部打通。5. 本篇常见报错排查5.1 不允许发送原生 markdown这是 QQ 集成里最常见的报错日志长这样[qqbot-api] Body: {message:不允许发送原生 markdown,code:40034012} [qqbot] Failed to send markdown message: API Error [/v2/users/xxx/messages]: 不允许发送原生 markdown原因是 QQ 机器人接口不接受原生 markdown 格式。解决办法是关掉 markdown 支持openclaw config set channels.qqbot.markdownSupport false openclaw gateway restart重启后再发消息机器人会用纯文本回复报错消失。5.2 机器人无响应发消息后完全没回复按下面顺序排查现象可能原因解决方法无任何回复IP 白名单未配置检查 QQ 开放平台白名单是否加了服务器公网 IP无任何回复沙箱成员未添加确认测试 QQ 号已在沙箱配置中添加无任何回复AppID/AppSecret 错误重新获取凭证并更新配置无任何回复网关未重启执行 openclaw gateway restart5.3 连接失败与端口检查# 检查通道状态 openclaw channels status # 查看详细错误日志 openclaw channels logs # 检查端口是否放行 netstat -an | findstr 18789如果端口没监听说明网关没起来如果端口在监听但通道状态异常重点看channels logs里的凭证报错。5.4 消息延迟或丢失设置消息防抖时长建议 1 到 3 秒避免重复接收同一条消息。同时检查服务器网络带宽是否充足确认 OpenClaw 版本在 2026.1.24-3 及以上。版本过低可能缺少 QQ 通道的稳定性修复。5.5 凭证与账号类问题AppSecret 丢失了在机器人开发管理页面重新生成即可但新密钥生效后旧密钥会失效记得同步更新 config.toml。QQ 开放平台登录失败多半是因为用 QQ 号直接登录它需要先完成独立注册和绑定流程。想在 QQ 群里用机器人目前开放平台暂不支持群配置只能单聊。6. 把模型通道固定下来后续少折腾配置跑通之后建议把模型通道这一层固定住。OpenClaw 的 QQ 通道本身不复杂真正容易出问题的是模型凭证散落在多处。用 TaoToken 的统一 Key 之后你只需要在 config.toml 里维护一个api_key和base_url换模型时改model字段就行不用动 QQ 那边的任何配置。如果你后面要做长期编码或 Agent 类任务可以了解下 Coding Plan它更适合高频调用场景。日常调试模型回复效果直接在模型对话里试比在 QQ 里试更快。接入过程中遇到凭证或通道报错先到 API Keys 页面确认 Key 状态再对照接入文档检查字段名大部分问题都能定位到具体配置项。整套流程走下来核心就三件事QQ 开放平台把凭证和白名单配好OpenClaw 把插件和通道配好TaoToken 把模型通道配好。三处都对了QQ 里发一句话AI 就能接住。