PicoClaw 接入 QQ 开放平台机器人：官方 API 配置、部署与源码解析-北京尧图网络

人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载导读本文围绕 PicoClaw 的 QQ 渠道展开讲解如何通过 QQ 开放平台的官方机器人 API让 PicoClaw 以机器人身份接入 QQ实现私聊与群聊场景下的智能对话。读完本文你将掌握 QQ 渠道的完整配置方法含全部可调参数与环境变量、从开放平台创建机器人的快捷与手动两条路径并理解消息收发、媒体上传、去重与 URL 消毒等底层实现原理可直接基于当前仓库落地一套可运行的 QQ 机器人。QQ 渠道概述PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持详见 docs/channels/qq/README.zh.md 与 docs/channels/qq/README.pt-br.md。与通过 OneBot 等第三方协议中转的方案不同该渠道直接对接 QQ 开放平台的官方接口机器人与 QQ 服务器之间使用官方 WebSocket 长连接通信私聊消息C2C与群聊消息GroupAT均被支持。在仓库中的实现位于 pkg/channels/qq 包底层使用腾讯官方 Go SDKgithub.com/tencent-connect/botgo核心代码见 qq.go渠道工厂注册见 init.go。配置详解完整配置示例以下配置片段来自仓库的 config/config.example.json第 138147 行是 QQ 渠道在当前项目中的标准写法——渠道公共字段位于channel_list.qq顶层渠道特有参数位于settings子对象中{ channel_list: { qq: { enabled: false, type: qq, allow_from: [], reasoning_channel_id: , settings: { app_id: YOUR_QQ_APP_ID, app_secret: YOUR_QQ_APP_SECRET } } } }启用时只需将enabled改为true并填入真实凭证。原文档 README.pt-br.md 给出的是将app_id、app_secret直接平铺在qq对象下的简化写法实际项目以settings嵌套格式为准两种写法在语义上一致。参数说明字段类型必填描述enabledbool是是否启用 QQ Channeltypestring是渠道类型固定为qq用于配置校验与工厂分发app_idstring是QQ 机器人应用的 App IDapp_secretstring是QQ 机器人应用的 App Secretallow_fromarray否用户 ID 白名单空数组表示允许所有用户reasoning_channel_idstring否推理/思考内容推送目标会话 ID如某个群 ID仅用于出站路由group_triggerobject否群消息触发规则如mention_only等max_message_lengthint否单条消息最大长度max_base64_file_size_mibint否本地文件转 base64 上传的最大体积单位 MiB0表示不限制。仅影响本地文件不影响 URL 直传send_markdownbool否出站消息是否使用 Markdown 消息类型msg_type2发送其中allow_from、reasoning_channel_id、group_trigger等公共字段的定义可参见 config_channel.go 中的Channel结构体QQ 特有的app_id、app_secret、max_message_length、max_base64_file_size_mib、send_markdown定义于 config.go 的QQSettings结构体。环境变量与密钥安全QQ 渠道的每个设置项均提供了对应的环境变量覆盖方式见 config.go 中的env标签环境变量对应字段PICOCLAW_CHANNELS_QQ_APP_IDapp_idPICOCLAW_CHANNELS_QQ_APP_SECRETapp_secretPICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTHmax_message_lengthPICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIBmax_base64_file_size_mibPICOCLAW_CHANNELS_QQ_SEND_MARKDOWNsend_markdown注意app_secret在配置系统中被声明为SecureString类型config.go属于敏感字段它会被安全地脱敏存储在普通配置输出中不会以明文出现相关加密/脱敏逻辑可参考 pkg/config/security.go 及其测试 security_integration_test.go。设置流程快捷方式推荐QQ 开放平台提供了一键创建入口适合快速体验打开 QQ 机器人快速创建页面文档原文链接为https://q.qq.com/qqbot/openclaw/index.html扫码登录系统自动创建机器人复制App ID和App Secret将凭证填入 PicoClaw 配置文件config/config.example.json中的channel_list.qq块运行picoclaw gateway启动服务打开 QQ与机器人开始对话。注意App Secret 仅显示一次请立即保存再次查看将强制重置。通过快捷入口创建的机器人仅供创建人使用暂不支持群聊。如需群聊功能请在 QQ 开放平台配置沙箱模式。手动创建使用 QQ 账号登录 QQ 开放平台注册开发者账号创建 QQ 机器人自定义头像和名称在机器人设置中获取App ID和App Secret将凭证填入 PicoClaw 配置文件运行picoclaw gateway启动服务在 QQ 中搜索你的机器人开始对话。开发阶段建议开启沙箱模式将测试用户和群添加到沙箱中进行调试。启动命令与验证配置完成后执行picoclaw gateway即可启动网关含 QQ 渠道。该子命令定义于 cmd/picoclaw/internal/gateway/command.go描述为 Start picoclaw gateway支持通过参数覆盖网关绑定地址与日志级别。启动 QQ 渠道时核心的Start()流程qq.go会依次完成凭证校验若app_id或app_secret为空直接返回错误QQ app_id and app_secret not configured创建凭证源基于token.QQBotCredentials构建QQBotTokenSource并启动独立的 token 自动刷新协程初始化 OpenAPI 客户端botgo.NewOpenAPI(appID, tokenSource).WithTimeout(5 * time.Second)注册事件处理器handleC2CMessage()私聊与handleGroupATMessage()群消息两个处理器被注册进 intent建立 WebSocket 连接先通过api.WS()获取分片shards信息再由sessionManager.Start()在后台协程中启动长连接启动去重清理协程并将reasoning_channel_id预注册为群聊类型以便出站路由正确。启动成功后日志输出QQ bot started successfully。源码实现原理消息收发与路由QQ 渠道在消息层面实现了两种会话类型私聊C2C与群聊GroupAT。chatType这个sync.Map记录了每个chatID是group还是directqq.go。未知会话默认按群聊处理因为群 ID 更常作为纯出站目标如reasoning_channel_id出现。发送消息时Send()qq.go代码先根据会话类型选择PostGroupMessage或PostC2CMessage若send_markdown开启则消息类型切换为dto.MarkdownMsgmsg_type2并清空纯文本字段以避免重复发送。收到私聊/群消息时处理器会先做去重校验与发送者白名单校验IsAllowedSender再提取文本与附件最后构造InboundContext交给 BaseChannel 统一分发qq.go。群消息 URL 消毒QQ 平台对群消息存在 URL 黑名单限制直接发送带点的域名可能被拒绝。因此对于群聊出站消息代码中的sanitizeURLs()qq.go会用正则匹配带http(s)://前缀的 URL将域名部分的英文句点替换为全角句号。而路径与参数保持不变——这样既能绕过黑名单又不破坏链接可读性。该处理仅作用于群消息且只匹配带显式协议的 URL避免误伤版本号之类的裸文本。媒体发送两步上传流程QQ 渠道实现了channels.MediaSender接口群/私聊媒体发送是典型的两步流程qq.go上传媒体向/v2/groups/{id}/files或/v2/users/{id}/files发起 POSTmediaUploadURL()qq.go。媒体来源有两种远程 URL 直接提交url字段本地文件则读取字节并 base64 编码后放入file_data字段。图片/视频/音频/文件的file_type分别映射为 1/2/3/4qqFileType()发送富媒体消息使用返回的file_info构造msg_type7的RichMediaMsg消息发送。max_base64_file_size_mib正是在本地文件走 base64 通道时生效文件超过限制会直接报错并归类为ErrSendFailedqq.go而 URL 直传不受此限制。此外音频发送前会探测本地文件时长无法获取时长或超过 QQ 语音时长上限qqVoiceMaxDuration时自动降级按普通文件发送outboundMediaType()qq.go。去重、输入状态与语音能力消息去重QQ 回调可能重复投递isDuplicate()基于消息 ID 在 5 分钟 TTLdedupTTL内去重并设置 10000 条硬上限超限时淘汰最旧条目后台dedupJanitor协程每 60 秒清理一次过期记录qq.go。输入状态提示StartTyping()实现channels.TypingCapable发送InputNotifymsg_type6后每 8 秒重发一次直至上下文取消qq.go。语音能力VoiceCapabilities()声明ASR: true, TTS: trueqq.go即该渠道支持语音识别与语音合成。被动回复元数据applyPassiveReplyMetadata()会为出站消息附加最近一条入站消息的msg_id并通过按会话递增的msg_seq支持多段回复的正确排序qq.go。渠道注册与配置校验QQ 渠道通过channels.RegisterFactory注册到渠道工厂init.gokey 为config.ChannelQQ同时QQSettings被注册进channelSettingsFactory映射config_channel.go使得type: qq能通过配置校验其settings块会正确解码为QQSettings结构体。这意味着 QQ 渠道与其它渠道共用同一套初始化、校验、敏感字段加密与出站分发基础设施接入方式与其他官方渠道保持一致。小结配置上在config/config.example.json的channel_list.qq中填入app_id/app_secret设置enabled: true即可用picoclaw gateway启动全部参数与环境变量可参见 config.go。能力上QQ 渠道原生支持私聊与群消息、Markdown 出站、富媒体图片/视频/音频/文件收发、输入状态提示与语音能力。源码上核心实现在 pkg/channels/qq/qq.go可据此进一步定制消息路由、URL 消毒策略或媒体处理逻辑。赞分享人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载相关推荐PicoClaw QQ 通道接入指南基于 QQ 开放平台官方机器人 API 的配置与源码解析PicoClaw QQ 通道接入指南基于 QQ 开放平台官方机器人 API 的配置与源码解析 PicoClaw 通过 QQ 开放平台的官方机器人 API 提供人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆PicoClaw 接入 QQ 开放平台机器人配置、部署与源码级原理剖析PicoClaw 接入 QQ 开放平台机器人配置、部署与源码级原理剖析 PicoClaw 通过 QQ 开放平台的官方机器人 APIWebSocket 长连接人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆PicoClaw 接入 QQ开放平台机器人配置指南与通道源码解析PicoClaw 接入 QQ开放平台机器人配置指南与通道源码解析 PicoClaw 通过 QQ 开放平台的官方机器人 Bot API 提供完整的 QQ 通道支人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

PicoClaw 接入 QQ 开放平台机器人：官方 API 配置、部署与源码解析

相关推荐

NumPy 用户自定义 DType 的 Partition / Argpartition 支持：基于 ArrayMethod API 实现自定义分区算法

EsDA低代码实现Modbus RTU Master转UDP Client协议转换

大文件分片上传实战：Blob切片、秒传与断点续传五层追问

更多资讯

ASTM A640标准文件识别与工程应用核验指南

FPGA新手入门：从点亮LED开始掌握Vivado与Verilog开发全流程

SPSS多元线性回归实例：从截图到语法复现与结果解读

OneUptime Runbook 代理（Agent）完全指南：在自建基础设施内安全执行 Bash 与 JavaScript 步骤

Glances MPP 插件详解：监控 Rockchip 平台硬件视频编解码引擎（RKVENC / RKVDEC / RKJPEGD）

Taro H5 端路由系统解析：从 `@tarojs/router` 看小程序路由规范在 Web 端的落地

今日更新

校园网认证计费模式详解：AAA与代拨架构、原理及排障

Spring Boot+Vue垃圾分类毕设：分层、权限与排错实战

把 Cline 的 Base URL 改到 TaoToken 之后，DeepSeek 仍能修调试配置

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？