Ditching QQ's Official Bot for a Self-Hosted SnowLuma + AstrBot Stack
Anyone who self-hosts a QQ bot runs into the same tiered API and broken card messages; the specific compose flags and networking steps here turn what otherwise becomes hours of trial and error into a checklist. The same ptrace-based pattern also applies on other platforms whose official bot APIs throttle individuals.
QQ's official bot productized as an enterprise service channel, and individual developers pay for that. A batch of APIs stays gated behind gray-scaling, friend private messages never existed, and card messages render as placeholder garbage on TIM, the desktop client. The replacement stack keeps QQ itself in the loop instead of reimplementing its protocol from scratch.
SnowLuma runs a real QQ client inside Docker, injects hooks via ptrace, and presents a OneBot v11 interface. AstrBot takes the conversation side: model API calls, plugins, persona. One outbound WebSocket carries events from SnowLuma to AstrBot's reverse WS listener; the writeup spells out why the opposite direction fails.
The migration notes name where the official docs mislead: SnowLuma's guide describes server-mode OneBot only, the manual JSON editing it prescribes has a WebUI equivalent with fewer failure modes, and the two compose stacks land on separate Docker networks that never see each other. Parameter errors that break silently, like a missing SYS_PTRACE capability and the 1GB shm bump QQ's Chromium runtime needs, get pinned down along with the security posture: port 6081 is a remote desktop into the QQ account, and third-party clients carry ban risk.
QQ's official bot productized around enterprise service entries, so individual hobbyists become second-class API users; the feature gating and missing private chat follow from that positioning, not from oversight.
SnowLuma's docs describe the container as a OneBot server, but the AstrBot integration needs it as the outbound WS client; the whole setup depends on flipping that assumption, and the WebUI holds the one field the docs never mention.
ptrace injection of a real QQ client trades protocol-reimplementation risk for behavioral-detection risk; it looks normal to Tencent's servers, but the account still lives or dies by how the hook behaves under actual use.
The security section treats the bot as a remote desktop and an account risk rather than a web service; that framing changes what constitutes acceptable exposure and which account to choose.