PicoClaw 接入 QQ开放平台机器人配置指南与通道源码解析【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 通过 QQ 开放平台的官方机器人 Bot API 提供完整的 QQ 通道支持支持私聊C2C与群聊 消息的收发、图片/语音/文件等富媒体、输入状态提示与语音能力。本文以 docs/channels/qq/README.zh.md 为骨架结合仓库内pkg/channels/qq的通道实现与 config/config.example.json 中的真实配置格式完整讲解从凭证申请、配置写入、picoclaw gateway启动到消息收发与媒体发送的实战流程并深入解析底层调用链帮助你在 10 分钟内把 QQ 机器人接入 PicoClaw。功能概述QQ 通道基于 QQ 开放平台的官方机器人能力实现无需自建服务端机器人通过 WebSocket 长连接订阅消息事件。从 pkg/channels/qq/qq.go 的代码可以看到通道注册了两类事件处理器handleC2CMessage()处理用户与机器人之间的私聊C2C消息handleGroupATMessage()处理群聊中 机器人的消息。发送侧则根据会话类型自动路由到PostGroupMessage群消息或PostC2CMessageC2C 私聊消息两个 OpenAPI 接口并支持 Markdown 消息、富媒体上传msg_type7、输入状态提示msg_type6等扩展能力。前置准备获取 App ID 与 App Secret接入 QQ 通道的核心凭证是App ID和App Secret两者均由 QQ 开放平台下发。文档提供了两种获取方式。快捷创建推荐QQ 开放平台提供了一键创建机器人入口适合快速验证打开 QQ 机器人快速创建入口扫码登录系统自动创建机器人页面展示App ID与App Secret立即复制保存将凭证填入 PicoClaw 配置文件下文详述运行picoclaw gateway启动服务打开 QQ与机器人开始对话。注意App Secret 仅完整显示一次请立即保存再次查看会被强制重置。另外通过快捷入口创建的机器人仅供创建人个人使用暂不支持群聊如需群聊功能请在 QQ 开放平台为机器人配置沙箱模式。手动创建使用 QQ 账号登录 QQ 开放平台注册开发者账号创建 QQ 机器人自定义头像与名称在机器人设置页获取App ID与App Secret将凭证填入 PicoClaw 配置文件运行picoclaw gateway启动服务在 QQ 中搜索你的机器人开始对话。开发阶段建议开启沙箱模式把测试用户和测试群加入沙箱便于在受控范围内调试避免误触线上用户。配置文件详解标准配置结构以仓库根目录 config/config.example.json 中真实的 QQ 通道配置段为准完整结构如下{ 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并将app_id、app_secret替换为开放平台下发的真实凭证即可。字段说明通道级字段与 settings 级字段分别对应 pkg/config/config.go#L573-L579 中定义的QQSettings结构体及其外层Channel配置字段类型必填位置描述enabledbool是channel 级是否启用 QQ 通道typestring是channel 级固定为qq用于匹配注册的通道工厂allow_fromarray否channel 级用户 ID 白名单空数组表示允许所有用户reasoning_channel_idstring否channel 级推理输出专用会话 ID可配置为群 IDapp_idstring是settingsQQ 机器人应用的 App IDapp_secretstring是settingsQQ 机器人应用的 App Secret敏感字段加密存储max_message_lengthint否settings单条消息最大长度限制max_base64_file_size_mibint否settings本地文件转 base64 上传的最大体积MiB0表示不限制仅影响本地文件不影响 URL 直传send_markdownbool否settings发送时是否使用 Markdown 消息类型环境变量替代方案从QQSettings的 struct tag 可以看到所有 settings 级字段都支持通过环境变量注入适合容器化或密钥管理场景PICOCLAW_CHANNELS_QQ_APP_IDPICOCLAW_CHANNELS_QQ_APP_SECRETPICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTHPICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIBPICOCLAW_CHANNELS_QQ_SEND_MARKDOWN其中app_secret在 pkg/config/config.go#L573 中使用SecureString类型仓库的 安全配置测试 会验证这类敏感字段的脱敏与加密行为切勿在日志或明文配置中泄露。白名单与群触发allow_from白名单在创建通道时通过channels.NewBaseChannel的bc.AllowFrom传入空数组放行所有用户如需限制为指定 QQ 用户可填入对应的用户 ID 列表。group_trigger则控制群聊场景下的触发词过滤配合群 事件使用。启动服务配置写入后运行 gateway 子命令启动服务picoclaw gateway该命令在 cmd/picoclaw/internal/gateway/command.go 中定义用途说明为 Start picoclaw gateway启动时会根据配置文件中的channel_list实例化所有已启用的通道QQ 机器人随之建立 WebSocket 长连接并开始订阅消息事件。启动成功后在 QQ 中搜索你的机器人即可开始对话。源码实现原理通道注册QQ 通道通过工厂模式注册见 pkg/channels/qq/init.goinit()中调用channels.RegisterFactory把config.ChannelQQ类型映射到NewQQChannel构造函数配置文件中的settings块会被解码为*config.QQSettings后传入。这就是type字段必须为qq的原因。WebSocket 连接与事件订阅在Start()方法中pkg/channels/qq/qq.go#L102-L174校验app_id与app_secret是否已配置缺失则直接报错基于凭证构造token.QQBotCredentials创建 oauth2 token source并启动后台协程自动刷新 Access Token初始化 OpenAPI 客户端5 秒超时注册 C2C 消息与群 消息两类事件处理器构建 Intent从WS接口获取 WebSocket 网关信息由botgo.NewSessionManager()建立长连接额外启动一个去重清扫协程dedup janitor并在reasoning_channel_id配置了群 ID 时预注册为 group 会话类型保证纯出站路由正确。这里使用了腾讯开源的tencent-connect/botgoSDK底层事件分发的细节被封装在 botgo 中PicoClaw 侧只需实现qqAPI接口WS、PostGroupMessage、PostC2CMessage、Transport即可完成收发。消息去重WebSocket 场景下事件可能重投递通道在 pkg/channels/qq/qq.go#L909-L936 实现基于消息 ID 的 TTL 去重默认 5 分钟窗口dedupTTL并对去重表设置 10000 条硬上限超出时淘汰最旧条目dedupJanitor每 60 秒清扫过期条目避免内存无限增长。会话路由与被动回复通道内部维护chatType映射记录每个 chatID 是群聊还是私聊未知 chatID 默认按群聊处理。同时记录每个会话最后一条入站消息 IDlastMsgID出站回复时通过applyPassiveReplyMetadata回填msg_id与递增的msg_seq实现 QQ 开放平台要求的被动回复消息引用机制。媒体发送两步上传流程SendMedia实现channels.MediaSender接口pkg/channels/qq/qq.go#L326-L367QQ 的富媒体发送是两步流程先将媒体上传到/v2/groups/{group_id}/files或/v2/users/{user_id}/files依会话类型而定获得file_info再以msg_type7的富媒体消息携带file_info发送。媒体类型映射为qqFileType图片1、视频2、音频3、普通文件4。对于本地文件如果配置了max_base64_file_size_mib会先os.Stat校验文件大小再以 base64 编码上传见buildMediaUploadURL 直传则不受该限制。音频还会做时长探测超过 QQ 语音时长上限或无法探测时长时自动降级为普通文件发送。输入状态提示通道实现channels.TypingCapable接口的StartTyping发送msg_type6的 InputNotify 消息并以 8 秒为间隔重发模拟对方正在输入的状态直到返回的停止函数被调用幂等可重复调用。群消息 URL 净化为避免 QQ 对群消息的 URL 黑名单拦截通道在群聊出站前会用sanitizeURLs将 URL 域名中的.替换为全角。pkg/channels/qq/qq.go#L980-L1017。该处理只作用于带http(s)://前缀的 URL且只替换域名部分、保留路径与查询参数避免对版本号之类的纯文本误伤。语音能力通道声明VoiceCapabilities{ASR: true, TTS: true}pkg/channels/qq/qq.go#L1019-L1022表明 QQ 通道同时支持语音识别ASR与语音合成TTS可用于语音交互类场景。常见问题与排错提示启动报 app_id and app_secret not configured说明配置文件中的app_id/app_secret为空请确认凭证已正确写入settings段。私聊正常但群聊无响应快捷创建入口创建的机器人不支持群聊需在 QQ 开放平台配置沙箱模式并把测试群加入沙箱。凭证泄露风险App Secret 属于敏感字段仓库以SecureString处理并在加密与脱敏逻辑中覆盖生产环境建议通过PICOCLAW_CHANNELS_QQ_APP_SECRET环境变量注入。群消息被拦截QQ 对群内 URL 有黑名单策略通道默认已做域名点号净化如需外链直达请结合实际开放平台规则调整发送内容。若需进一步了解 PicoClaw 的整体架构与配置体系可继续阅读 项目 README 与 配置文件指南。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考