企业官网建设流程全解析

• 人工智能
• AI 应用
• AI Agent
• 交互助手
• 工具调用
• MCP Clients
• Agent 记忆

导读

本文围绕 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 SDK（github.com/tencent-connect/botgo），核心代码见 qq.go，渠道工厂注册见 init.go。

配置详解

完整配置示例

以下配置片段来自仓库的 config/config.example.json（第 138～147 行），是 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嵌套格式为准，两种写法在语义上一致。

参数说明

其中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标签）：

注意app_secret在配置系统中被声明为SecureString类型（config.go），属于敏感字段：它会被安全地脱敏存储，在普通配置输出中不会以明文出现，相关加密/脱敏逻辑可参考 pkg/config/security.go 及其测试 security_integration_test.go。

设置流程

快捷方式（推荐）

QQ 开放平台提供了一键创建入口，适合快速体验：

1. 打开 QQ 机器人快速创建页面（文档原文链接为https://q.qq.com/qqbot/openclaw/index.html），扫码登录；
2. 系统自动创建机器人，复制App ID和App Secret；
3. 将凭证填入 PicoClaw 配置文件（config/config.example.json中的channel_list.qq块）；
4. 运行picoclaw gateway启动服务；
5. 打开 QQ，与机器人开始对话。

注意：App Secret 仅显示一次，请立即保存；再次查看将强制重置。

通过快捷入口创建的机器人仅供创建人使用，暂不支持群聊。如需群聊功能，请在 QQ 开放平台配置沙箱模式。

手动创建

1. 使用 QQ 账号登录 QQ 开放平台，注册开发者账号；
2. 创建 QQ 机器人，自定义头像和名称；
3. 在机器人设置中获取App ID和App Secret；
4. 将凭证填入 PicoClaw 配置文件；
5. 运行picoclaw gateway启动服务；
6. 在 QQ 中搜索你的机器人，开始对话。

开发阶段建议开启沙箱模式，将测试用户和群添加到沙箱中进行调试。

启动命令与验证

配置完成后，执行picoclaw gateway即可启动网关（含 QQ 渠道）。该子命令定义于 cmd/picoclaw/internal/gateway/command.go，描述为 "Start picoclaw gateway"，支持通过参数覆盖网关绑定地址与日志级别。

启动 QQ 渠道时，核心的Start()流程（qq.go）会依次完成：

1. 凭证校验：若app_id或app_secret为空，直接返回错误"QQ app_id and app_secret not configured"；
2. 创建凭证源：基于token.QQBotCredentials构建QQBotTokenSource，并启动独立的 token 自动刷新协程；
3. 初始化 OpenAPI 客户端：botgo.NewOpenAPI(appID, tokenSource).WithTimeout(5 * time.Second)；
4. 注册事件处理器：handleC2CMessage()（私聊）与handleGroupATMessage()（群 @ 消息）两个处理器被注册进 intent；
5. 建立 WebSocket 连接：先通过api.WS()获取分片（shards）信息，再由sessionManager.Start()在后台协程中启动长连接；
6. 启动去重清理协程，并将reasoning_channel_id预注册为群聊类型以便出站路由正确。

启动成功后日志输出"QQ bot started successfully"。

源码实现原理

消息收发与路由

QQ 渠道在消息层面实现了两种会话类型：私聊（C2C）与群聊（GroupAT）。chatType这个sync.Map记录了每个chatID是"group"还是"direct"（qq.go）。未知会话默认按群聊处理，因为群 ID 更常作为纯出站目标（如reasoning_channel_id）出现。

发送消息时（Send()，qq.go），代码先根据会话类型选择PostGroupMessage或PostC2CMessage；若send_markdown开启，则消息类型切换为dto.MarkdownMsg（msg_type=2），并清空纯文本字段以避免重复发送。收到私聊/群消息时，处理器会先做去重校验与发送者白名单校验（IsAllowedSender），再提取文本与附件，最后构造InboundContext交给 BaseChannel 统一分发（qq.go）。

群消息 URL 消毒

QQ 平台对群消息存在 URL 黑名单限制，直接发送带点的域名可能被拒绝。因此对于群聊出站消息，代码中的sanitizeURLs()（qq.go）会用正则匹配带http(s)://前缀的 URL，将域名部分的英文句点替换为全角句号。，而路径与参数保持不变——这样既能绕过黑名单，又不破坏链接可读性。该处理仅作用于群消息，且只匹配带显式协议的 URL，避免误伤版本号之类的裸文本。

媒体发送：两步上传流程

QQ 渠道实现了channels.MediaSender接口，群/私聊媒体发送是典型的两步流程（qq.go）：

1. 上传媒体：向/v2/groups/{id}/files或/v2/users/{id}/files发起 POST（mediaUploadURL()，qq.go）。媒体来源有两种：远程 URL 直接提交url字段；本地文件则读取字节并 base64 编码后放入file_data字段。图片/视频/音频/文件的file_type分别映射为 1/2/3/4（qqFileType()）；
2. 发送富媒体消息：使用返回的file_info构造msg_type=7的RichMediaMsg消息发送。

max_base64_file_size_mib正是在本地文件走 base64 通道时生效：文件超过限制会直接报错并归类为ErrSendFailed（qq.go），而 URL 直传不受此限制。此外，音频发送前会探测本地文件时长：无法获取时长或超过 QQ 语音时长上限（qqVoiceMaxDuration）时，自动降级按普通文件发送（outboundMediaType()，qq.go）。

去重、输入状态与语音能力

• 消息去重：QQ 回调可能重复投递，isDuplicate()基于消息 ID 在 5 分钟 TTL（dedupTTL）内去重，并设置 10000 条硬上限，超限时淘汰最旧条目；后台dedupJanitor协程每 60 秒清理一次过期记录（qq.go）。
• 输入状态提示：StartTyping()实现channels.TypingCapable，发送InputNotify（msg_type=6）后每 8 秒重发一次，直至上下文取消（qq.go）。
• 语音能力：VoiceCapabilities()声明ASR: true, TTS: true（qq.go），即该渠道支持语音识别与语音合成。
• 被动回复元数据：applyPassiveReplyMetadata()会为出站消息附加最近一条入站消息的msg_id，并通过按会话递增的msg_seq支持多段回复的正确排序（qq.go）。

渠道注册与配置校验

QQ 渠道通过channels.RegisterFactory注册到渠道工厂（init.go），key 为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 Clients
• Agent 记忆