# QQ Bot常见问题答疑

# 一、机器人管理平台

# Q：旧版管理端机器人提交上架审核

旧版管理端目前已停止审核上架、功能配置等，请使用机器人管理员登录新版QQ Bot管理端，管理你的机器人使用的范围。
公开全量使用：当前该能力正在对于企业开发者灰度，后续会推全到个人认证，请耐心等待。
个人主体如需添加群聊：机器人创建者仅可添加是自己是群主/管理员的群聊 (升级最新版移动QQ添加)；个人主体如需添加其他用户私聊，请在新版管理端开发设置中添加开发体验用户。

# Q：机器人如何公开添加进群、频道

目前在最新机器人管理端中，企业主体公开使用已开放，个人主体正在陆续开放中。
个人主体如需添加群聊，机器人创建者仅可添加是自己是群主/管理员的群聊 (升级最新版移动QQ添加)；如需添加成员使用，请在新版管理端开发设置中添加开发体验用户。

# Q：机器人删除、注销失败

网页管理端注销机器人：使用创建机器人的QQ账号登录 QQ开放平台 (opens new window)，进入机器人管理端后点击对应机器人注销，已被封禁的机器人不支持注销。
手机端注销机器人：升级最新版手机QQ，客户端登录创建机器人QQ账号，在机器人聊天界面点击右上角进入机器人资料页，点击资料页右上角设置图标，进入「机器人管理」-「高级设置」-「注销机器人」。
（注意：注销是永久注销机器人，不是删除和机器人的聊天关系，且已封禁机器人不支持注销）

# Q：创建机器人显示当前QQ账号状态异常，暂时无法创建机器人

请注意您的相关QQ账号合规使用状态，机器人相关 QQ账号异常，会导致无法创建机器人。

# Q：创建机器人显示创建失败

请检查账户主体是否有认证，账户是否为超级管理员。

# Q：为什么只能创建 5 个机器人

个人主体：个人认证开发者，支持创建 5 个机器人。
企业主体：企业认证开发者，支持创建 10 个机器人；同一企业主体下所有认证账号共用机器人创建名额，创建上限为 50个。

# Q：怎么添加沙箱环境测试机器人

使用管理员账号进入新版机器人管理端后，管理员账号可直接测试使用，无需沙箱环境。(旧版管理端已不支持添加沙箱群\频道配置)

# Q：机器人提示可添加群聊已满

当前对于不同账号认证状态下，服务范围的限制如下:
未认证：机器人仅管理员使用，可添加到管理员作为群主的群内。
个人认证：可设置为公开使用，机器人进群数量添加上限为 500 个。
企业认证：所有场景均可设置为公开被使用的服务范围。
备注：历史通过旧版开放平台审核上架的机器人不受群上限数量影响。

# Q：个人认证怎么升级企主体

个人主体无法直接升级为企业主体，可以使用新的邮箱账号重新注册并认证企业主体（个体户），可绑定相同的管理员QQ。
邮箱注册地址：邮箱注册 (opens new window)，提交对应工商信息，成功认证企业(个体户)主体后，绑定管理员。

# Q：机器人 Appsecret 无法重置

请检查账户主体是否有认证，账户是否为机器人超级管理员，如开发主体已认证，请登录 QQ开放平台 (opens new window)，点击右上角小头像-账户信息，查看账号资质是否处于异常状态。

# Q：QQ 开放平台登录显示查询开发者信息失败报错

请优先尝试： 1.清除浏览器缓存后重新登录
2.更换浏览器尝试
3.确认您的账号已完成实名认证、为超级管理员账户
如问题持续，可通过开发者社区、机器人工单小助手人工服务反馈。

# Q：如何更改开放平台管理员(QQ账号)、更新主体信息？

如需更改管理员、主体，建议开发者自行到 QQ开放平台 (opens new window)，点击右上角小头像-账户信息-修改。

# Q：如何更换开放平台邮箱

目前邮箱一旦填写完毕进入激活步骤，则被占用不可修改。如需更改管理员，管理员可自行登录 QQ开放平台 (opens new window)，点击右上角头像-账号信息。

# Q：在机器人管理端找不到相关机器人

首先确认主体是否进行主体认证，确认登录账号是否账号为超级管理员。登录账户仅能看到本账号创建的机器人（或添加协管账号），无法看到同一主体其他账户所建。

# Q：如何注销开放平台账号、注销认证的主体

目前平台暂不支持开放平台和开发主体的注销操作。如需更改管理员，管理员可自行登录 QQ开放平台 (opens new window)，点击右上角小头像-账号信息-修改。

# Q：QQ 机器人影响QQ账号注销

如机器人应用影响QQ号注销，需要注销机器人的应用互联状态，可以邮件向QQ互联平台申请注销应用(connect@qq.com)。

# 二、机器人开发使用

# Q：怎么认证开发平台主体

# Q：如何进入QQ Bot管理端创建机器人

# Q：QQ Bot开发教程

原创 QQ Bot开发文档：开发文档 (opens new window)
Agent 接入 QQ Bot使用文档：Agent接入 (opens new window)

# Q：机器人如何添加、修改指令

已开放自定义菜单与指令面板，请查看官方开发文档：自定义菜单与指令面板 (opens new window)

# Q：如何使用MarkDown消息、消息按钮

单聊场景、群聊场景自定义 Markdown 消息能力、消息按钮已开放到所有机器人均可使用，无需单独申请 Markdown 模版。
Markdown语法参考文档：Markdown消息 (opens new window)

# Q：使用WebHook 连接方式中断

遇到 webhook 数据突然中断，可优先排查防火墙等网络安全设置，避免因防火墙误拦截导致数据异常问题。

# Q：在群里@机器人不回复，但私聊可以 (机器人在群中主动发送消息失败)

升级最新版手机QQ，使用移动端添加机器人入群时，群主在群中或在成员列表中点击机器人，进行相关权限设置。

1.接收全量消息能力：当群主设定允许该机器人接收群内全部消息时，机器人可接收到群内所有成员在群内的发言消息。
2.主动推送消息能力：当群主设定允许机器人主动在群聊内发言，机器人主动在群聊内发言，如定时任务推送等。
3.机器人撤回成员消息能力：当机器人被群主设置为群管理员时，可撤回成员发送的消息。

# Q：如何申请开通机器人Union_openid

开通union_id规则如下：
1.申请者务必确保提供的appid主体均是同一注册主体，非同一主体不可配置
2.当前采用发送邮件申请，格式如下：
邮箱地址：qq_bot_api@tencent.com
邮件主题：申请Union_openid绑定

— —邮件内容— —

bot appid：

绑定主union_openid(appid)：

机器人功能说明：

机器人主体名称：

申请事项：

承诺业务将严格遵守 QQ 机器人平台的运营规范，如果有违反，一切后果由业务使用侧自行承担。

承诺方：

承诺日期：

邮件将在1-3工作日内回复通知，请耐心等待。

# Q：QQ机器人Union_openid支持哪些APPID

目前只支持绑定QQBot，已创建的QQ互联应用 (如QQ小程序、小游戏等)，如绑定微信小程序的QQ互联ID则会获取失败。

# Q：如何申请未开放的权限、接口

内邀接口暂未开放申请渠道，请及时关注官方文档更新。

# 三、机器人接入Agent

# Q：QQ机器人怎么连接AI Agent？（如 Openclaw、hermes）

Agent接入QQBot使用教程：Agent接入 (opens new window)

# Q：如何升级OpenClaw

方式一：对话框升级，复制以下内容，粘贴发送给 QQ Bot：

请在后台环境中执行命令“npx -y @tencent-connect/openclaw-qqbot-cli@latest”，完成qqbot插件的安装或更新操作：若当前环境未安装该qqbot插件，请直接执行安装流程；若已安装该插件，请执行对应版本的更新操作，操作完成后通知我。

方式二：终端升级，在终端执行升级 qqbot 插件命令：

npx -y @tencent-connect/openclaw-qqbot-cli@latest

# Q：Bot灵魂不在线

建议本地使用稳定服务设备，尝试升级QQ Bot插件或重启网关、重新连接。参考文档：Agent接入教程 (opens new window)

# Q：OpenClaw升级后机器人无法连接怎么办？

尝试升级QQ Bot插件或重启网关、重新连接。参考文档：Agent接入教程 (opens new window)

# Q：为什么OpenClaw没法给QQ Bot发图片？

OpenClaw是可以回复图片给到QQ Bot的，如果不能回复，尝试升级QQBot插件重新连接，或让OpenClaw分析一下失败原因。

# Q：机器人接入Hermes智能体在群聊@机器人无响应

接入hermes智能体目前不支持获取群内全部消息；可将机器人接收消息设置成仅获取@机器人的消息，并且在 config 文件中增加group_policy: open以打开群聊消息接收。
具体配置层级为：
platforms:
qqbot:
extra:
group_policy: open #群消息接收策略

# Q：接入Hermes智能体如何进行问题排查

1.如果有显示小灰条灵魂不在线，则为配置问题，让用户按小灰条引导进行
2.如果 c2c 也不能正常回复，则为 hermes 问题，让用户提单，指引用户提供 logs 进行分析
3.如果 c2c 可以正常回复，qq 群内机器人设置为仅@模式或上下文模式，群内@时没有回复，则大概率为配置变量问题，回复hermes qqbot默认设置为不接收群内消息，需要在 config 文件中增加group_policy: open以打开群聊消息接收。
4. 如果 c2c 可以正常回复，qq 群内机器人设置为全量模式，没有回复，则为 hermes 不支持获取全部消息。

# Q：机器人回复create session error是什么情况？

这个错误通常表示会话创建失败，可能原因： 1.机器人Token已过期
2.网络连接不稳定
3.服务器时间不同步
建议检查服务器时间配置，并重新获取Access Token。

# Q：如何给机器人配置skill

可以参考Skills 安装技巧 (opens new window)

# 四、机器人运营

# Q：QQ 机器人可以接入 AI 功能吗

AI 服务模型及工具由开发者自主选配，使用请注意相关安全规范，确保机器人输出消息符合平台规范，违规使用会导致机器人或相关账号封禁。

# Q：机器人私聊界面不显示Bot头像

目前为提升消息浏览体验、展示消息更多篇幅，聊天界面使用宽屏消息展示。

# Q：机器人被封禁

机器人封禁处罚是依据平台规则执行，暂不支持解封。使用请注意相关安全规范，始终遵循平台规则，确保机器人输出消息符合平台规范，违规使用会导致机器人或相关账号封禁。

# Q：QQ小程序小游戏审核、创建

开放平台维护中，暂不支持创建新的小游戏/小程序，如有疑问，请尝试联系以下客服。
小游戏：wanba@tencent.com
小程序：qq-miniprogram@tencent.com

# Q：官方开发者社区频道号

QQ开发者社区频道号：20dnumts4z

# Q：机器人工单小助手人工回复很慢

技术人员排查问题需要时间，工单需排队处理，高峰期如出现积压，请耐心等待回复。

# Q：怎么申请机器人推荐榜单

机器人推荐的评审相关工作在进行运营策略调整，已不接受新的申请。如有相关政策更新，我们会在官方渠道第一时间发布通知，感谢您的关注。

# Q：如何举报机器人违规

可参照机器人举报流程进行举报（提供真实有效信息），相关安全人员会进行核实，具体流程如下：
1.在聊天界面内多选机器人消息内容，选择举报
2.提交后，选择相关违规类型