QQ Open Platform channel adapter for Bub.
Chinese documentation: README.zh-CN.md
| Capability | Details |
|---|---|
| Single-chat (C2C) receive/reply | C2C_MESSAGE_CREATE adapted to Bub ChannelMessage; passive text / markdown / rich-media replies |
| Group receive/reply | GROUP_AT_MESSAGE_CREATE / GROUP_MESSAGE_CREATE; full-message mode supported, payload carries was_mentioned / sender_role |
| Active group messages | Proactive fallback when a passive reply is impossible (active_messages, requires the group admin's opt-in in the QQ client) |
| Reply modes & selective silence | reply_mode: tool (default) exposes a native qq.send tool so the model replies by calling it and stays silent by not calling it; direct forwards the model's final text and swallows <no_reply/> (see Reply modes) |
| Quotes and chat records | msg_elements parsed into quoted_messages (quoted messages / merged-forward chat records) for the model |
| Receive transport | webhook or websocket (mutually exclusive on the QQ platform side); ed25519 signature verification and reconnect included |
| Security | One Guard for every action: admin pairing (,qq.claim), per-resource rules, one-time shell approvals, protected files, public-only downloads, allowlists, rate limiting, audit logs (see Security) |
| Persisted platform state | Active-message opt-ins (*_MSG_RECEIVE / *_MSG_REJECT) and group claw_cfg survive restarts |
| Reliable sending | Inbound/outbound dedupe, msg_seq management, error catalog; async manual audit (304023/304024) treated as pending success |
| Onboarding | bub onboard collects appid / secret / receive_mode; bundled skill resources under src/skills/qq |
Plugin entry point: qq → bub_qq.plugin. Supports single-chat (C2C) and group text receive/reply. QQ Guild is not covered yet.
- Install Bub 0.6.0 or later (recommended:
uv tool install bub). On an older Bub the plugin does not load and the log says why. Newer minor releases and development builds load with aqq.bub.untested/qq.bub.prereleasewarning: tools a newer Bub adds stay admin-only until bub-qq knows them - Run
bub onboardand ensure model access works (bub chatorbub run) - Create a QQ bot on the QQ Open Platform and obtain
APPID/SECRET
bub-qq is not on PyPI. With a global Bub install (uv tool install bub), install the plugin into Bub’s own environment:
bub install bub-qq@mainThis resolves to the official monorepo package:
git+https://github.com/bubbuild/bub-contrib.git@main#subdirectory=packages/bub-qq
Equivalent forms:
# Full Git URL (use https:// …, not git+https://, when passing to bub install)
bub install "https://github.com/bubbuild/bub-contrib.git#subdirectory=packages/bub-qq"
# Pin a tag or commit when available
bub install bub-qq@<tag-or-sha>Verify the plugin is loaded:
bub hooksYou should see the qq plugin among discovered entry points / hook providers.
bub update bub-qq
bub uninstall bub-qq- Do not use bare
bub install bub-qq. A name without@refis treated as a PyPI package name. bub installrequires Bub to run inside a virtual environment (including the environment created byuv tool install bub) anduvonPATH.
Editable install into the same environment that runs bub.
uv pip install -e /path/to/bub-contrib/packages/bub-qq \
--python ~/.local/share/uv/tools/bub/bin/pythonThen use the global CLI as usual:
bub hooks
bub gatewayFrom a uv project that already depends on Bub:
uv add --editable /path/to/bub-contrib/packages/bub-qq
# or, from bub-contrib workspace workflows:
uv pip install -e packages/bub-qquv pip install \
"git+https://github.com/bubbuild/bub-contrib.git#subdirectory=packages/bub-qq" \
--python /path/to/the/python/that/runs/bubSettings can come from:
- the
qq:section in~/.bub/config.yml BUB_QQ_*environment variables (including values loaded from.env)bub onboard, which interactively collects the required fields when theqqchannel is enabled
Env vars override YAML, so shared policy can live in config.yml while secrets stay in the environment.
YAML field (qq.*) |
Env var | Description |
|---|---|---|
appid |
BUB_QQ_APPID |
QQ bot app ID |
secret |
BUB_QQ_SECRET |
QQ bot secret |
receive_mode |
BUB_QQ_RECEIVE_MODE |
Inbound transport: webhook or websocket |
receive_mode must match the QQ developer console:
webhook— starts the embedded webhook server only; WebSocket is not startedwebsocket— starts the WebSocket client only; the embedded webhook server is not started
QQ treats webhook and WebSocket as mutually exclusive. After a valid HTTPS webhook callback URL is configured successfully, WebSocket delivery is no longer supported on the platform side.
Gateway start fails if appid / secret are empty, or if receive_mode is not webhook / websocket.
YAML field (qq.*) |
Env var | Default | Description |
|---|---|---|---|
token_url |
BUB_QQ_TOKEN_URL |
https://bots.qq.com/app/getAppAccessToken |
Access token endpoint |
openapi_base_url |
BUB_QQ_OPENAPI_BASE_URL |
https://api.bot.qq.com |
OpenAPI base URL (official unified endpoint; override here to use the legacy https://api.sgroup.qq.com) |
timeout_seconds |
BUB_QQ_TIMEOUT_SECONDS |
30 |
HTTP timeout for token and OpenAPI |
token_refresh_skew_seconds |
BUB_QQ_TOKEN_REFRESH_SKEW_SECONDS |
60 |
Refresh token this many seconds before expiry |
webhook_host |
BUB_QQ_WEBHOOK_HOST |
127.0.0.1 |
Embedded webhook bind host |
webhook_port |
BUB_QQ_WEBHOOK_PORT |
8080 |
Embedded webhook port (80 / 443 / 8080 / 8443 allowed by QQ) |
webhook_path |
BUB_QQ_WEBHOOK_PATH |
/qq/webhook |
Webhook path |
verify_signature |
BUB_QQ_VERIFY_SIGNATURE |
true |
Enforce webhook signature verification |
webhook_signature_timestamp_tolerance_seconds |
BUB_QQ_WEBHOOK_SIGNATURE_TIMESTAMP_TOLERANCE_SECONDS |
300 |
Reject webhook requests whose signature timestamp deviates from local time by more than this many seconds (blocks replayed callbacks; keep the server clock in sync); 0 disables the check. Webhook bodies over 1 MB are rejected |
inbound_dedupe_size |
BUB_QQ_INBOUND_DEDUPE_SIZE |
1024 |
Recent inbound msg_id cache size |
session_state_size |
BUB_QQ_SESSION_STATE_SIZE |
1024 |
Max sessions / send records kept in memory for passive replies (oldest entries are evicted) |
passive_reply_window_seconds |
BUB_QQ_PASSIVE_REPLY_WINDOW_SECONDS |
platform limit | Override how long after an inbound message passive replies are attempted; unset uses the platform limits (3600 s in C2C, 300 s in groups) |
active_messages |
BUB_QQ_ACTIVE_MESSAGES |
false |
Send proactive group messages (no msg_id) when a passive reply is impossible; requires the group admin to allow proactive messages in the QQ client |
passive_replies_per_msg_id |
BUB_QQ_PASSIVE_REPLIES_PER_MSG_ID |
platform limit | Override the local cap of passive replies per inbound message; unset uses the platform limits (4 in C2C, 5 in groups). Beyond it the send falls back to an active message (when enabled) or is skipped |
group_wake |
BUB_QQ_GROUP_WAKE |
all |
Which group messages start a model turn: all (the model decides whether to reply) or mention (only @-mentions; follow-ups right after are still included). mention saves model calls in busy groups |
reply_mode |
BUB_QQ_REPLY_MODE |
tool |
How model output reaches QQ: tool (default) disables direct forwarding and exposes the qq.send tool; direct forwards the final text (output exactly <no_reply/> to stay silent) (see Reply modes) |
state_file |
BUB_QQ_STATE_FILE |
empty | JSON file persisting registered admins and platform switches (active-message opt-ins, group claw_cfg); empty uses <bub home>/qq/state.json |
admin_users |
BUB_QQ_ADMIN_USERS |
empty | Admins, the only trusted senders. Entries are scoped identities (c2c:<user_openid>, group:<group_openid>:<member_openid>) or bare openids matching in any scope. Usually left empty and filled by ,qq.claim (see Security) |
allow_users |
BUB_QQ_ALLOW_USERS |
empty | Comma-separated C2C allowlist; when set, C2C messages from anyone else are dropped |
allow_groups |
BUB_QQ_ALLOW_GROUPS |
empty | Comma-separated group allowlist; when set, messages from other groups are dropped |
group_shell |
BUB_QQ_GROUP_SHELL |
approval |
Shell (bash) for admins: approval (an admin taps to confirm every command; no always-allow) or deny. Non-admins never get a shell. Applies in groups and C2C |
shell_sandbox |
BUB_QQ_SHELL_SANDBOX |
none |
Declare whether Bub runs inside an external sandbox (none / external). The plugin does not isolate commands; none with shell enabled logs a warning at startup |
c2c_access |
BUB_QQ_C2C_ACCESS |
admin_users |
Who may use tools in C2C: admin_users, or allow_users (requires a non-empty allow_users; startup fails otherwise). Replies always work |
inbound_images |
BUB_QQ_INBOUND_IMAGES |
direct |
Which inbound images are attached to the message so a multimodal model sees them: direct (private chats and group messages that @ the bot), all, or off. Others stay metadata the model can open with qq.view_image |
inbound_images_per_message |
BUB_QQ_INBOUND_IMAGES_PER_MESSAGE |
4 |
Most images attached to one message |
inbound_image_max_bytes |
BUB_QQ_INBOUND_IMAGE_MAX_BYTES |
10485760 |
Largest image attached or opened with qq.view_image |
download_allow_hosts |
BUB_QQ_DOWNLOAD_ALLOW_HOSTS |
empty | Comma-separated hostnames that media_url, web.fetch and attachment downloads may reach even on private addresses (e.g. an intranet image host) |
group_tool_policy |
BUB_QQ_GROUP_TOOL_POLICY |
restricted |
Policy for tools other than shell and files in groups: open / restricted (denies subagent and denied_tools) / locked (denies every tool except replies, admins included) |
c2c_tool_policy |
BUB_QQ_C2C_TOOL_POLICY |
open |
Same, for C2C users allowed by c2c_access |
allowed_tools |
BUB_QQ_ALLOWED_TOOLS |
empty | Extra comma-separated tool-name glob patterns non-admins may use, e.g. web_search.*. Tools outside the built-in list and these patterns are admin-only; shell, code mode and session-changing tools are unaffected |
denied_tools |
BUB_QQ_DENIED_TOOLS |
empty | Extra comma-separated tool-name glob patterns denied under restricted, e.g. web.fetch,tape.* |
llm_rate_limit_per_minute |
BUB_QQ_LLM_RATE_LIMIT_PER_MINUTE |
0 |
Max LLM calls per sender per session per minute; 0 disables |
llm_rate_limit_notice |
BUB_QQ_LLM_RATE_LIMIT_NOTICE |
请求过于频繁,请稍后再试。 |
Reply text used when a sender hits the LLM rate limit |
websocket_intents |
BUB_QQ_WEBSOCKET_INTENTS |
1 << 25 |
WebSocket identify intents (GROUP_AND_C2C_EVENT) |
websocket_use_shard_gateway |
BUB_QQ_WEBSOCKET_USE_SHARD_GATEWAY |
false |
Use /gateway/bot recommended shard count |
websocket_reconnect_delay_seconds |
BUB_QQ_WEBSOCKET_RECONNECT_DELAY_SECONDS |
5 |
Base delay before WebSocket reconnect (doubles per consecutive failure) |
websocket_reconnect_max_delay_seconds |
BUB_QQ_WEBSOCKET_RECONNECT_MAX_DELAY_SECONDS |
300 |
Upper bound for the exponential reconnect backoff |
websocket_max_identify_rejections |
BUB_QQ_WEBSOCKET_MAX_IDENTIFY_REJECTIONS |
5 |
Stop the client after this many consecutive identify rejections (op 9); 0 disables the limit |
Example:
qq:
appid: your_app_id
secret: your_secret
receive_mode: websocketexport BUB_QQ_APPID=your_app_id
export BUB_QQ_SECRET=your_secret
export BUB_QQ_RECEIVE_MODE=websocketRemoved in 0.3.0: exec_approval (use group_shell) and workspace_jail (replaced by the Guard; see Security). If still set they are ignored with a startup warning.
Which group messages the bot hears is controlled in the QQ client by a group admin setting (all messages / last 10 @mentions / @only). With group_wake: all (default) every received group message wakes the model, and was_mentioned in the payload is false when the bot was not @mentioned; with group_wake: mention only @-mentions start a turn.
Settings path in the latest mobile QQ client: open the group chat → tap "More" in the top-right corner → Group Bots → Manage. There the group owner or an admin can adjust the bot's group message scope and toggle "allow the bot to speak proactively" (pairs with active_messages).
reply_mode decides how model output becomes a QQ message, and — just as important — how the model stays silent (e.g. for un-mentioned group chatter it has nothing to add to). In opt-in/opt-out terms: direct is opt-out (replying is the default; the model explicitly opts out with a sentinel), while tool is opt-in (silence is the default; the model explicitly opts in by calling the send tool — the same contract Bub's other channels use). Both modes share the same send pipeline (passive msg_id/msg_seq targeting, dedupe, markdown fallback, active-message fallback), and a per-mode <qq_response_instruct> block is injected into the system prompt so the model knows the active contract.
Direct forwarding is disabled (model output is routed to the null channel) and a native qq.send tool is registered instead. The model replies by calling qq.send with the message text (and optionally media_url / file_type for native rich media) — msg_id/msg_seq are resolved internally, so the model never touches protocol fields — and stays silent by simply not calling it. Buttons are plugin-owned, not model-generated. The failure mode: if the model forgets to call the tool, the reply is silently lost.
The model's final text is forwarded to the chat as-is — delivery never depends on the model calling anything. To skip a reply, the model outputs exactly <no_reply/>; the channel swallows it (logged as qq.send skip_no_reply) and nothing is sent. Leaked model special tokens (<|eos|>, <|im_end|>, …) are stripped from the edges of outbound text; output consisting only of such tokens is also treated as silence. Use this when the configured model's tool-calling reliability is unknown: the failure mode is an unwanted message, never a lost one. direct cannot send media_url.
qq.send is exempt from the tool policy (group_tool_policy / c2c_tool_policy / denied_tools): it is the reply path itself, which was never gated in direct mode.
Notes for tool mode:
- Comma-command output is always delivered directly in both modes (commands bypass the model).
- When a sender hits
llm_rate_limit_per_minute, the plugin sendsllm_rate_limit_noticeitself (at most once per minute per sender). The limit counts turns, not the individual LLM calls of a multi-step turn. qq.sendreplies to the message that triggered the turn, even if newer messages arrived meanwhile; button clicks are answered throughevent_idas QQ requires.
Every action a chat can trigger passes one checkpoint, the Guard: model tool calls and comma commands (both in before_tool_call, since Bub runs a command's tool with the tool hooks), and approved executions. It decides from who is asking and which resource the call touches. Anyone who can message the bot can steer the model, so model tool calls are treated as coming from the sender.
Who is trusted. Only admins: identities in admin_users plus those registered with ,qq.claim. When Bub merges several messages into one turn (it debounces bursts), the turn counts as an admin's only if every sender in it is an admin, so a member's request cannot ride on an admin's message sent right after it. A turn that reaches a QQ session without a QQ sender (a scheduled job, another plugin) is checked as an unknown member, never as an admin, even in a private chat (log: qq.security.unattributed_turn). QQ group owner/admin roles grant nothing, because whoever deploys the bot is not necessarily the group owner. The same person has a different openid in C2C and in each group, so identities are scoped (c2c:<user_openid>, group:<group_openid>:<member_openid>).
What each resource allows (defaults):
| Resource | Everyone else | Admins |
|---|---|---|
shell (bash) |
denied | approval for every command (group_shell) |
read files (fs.read) |
inside the workspace | inside the workspace |
write files (fs.write / fs.edit) |
denied | inside the workspace |
protected files (.env*, .git/, the state file) |
denied | denied |
send a file (qq.send media_path) |
only outbox/ and inbox/ |
same |
downloads (media_url, web.fetch, attachments) |
public internet only, every redirect checked; attachments may also come from QQ's media domains (qq.com.cn, qpic.cn, qq.com), whose URLs QQ supplies |
same |
code mode (run_code / code_mode) |
denied | denied |
read-only tools (tape.info / tape.search / tape.anchors / tape.handoff, skill, tool.describe, spill.read, help, qq.fetch_attachment, qq.view_image) |
group_tool_policy / c2c_tool_policy |
same |
session-changing tools (tape.reset, subagent, model, reasoning_effort, quit) |
denied | group_tool_policy / c2c_tool_policy |
| unlisted tools (other plugins, MCP, tools new in Bub) | denied unless matched by allowed_tools |
group_tool_policy / c2c_tool_policy |
In C2C, tools are admin-only by default (c2c_access); replies always work.
Approval. An admin's shell command posts a card with the full command (commands too long to show in full are refused, never truncated) and two buttons, clickable only by that group's registered admins. A tap on allow issues a one-time token bound to the session, requester, tool and exact arguments, valid for 240 seconds; the command then re-enters the Guard to use it. The card shows the command itself (other arguments on a # line) and flags destructive patterns such as rm -rf, find -delete, dd of= or curl | sh with a warning, and notes downloads (curl/wget/aria2c with a URL), which skip the plugin's address check; both are hints, approval stays the admin's call. There is no always-allow. Once approved, model-issued calls and admins' comma commands alike are handed back to Bub as a comma command (a model call is first rewritten as the equivalent ,bash command=…), so they run in the original session's execution environment, post their output to the chat and land on the session tape. Bub keeps command output out of the model's context, so how each approval ended (ran with its output, denied, expired, refused, failed) is added once to the session's next message as approval_results (the last 3, output cut at 500 characters).
Shell is not sandboxed by the plugin. Nothing in bub-qq confines what an approved command does. Run Bub in a container or similar and set shell_sandbox=external, or set group_shell=deny.
Becoming an admin. On first start with no admins, the log prints a one-time pairing code:
qq.admin.unclaimed no admins configured; send ',qq.claim K7QX2M9PHT' to the bot in a private (C2C) chat within 10 minutes to become its admin
- Add the bot as a friend and send
,qq.claim <code>in C2C. A code sent in a group is burned and replaced. - To act as admin in a group, send
,qq.claim groupin C2C, then post the returned group code (valid 1 minute, single use) in that group. Whoever asked for the code gets a private message when it is used, naming the identity it registered, so a code someone else replayed first can be revoked with,qq.admins remove. ,qq.adminslists admins;,qq.admins remove <identity>removes a registered one.
Five wrong codes lock that sender out for 10 minutes; the bot says so once and then ignores their claims until the lock ends, so nobody can make it flood the chat. Claim and admin commands are handled by the plugin and never reach the model or the tape. You can skip pairing by writing identities into admin_users.
Also in place: allowlists (allow_users / allow_groups) drop other chats before the model; llm_rate_limit_per_minute caps LLM calls per sender; qq.audit.llm / qq.audit.tool log lines record every call (requested_model in qq.audit.llm is the model asked for; with fallback_models, the trace's chat span shows the one that answered).
The command prefix follows Bub's BUB_COMMAND_PREFIX (, by default and in the examples below). Comma commands are accepted only from admins; anyone else's , message reaches the model as plain text. Each command is checked by the Guard exactly as Bub will run it. Ops commands are registered with exposure="command", so they never appear in the model's tool list.
| Command | Description |
|---|---|
,qq.claim <code> / ,qq.claim group |
Register as admin (see above); accepted from anyone |
,qq.admins / ,qq.admins remove <identity> |
List or remove admins |
,qq.version |
Show the installed bub-qq plugin version |
Any other registered Bub tool can be run as ,name args; an unknown ,name is run by Bub as a shell line and therefore follows the shell rule.
QQ is a channel listener surface. Start Bub gateway after the plugin is installed and configured:
bub gatewayThe workspace is pwd at start. Prefer a dedicated directory, so downloaded attachments land in inbox/ and plugin downloads in outbox/ at its root:
mkdir -p ~/Documents/bub-qq-work
cd ~/Documents/bub-qq-work
bub gatewayIf you start from / or $HOME (or a directory that is not writable), those folders move to ~/.bub/qq/ instead of the filesystem root. File tools still stay inside the process working directory.
For webhook mode, expose a public HTTPS URL that reaches the embedded server (host/port/path above) and register it in the QQ bot console. For websocket mode, ensure the console is not locked into a successful webhook-only configuration.
CLI chat (bub chat) does not replace the QQ channel; use gateway for QQ IO.
To see each event exactly as QQ sent it (e.g. to check what a quote or a forwarded chat record contains), set Bub's verbose: 1 (or BUB_VERBOSE=1): every event is then logged as a qq.transport.payload DEBUG line on the gateway's stderr. Bub writes no log file, so keep one with bub gateway 2>&1 | tee gateway.log. These lines hold message text, openids and attachment URLs with temporary download keys; turn verbose back off when done and do not share the log as is.
| Concept | Format / behavior |
|---|---|
| Session ID (C2C) | qq:c2c:<user_openid> |
| Chat ID (C2C) | c2c:<user_openid> |
| Session ID (group) | qq:group:<group_openid> |
| Chat ID (group) | group:<group_openid> |
| Inbound event | C2C_MESSAGE_CREATE, GROUP_AT_MESSAGE_CREATE, GROUP_MESSAGE_CREATE |
| Group activation | every received group message is is_active=true; delivery scope is set in the QQ client by a group admin |
| Command messages | inbound text starting with , is forwarded as Bub kind=command for authorized senders only (see Security); otherwise treated as plain text |
| Outbound | Default qq.send: text / markdown (msg_type = 0/2), rich media (msg_type = 7; plugin downloads media_url then multipart-uploads, or workspace media_path); passive reply preferred (msg_id + plugin-managed msg_seq), with an optional active fallback for groups (active_messages, plain text only — rich media does not take the active path) |
| Passive window | passive replies stop once the latest inbound timestamp is older than 60 minutes; groups fall back to active messages when enabled |
| Active opt-in | GROUP_MSG_RECEIVE / GROUP_MSG_REJECT (and the C2C twins) are persisted per group/user; sends are skipped when the admin explicitly rejected active messages |
| Debounce | needs_debounce = true |
C2C stays passive-only: official docs state active C2C push stopped being provided on 2025-04-21. Group active messages are opt-in on both sides (bot config active_messages + the group admin's QQ client switch) and consume platform quota.
Inbound non-command messages are encoded as a JSON string, including fields like:
messagemessage_idtype(textorattachment)sender_id(C2Cuser_openid, groupmember_openid)sender_name/sender_role/group_openid/chat_type/was_mentioned(group)dateattachments(when present)quoted_messages(when present: quoted message / merged-forward chat record content frommsg_elements, withmessage, optionalsender_name,attachmentsand nestedmessages; quoted attachments carry anindexnumbered after the message's own)message_type(0=text, 3=ARK card, 101/102/103=quote or chat record)ark_data(card payload whenmessage_typeis 3)
Images (PNG, JPEG, GIF, WebP) in messages addressed to the bot are attached to the message, so a multimodal model sees them; their entry in attachments is marked "attached": true, and they are downloaded (from QQ's media domains or public addresses, size-capped) when Bub builds the prompt. Other images stay metadata: the model opens one with qq.view_image(message_id, index), which returns the image itself. Other files are not downloaded on arrival; qq.fetch_attachment(message_id, index) saves one under inbox/<message_id>/. Both tools only reach messages from the same chat. A quoted message's attachments are reached through the quoting message, by their index in quoted_messages, and are attached like the message's own images; QQ signs their URLs afresh, so quoting an old image lets the bot fetch it again after the original URL expired or the gateway restarted. A refused address is reported to the model as Private network address check failed, access refused., followed by a sentence telling the model not to fetch the URL another way (bash, curl, scripts). Attachment downloads trust QQ's media domains, so they also work behind fake-IP proxies such as Surge or Clash. Attached images stay in the session's history until a handoff, so keep inbound_images: direct in busy groups.
In direct mode, normal replies should return final text and let Bub outbound routing call QQChannel.send; in tool mode, replies go through the qq.send tool. In both cases msg_seq is managed inside the plugin — never invent protocol fields.
- Config via
qq:YAML,BUB_QQ_*, andbub onboard - Access token from
https://bots.qq.com/app/getAppAccessTokenwith cached refresh (60s renewal window) aiohttpOpenAPI client withAuthorization: QQBot {ACCESS_TOKEN}- Embedded webhook receiver, callback validation (
op = 13), ed25519 signature flows - Webhook request verification (
X-Signature-Ed25519,X-Signature-Timestamp) - WebSocket receive path with reconnect / resume and optional sharding
- C2C / group inbound adaptation,
msg_iddedupe, 60-minute passive text or markdown replies qq.sendrich media: downloadmedia_url(public addresses only) or usemedia_path(outbox//inbox/only), multipart upload, thenmsg_type = 7(C2C/group isolated; passive window only)- Inbound images for multimodal models (attached to direct messages,
qq.view_imagefor others) and on-demand file download withqq.fetch_attachment - Plugin-owned message buttons (fixed templates);
INTERACTION_CREATEtype 11/12 is PUT-acked then adapted inbound - Group text receive/reply; message scope is controlled in the QQ client by a group admin
- In-memory send idempotency for the same
session_id + msg_id + msg_seq - OpenAPI error surfacing (HTTP status, platform
code/err_code, trace_id from the response header or body) and error catalog metadata - Guard-based security: admin pairing, per-resource rules, one-time approvals for shell, protected files, public-only downloads, allowlists, LLM rate limiting, and audit logs (see Security)
- Proactive group messages as a passive-reply fallback (
active_messages), with persisted per-group/user opt-in state from*_MSG_RECEIVE/*_MSG_REJECTevents - claw_cfg round-trip:
INTERACTION_CREATE2002 updates are persisted per group and 2001 queries echo the realrequire_mentionstate - 304023/304024 (async manual audit) treated as pending success instead of a failed send
- Selective silence in both reply modes:
<no_reply/>sentinel filtering (direct) and reply-by-tool with silence-by-omission (tool), driven by an injected per-mode system prompt block - Automated tests for config, auth, signatures, channel, webhook, websocket, gateway, plugin onboarding, C2C/group services, security policies, reply modes, and the platform store
- QQ Guild
- Sandboxing shell commands (declare an external sandbox with
shell_sandbox) - Wider webhook event coverage beyond validation, basic
{"op":12}ack, C2C/group messages, message-toggle events, interaction query/update, and button/menu clicks - Active C2C push (discontinued by the platform on 2025-04-21)
- Markdown in active group messages (requires a registered template; active path sends plain text)
- Dynamic in-process shard rebalancing after startup
From official QQ Bot docs (API auth + event subscription):
Auth / OpenAPI
- Token:
POST https://bots.qq.com/app/getAppAccessTokenbody{ appId, clientSecret } - Token lifetime up to
7200seconds; refresh within60seconds of expiry returns a new token while the old remains valid during the overlap - OpenAPI unified endpoint:
https://api.bot.qq.com(the legacyhttps://api.sgroup.qq.comcan be restored viaopenapi_base_url) - Header:
Authorization: QQBot {ACCESS_TOKEN} - Failure response body carries
err_code,message,trace_id(legacy format usescode; the plugin accepts both); trace_id is also exposed via theX-Tps-trace-IDresponse header
Events / transport
- Production webhooks require HTTPS; ports
80,443,8080,8443 - Webhook and WebSocket are mutually exclusive once a valid HTTPS callback is configured
- Validation requests use
op = 13; response must includeplain_tokenand ed25519 signature overevent_ts + plain_token - Normal webhook verification uses
timestamp + raw_body - Event payload shape:
{ id, op, d, s, t } C2C_MESSAGE_CREATE/GROUP_AT_MESSAGE_CREATEintent:GROUP_AND_C2C_EVENT(1 << 25)- Documented
C2C_MESSAGE_CREATE.dfields used here:id,author.user_openid,content,timestamp,attachments - Group event
dfields used here:id,group_openid,author.member_openid,content,timestamp,mentions,attachments - Group send:
POST /v2/groups/{group_openid}/messageswith the same body as C2C (msg_id,msg_seq, pluscontent+msg_type = 0,markdown.content+msg_type = 2, ormedia.file_info+msg_type = 7) - Rich-media upload: local multipart (
upload_prepare/upload_part_finish/filesmerge withupload_id) thenmsg_type = 7; C2C and group files cannot be mixed - WebSocket close codes
4914/4915are fatal; codes such as4006–4009and4900–4913are treated as reconnectable
Use the QQ docs for app creation, credentials, event subscription, and callback settings (APPID, SECRET, webhook URL, intents, etc.).
uv run --package bub-qq pytest -qTests use mocks — no live QQ network required.
Same as the bub-contrib repository.