qq-ai-bot
A production-grade open-source QQ ↔ AI bot scaffold built for self-hosted NapCat / LLOneBot deployments and ACP-compatible local agents. It keeps transport, session orchestration, and agent execution clearly separated so the repo feels more like infrastructure than a one-off chat demo.
If this repo already saved you OneBot / ACP wiring time: the shameless fast path is to tip ¥9.9 / ¥19.9. If you want something concrete back, jump straight to the ¥29.9 quick read or ¥99 async packaging pass for your own bot / agent repo.
Why this repo exists
- keep QQ transport logic independent from any specific model vendor
- reuse an ACP-style local agent bridge instead of hard-wiring one chatbot backend
- preserve session continuity per private chat or group conversation
- stream plan / tool / progress events back into QQ without inventing a custom protocol
- make the repo feel like a real bot infrastructure scaffold, not a fragile demo
- leave room for Telegram / WeChat / Feishu-style channel adapters later
- support local self-hosted agent workflows and operationally cleaner deployments
- give OneBot + ACP users a faster starting point than wiring everything from scratch
System shape
High-level view of how transport, session orchestration, and ACP execution stay separated.
What the user actually sees
A real strength of this repo is that it can stream progress updates back into QQ instead of only dumping a final answer.
Why this repo looks worth betting on
- released as v0.1.0 with CI, Docker publishing, and build metadata now exposed in status endpoints
- /metrics now exposes Prometheus-style runtime counters for connection state, traffic, ACP calls, and conversation gauges
- has a public roadmap instead of pretending the current shape is the final shape
- actively invites contributions on session storage, richer media, and stronger runtime visibility
- better than a throwaway demo: it already has architecture notes, quickstart docs, and health endpoints
- best next high-signal OSS work here is Redis session store, richer media, and tracing / deeper observability
- if you want your own bot repo packaged this clearly, the blunt paid read starts at ¥29.9
Useful links: roadmap · contributing · help wanted issues
What you get today
- OneBot 11 reverse and forward WebSocket modes
- private chat + group mention triggers
- persistent conversation sessions keyed by QQ conversation
- image download and pass-through into the ACP agent flow
- progress message streaming from plan / tool events
- health and readiness endpoints
- mock ACP agent for local integration work
- ESLint, typecheck, tests, and GitHub Actions
- Docker packaging for cleaner deployment
- clear extension path for richer media and stronger observability
Quick start
- Clone the repo and install dependencies with
npm install. - Copy
.env.exampleto.env. - Start with the mock ACP agent first to validate the bridge path.
- Point NapCat / LLOneBot at the reverse WebSocket endpoint and run
npm run dev.
Full config examples, deployment details, and the session / progress model live in the repository README and architecture doc.
Who this is for
- engineers building self-hosted QQ bot infrastructure
- developers experimenting with ACP-compatible local coding / chat agents
- people who want a better starting point than mixing transport code and model code together
- maintainers who want a clearer architecture before adding Redis, tracing, or moderation logic
- hackers exploring multi-channel bot infrastructure after starting from QQ / OneBot
- anyone who wants a modern repo that feels more like middleware / orchestration than a toy bot
Support
If qq-ai-bot saved you OneBot + ACP plumbing time, the cleanest support path is a small direct tip
or support via the support page. Best payment note: qq-ai-bot.
- ¥9.9 / ¥19.9 — thank-you tip if this repo saved you setup or wiring time
- Best payment note —
qq-ai-botorqq-ai-bot setup - Fastest path — scan WeChat Pay / Alipay on the support page
- ¥29.9 quick read — one blunt paragraph + top 3 fixes for your own bot / README / landing page
- ¥99 async review — GitHub profile, pinned repos, README cleanup, or one focused landing page
- Best fit — if you want your own AI / infra repo to feel less toy-like and more hireable
If you want broader GitHub / README packaging feedback for your own bot, agent, or infrastructure repo, the lightweight async review options are on the review page.
Tip in 10 seconds
If this repo already saved you an hour of wiring, debugging, or README archaeology, do not overthink it.
Scan one of these, leave qq-ai-bot or qq-ai-bot setup as the note, and you're done.
If you want something concrete back, use the ¥29.9 quick read or
¥99 async review path instead.
Fastest path for a direct ¥9.9 / ¥19.9 thank-you tip if qq-ai-bot saved you setup time.
Same shortest path. Best payment note: qq-ai-bot, qq-ai-bot setup, or bot repo read.
Roadmap tie-in: direct support helps keep work moving on Redis session storage, richer media, tracing, and the next production-grade polish round.
Low-friction promo ask: if you share this repo in a QQ / OneBot / self-hosted AI group, the most useful link is the project page plus the note OneBot 11 + ACP + /metrics + Docker demo.
July offer: the first paid request this month gets one extra public page / README in the same async pass.