A KohakuTerrarium package that puts a creature into QQ private chats and QQ group chats.
The library surface is a trigger and a few tools:
qq_feed(trigger) wakes the creature with new chat as incremental updates.qq_send(tool) is the only way the creature speaks in QQ.qq_history(tool) reads older messages from the on-disk log.qq_sticker(tool) finds stickers in the user's sticker folder.qq_image_search(tool) finds images on the web to look at before sending.qq_watch(tool) lets a creature install a feed itself.
Plugins: qq_character (character files), qq_router (one creature per chat),
qq_status (dashboard panel), qq_guard (hides graph / Drive tools),
qq_web_guard (refuses web_fetch to private addresses).
Text the creature writes freely never reaches QQ; it shows only in the console or the dashboard. So silence is the default, and the creature decides when to speak.
Requires KohakuTerrarium 2.2.0 or newer (below 3.0.0): the first core with the
refactored module layout this package imports, on top of the UI extension
system and the path_arguments, trigger bind_host and
host_resources_allowed hooks it relies on.
kt install https://github.com/Kohaku-Lab/kt-qqbotkt-qqbot login # prints a QR code; scan it with mobile QQ
kt-qqbot login --manual # enter an existing bot's AppID and AppSecret
kt-qqbot status # list stored bots and check the default one
kt-qqbot logout [APPID]The QR login asks QQ to create or bind a bot on the scanning account and
returns its AppID / AppSecret. The scan page shows the caller as a third-party
bot. Credentials are saved to ~/.kohakuterrarium/qq-bot/credentials.json
(mode 0600). QQBOT_APPID and QQBOT_SECRET override the file.
One shared creature for every chat:
kt run @kt-qqbot/creatures/qq-group-chat # or start it from kt serveOne creature per chat (each with its own context and session):
kt run @kt-qqbot/creatures/qq-router # or start it from kt serveThe example creature has no character. To give it one, put files in
~/.kohakuterrarium/qq-bot/ (KT_CONFIG_DIR is honored):
character.md- optional
character/*.md, added in name order
The qq_character plugin adds them to the system prompt as ## Character.
Changes apply the next time the prompt is built.
A persona image character.png (or .jpg, .jpeg, .webp; the first in that
order wins, the others are logged as ignored) shows what the character looks
like. qq_character downscales it once to at most 768 px (cached by file hash
under qq-bot/cache/) and pins it right after the system prompt as a
reference image when the core supports pinned messages; it re-pins on change
and unpins when the file is removed (option persona: false turns this off).
qq_send(media="persona") sends that file; qq_send's character_directory
option must match qq_character's directory if you moved the folder.
| Key | Default | Meaning |
|---|---|---|
bot |
default bot | AppID to use |
conversations |
all |
all, c2c, groups, or a list of chat handles / group:<openid> keys |
wake |
ambient |
mention: only private chat, @-mentions, replies to the bot. all: every message. ambient: direct messages at once, otherwise after quiet_period or every_n messages, never sooner than cooldown after the last ambient wake |
quiet_period |
6 |
seconds of silence before an ambient wake |
every_n |
5 |
pending messages that force an ambient wake |
cooldown |
15 |
seconds between ambient wakes in one chat |
batch_delay |
0.5 |
seconds to wait so a burst lands in one delivery |
backfill |
20 |
on a chat's first delivery, how many messages from before the feed started to show as <qq_backfill> |
max_delivery |
100 |
most lines per chat in one delivery; older ones become "N earlier messages not shown; use qq_history" |
unseen_history |
backfill |
backfill: undelivered messages from before the feed started show as history; new: as new chat |
hold |
true |
qq_send returns chat that arrived meanwhile instead of sending, once |
mid_turn |
true |
chat that arrives while the creature is in a turn is folded into that turn before its next model call |
typing |
false |
send the private-chat typing indicator on wake (uses a reply slot) |
images / image_detail / max_images |
true / auto / 8 |
inbound images as vision input |
image_timeout |
5.0 |
seconds per inbound image; images download in parallel and a slow or failed one is skipped, never holding back the text |
subscriber |
the host creature's id (from core bind_host) |
cursor key; set it only to share or pin a cursor |
The creature can also install a feed itself: add the qq_watch tool
(type: package, module: kt_qqbot.tools, class: QQWatchTool). A feed
installed this way keys its cursor by the creature.
qq_send(message?, to?, reply_to?, media?, media_type?),
qq_history(chat?, before?, limit?). Both only reach chats the creature's feed
delivered.
media is one item or a real list of items, sent in order. An item is:
| Item | Meaning |
|---|---|
m12.1 |
attachment 1 of message m12 in the target chat, as tagged in the feed ([image m12.1], [file:x.pdf m12.3]) |
u_ab12cd/m12.1 |
the same, from another chat this creature's feed delivered |
sticker:<name> |
a sticker from qq_sticker |
img:<n> |
candidate n of this creature's latest qq_image_search (15 minutes) |
persona |
the persona image character.png / .jpg / .jpeg / .webp |
| a path | a file inside the creature's working folder (files the creature made can be sent) |
| an https URL | QQ downloads it |
Chat attachments are resent from QQ's URL; if that fails, or the message is
older than a day, the copy kept when the feed downloaded it is used (images
only; at most 500 kept per bot). Otherwise the tool says the handle is too old. A string is always one item; a JSON-looking string is not split,
so a sandbox plugin checks exactly the paths that are read (qq_send declares
media as a read path). Text goes first, then each media item as its own message; each
message uses one passive-reply slot. media_type (image, video, voice,
file) overrides the type inferred from the extension or MIME type.
- Voice must be SILK. Other audio is converted when the optional codec is
installed (
pip install "kt-qqbot[voice]", which addsgraiax-silkcoder); without it the tool answersNOT SENT: voice needs silk; install kt-qqbot[voice]. Voice URLs must point to a.silkfile. - Local files over 5 MB are refused. QQ's chunked upload is not implemented;
QQHub.chunked_uploader(aChunkedUploader) is where it plugs in. - Group chats refuse
filemessages unless the tool optionallow_group_files: trueis set.
qq_send options: max_chars (default 2000), allow_group_files (default
false), media_roots (extra folders local media may come from; by default only
the creature's working folder, symlinks resolved), mention_format (plain
by default: @<name> is sent as text, because QQ shows the native mention tag
raw in plain-text messages; set markdown if your bot has QQ markdown
permission: group text is then sent as a markdown message and @<name> of a
known member becomes a real mention, <qqbot-at-user id="…" />; a name two
members share always stays text).
Mentions of other members in incoming messages show in the feed as @<name>.
| Option | Default | Meaning |
|---|---|---|
template |
@kt-qqbot/creatures/qq-group-chat |
creature to build per chat; it must have a qq_feed trigger |
bot |
default bot | AppID |
conversations |
all |
all, c2c, or groups |
Creature ids are qq-<appid>-<c2c|group>-<openid> (safe as file names). Its
creatures read pending chat as new (unseen_history: new).
The router adds and re-adopts chat creatures in background tasks. Code that
drives it directly (tests, tooling) calls await router.wait_idle() to know when
every spawn started so far has finished; until then a chat creature may be in the
engine without its history, feeds or hub reference.
directory (default ~/.kohakuterrarium/qq-bot), heading (Character),
max_chars (20000), persona (true). It logs "Character loaded" (file names,
size) and "Persona image loaded" (file, pixels, bytes) on first load and on
change; never the content.
Put images (png, jpg, gif, webp) in ~/.kohakuterrarium/qq-bot/stickers/
(subfolders are fine). Names come from the file names. An optional
stickers/tags.yaml adds words:
thumbs_up.jpg: [ok, agree, good]
cats/sleepy-cat.gif: {tags: [tired], mood: sleepy}
happy.png: excitedqq_sticker(query) returns up to 4 sticker:<name> handles with small
previews. Options: directory, max_results (at most 8). qq_send takes the
folder from its sticker_directory option (same default); a sticker handle can
never leave that folder.
qq_image_search(query, count?) returns 3-6 candidates as img:<n> with
low-detail previews, so the creature looks before it sends. Backends:
- Brave Search API when
BRAVE_API_KEYis set (or theapi_keytool option), images endpoint withsafesearch=strict; - otherwise DuckDuckGo images through the
ddgslibrary (the one coreweb_searchuses), safe search on; no key needed.
Guards: https only; previews are fetched only from globally routable addresses,
must be image/* and at most 1 MB; blocklist (domains, subdomains included);
rate_limit_per_minute (default 6, per creature and chat). The full image is
sent by URL, so QQ downloads it.
qq-group-chat includes core web_search and web_fetch. Core web_fetch
has no private-address check, so the qq_web_guard plugin refuses fetches to
loopback, private, link-local and other non-global addresses. Redirects the
fetch backends follow are not re-checked.
- A creature started from the dashboard runs privileged and gets graph
(
group_*) and Drive (drive_*) tools.qq_guardhides them from the model and refuses them if called (allow_toolsre-enables names). The example creature has it on. - Under multi-user mode the QQ bot is for admin creatures only:
qq_feed,qq_send,qq_history,qq_watchand the router refuse other creatures ("QQ bot is available to admin creatures only"). This uses the corehost_resources_allowedhook. - One process per bot: a hub takes
~/.kohakuterrarium/qq-bot/data/<appid>.lock; a second process gets aBotInUseerror. - Chat text, names and file names are escaped before the creature reads them, so a QQ message cannot open or close a feed block or fake a line.
- Inbound images are fetched only from globally routable addresses. The host is resolved once for the check and again for the download, so a DNS-rebinding host could still differ; attachment URLs come from QQ, which limits this.
kt-qqbot logoutwhile a server runs: the server notices the changed credential file within a few seconds (on its next feed poll or send) and stops that bot.
QQ bots can only send passive replies: each message rides on a recently received message (any message, @-mention or not). Per QQ's rules:
| Chat | Window | Replies per received message |
|---|---|---|
| group | 5 min | 5 |
| private | 60 min | 4 |
QQ shut down active (unprompted) messages on 2025-04-21, so kt-qqbot never
tries one. When no reply is left, qq_send answers "the reply window has
closed" without calling QQ. Errors 40034128 / 40034005 / 304103 close that
slot; 40054005 (duplicate msg_seq) is retried once with the next seq. The
private-chat typing indicator (typing: true) uses a reply slot and is sent
only when the slot keeps at least one reply for the answer.
When a group owner turns on 获取群内全部消息, every group message (including
@bot ones) arrives as GROUP_MESSAGE_CREATE. kt-qqbot treats a message as an
@-mention when a mentions entry has is_you, when a mentions entry's id
equals the bot's id from READY, or when the content has a <@id> / <@!id>
tag for that id (records.mentions_bot). The real payload shape is not
confirmed yet. To check it, set debug_raw_events: 2 on the qq_feed
trigger, send one @-message and one plain message, and read
~/.kohakuterrarium/qq-bot/debug/raw-<time>.jsonl (mode 0600; payloads only,
no tokens). It is off by default.
Kept in ~/.kohakuterrarium/qq-bot/data/<appid>.kvault (KohakuVault):
- each chat's message log (newest 2000 messages), type, handle, first-seen and last-seen times;
- sender aliases and the QQ names seen (at most 1000 stored per chat);
- one cursor per feed per chat, so a resumed creature gets only what it has not seen;
- passive-reply slots (
msg_id, replies used, lastmsg_seq), pruned when their window ends; - the gateway
session_idand lastseq(seq written at most once a second and on shutdown); on start the hub sends RESUME, and QQ replays what was missed during a short downtime; replayed events are deduplicated by message id; - the bot's own identity from READY (id, name …), so mention detection works before the first READY and the settings page shows the bot's name.
Creatures: a creature with a session resumes with its conversation through the
normal kt resume path. Router-made chat creatures adopt their own session file
(<session_dir>/qq-<appid>-<kind>-<openid>.kohakutr) when it exists.
Not kept:
- events older than QQ's RESUME window, or any event after an INVALID_SESSION (QQ has no history API for bots, so they are lost);
- the private-chat typing state and pending delivery timers (recomputed);
- downloaded inbound images (they are fetched again only if still delivered).
The package adds three things to the kt serve dashboard (UI extension SDK v1,
plain ESM in ui/, no build step):
- Settings → QQ Bot (package owner
kt_qqbot.ui_owner:QQBotUI): bound bots and their gateway state, Bind with QR (the same flow askt-qqbot login; the dashboard draws the QR code and shows a new one when it expires), cancel, manual AppID / AppSecret entry, Test and Unbind. Running bots pick up new credentials at once. The secret is never sent back to the browser. Under multi-user mode only admins can bind, unbind or enter credentials. - QQ chats side panel (owner
plugin:qq_status): for the focused creature, its chats, unread count, last messages and free passive-reply slots, plus the connection state, updated live. It shows when the creature has theqq_statusplugin (the example creature does). - qq_send renderer: tool calls show as a chat bubble with the text, media and whether it was sent.
The QR encoder is a vendored copy of qrcode-generator (MIT), see
ui/vendor/README.md.
max_chats (default 30), last_messages (default 5).
uv venv && uv pip install -e /path/to/KohakuTerrarium -e ".[dev]"
pytest # unit + integration
npm install && npm test # dashboard UI (vitest)
KT_QQBOT_LIVE=1 pytest tests/live # real platform, after kt-qqbot login