QQ Bot
Connect a QQ group or private chat to an existing workspace conversation. Submit tasks, add instructions, stop tasks, and respond to approvals and questions from QQ. Full results remain available in Panel.
Prepare the bot
- Create an official bot on QQ Open Platform, obtain AppID and AppSecret, and enable the required group, private-chat, and button interaction capabilities.
- Install and enable the plugin in GameX and set account and workspace access. The plugin supports Linux amd64/arm64 and requires a Panel supporting external conversation events.
- Enter QQ AppID in plugin configuration and save AppSecret in the dedicated QQ AppSecret secret field. Keep it out of chat.
- Choose a connection mode and prepare an available conversation in the target workspace.
| Mode | Requirements |
|---|---|
| WebSocket (default) | Panel can reach QQ HTTPS/WSS endpoints; no public callback URL is needed |
| Webhook | Panel is reachable over public HTTPS; copy the callback URL from workspace QQ 机器人 → 接入设置 (QQ Bot → Connection settings) into QQ Open Platform |
The events are GROUP_AT_MESSAGE_CREATE, C2C_MESSAGE_CREATE, and INTERACTION_CREATE. Both modes receive messages in the background; the browser can be closed.
For Webhook, reverse proxies must preserve the original body and signature headers; see callback verification. Connection references: WebSocket and the official SDK.
Bind a chat
- Open the workspace QQ 机器人 (QQ Bot) view and add a binding.
- Choose group or private chat, the target conversation, and handling settings. Generate the binding command.
- Send the command while @mentioning the bot in the target group, or send it in a private chat.
- Return to Panel, verify the source chat, sender, and target conversation, then confirm. Commands expire after ten minutes and are invalidated when cancelled.
QQ tasks use the binding account's Panel identity. Confirm that conversation content may be shared with that chat. Group bindings do not authorize everyone: generate a join command in 成员管理 (Members), have the member send it, then confirm their access.
New members default to viewer. The binding owner can change their member roles in 成员管理 (Members).
Bound tasks may also read the owner's personal memories. For group use, choose a dedicated account and remove personal memories that must not be shared first.
Only the binding owner can edit, pause, or remove their binding and manage members. Nicknames and group names are display information, not authorization.
Choose how tasks are handled
| Setting | Choices |
|---|---|
| Reply content | Concise summary (default), or detailed progress including visible intermediate replies |
| Approvals | Manual, review for me (default), or full access; required human confirmations remain |
| When busy | Guide (default): add to the current task; queue: create a later task |
New bindings default to manual approval when the approval model is unavailable. QQ uses the binding's own approval settings. Existing bindings retain their settings when defaults change. Adjust these in binding settings or turn off 启用绑定 (Enable binding) to pause new tasks.
主动推送 (Forward Panel messages) is off by default. Enabling it also sends new Panel text messages, AI replies, approvals, and questions to the bound chat. Only the binding owner can answer Panel-originated requests. Pausing the binding stops forwarding.
Use QQ
@mention the bot for group messages; send private messages directly.
- Send text or images to submit a task. During execution, messages guide or queue according to the binding setting.
- For approvals, click 批准 (Approve) or 拒绝 (Reject).
- For questions, click an option or reply with its letter, text, or your own answer.
- To interrupt, click 停止任务 (Stop task). Check Panel for the actual outcome of actions already started.
Buttons need no extra @mention. Approvals and questions accept valid replies only from the binding owner or the relevant request initiator. Strong-verification operations still require Panel. Text commands also work: 批准 <request ID>, 拒绝 <request ID>, or 停止 <task ID>, replacing the placeholder with the ID in the current message.
Each message supports up to eight PNG, JPEG, GIF, or WebP images, subject to Panel's per-image limit. Image understanding depends on the selected model.
Results and troubleshooting
Open 历史记录 (History) for the task, source, initiator, and delivery state. Full output is in the bound Panel conversation. 已发送 (Sent) means QQ accepted the message, not that the recipient read it.
Replies use the original message's passive reply allowance first. When its window or quota expires, or QQ explicitly rejects passive replies, the plugin attempts active delivery. QQ permissions, recipient settings, and rate limits still apply. Unknown outcomes do not trigger blind fallback or resends; failed notifications do not rerun tasks.
- No task starts: check @mentions, confirmed and enabled bindings, member authorization, and event permissions.
- Binding fails: check command expiry or cancellation, regenerate it, and verify the source.
- Task completes without a reply: check the Panel conversation and History before deciding to retry.
Disabling the plugin closes its background connection. Uninstalling removes its persistent data.