Estrella Bot · QQ-BOT-Creative

Turn a spare QQ account into an AI group member. It chimes in, picks up running jokes, lurks, and occasionally speaks up on its own.

OneBot v11 · NapCat · a local model or DeepSeek / Zhipu / Qwen · a zero-build web console

Quick start

Two supported routes. Both end at the same console, on 127.0.0.1:8788.

macOS / Linux — Docker (the recommended route on macOS). NapCat runs in a container, so your own QQ client is never touched:

bash scripts/bootstrap.sh      # check the environment, start the container, print the WebUI login URL
node scripts/check-onebot.js   # confirm the protocol side is alive and list the groups you are in
npm start                      # run the bot

Windows — no Docker at all. Download the packaged build from Releases, unzip it, then run 1-SETUP.bat → 3-START-NAPCAT.bat → 2-START.bat.

Two things you always supply yourself: an OneBot v11 implementation (in practice NapCatQQ) and a model — a local one, or an API key. Step-by-step instructions, including what to do when a step fails: USER-GUIDE.md.

An OneBot v11 bridge that plugs a spare QQ account into any OpenAI-compatible model, plus a zero-build browser console — switch brains, watch state, edit the persona, manage skills and memory. All by clicking.

QQ alt ──► NapCat (Docker, OneBot v11) ──► bridge src/index.js ──► model
             ws/http :3000/:3001            │ trigger / context / prompt / splitting
                                            ├─ local  : MLX(:8080) / QwenChat(:8765)
                                            ├─ cloud  : DeepSeek API
                                            ├─ cloud  : Zhipu GLM (only one with web search + vision)
                                            └─ cloud  : Qwen (free grant per model, 90 days)
                      ┌─────────────────────┴─────────────────────┐
                      │  console panel/server.js (:8788, 127.0.0.1) │
                      │  ├─ frontend panel/next/ (static, polls /api/state every 3s)
                      │  └─ starts/stops the bridge, 4 brain presets, custom workspace
                      └───────────────────────────────────────────┘

Estrella Bot is the name of the software. The former name in the title is kept in exactly one place so that existing links, bookmarks and search results still land here — it is not used anywhere else. The project began as qq-bot and was renamed twice (2026-09-17, then 2026-10-11); the full history is in CHANGELOG.md. The GitHub slug stays ai-bot-groupmate on purpose. The launcher is Estrella-Bot.app. This English README is the default. The Chinese edition lives in README.zh-CN.md and is the authoritative one when the two differ.

Just want it running? Start with the User Guide — install, sign in, configure, start. Written for people who don't want to read the source first.

1. Local self-test (no QQ, no model)

The fastest way to see whether the code is sane — it needs neither a QQ account nor a model endpoint:

npm test        # behaviour regression (all local mocks)
npm run verify  # the full four-layer gate: contracts + regression + presets + panel

2. Protocol side: three routes (read this before you start)

Route A (recommended on macOS): Docker + Linux arm64. NapCat's Linux arm64 support is current, the container bundles a matching Linux QQ, and your local QQ client is not touched at all.

bash scripts/bootstrap.sh     # check env → start container → print WebUI login URL
node scripts/check-onebot.js  # liveness probe + list joined groups (get group ids here)
npm start                     # run the bridge

Full steps: INSTALL-DOCKER.md.

Route B: native macOS — currently blocked. NapCat's Mac installer only whitelists QQ builds 6.9.82-40768 … 6.9.93-47354, while current QQ is past that; Tencent does not archive old versions. Getting this route working requires a delisted QQ build. Do not install QQ from a third-party mirror — the chat client holds every credential for that account.

Route C: native NapCat on Windows — the route for Windows users. Windows needs no Docker: NapCat ships a current native Windows build (the container exists on macOS only because its version allowlist stopped half a year ago; see routes A/B above). This drops Docker Desktop and WSL2 from the chain entirely, and NapCat's WebUI still runs on 6099 with OneBot's WS / HTTP still on 3001 / 3000 — identical to the bridge defaults, so neither the bridge nor the console changes.

npm install
copy config.example.json config.json

Installing NapCat, opening the two channels, the nine platform differences (quit the desktop QQ before scanning / keep the NapCat window alive / no local model / memory card / instance count / the Docker step / the console window), and what to report back from your first real-machine run:

👉 Full install steps: USER-GUIDE.md · section 9

3. Four brain presets

The console organises model settings into four presets. Switching only materialises one of them into flat fields for the bridge; presets never bleed into each other, and per-brain edits survive switching away and back.

On "free" — it is not one thing. local never costs anything; some Zhipu models are permanently free; Zhipu's gift packs and every Qwen model run on a grant that expires. All three cases are decided by a single rule (src/free-quota.js), and the console shows which one applies plus when it ends. Only Zhipu exposes a live balance — Qwen's usage API is account-scoped, so the console says "check the website" rather than inventing a number.

Custom models — bring your own key

If none of the four fit, add your own. Any OpenAI-compatible endpoint works: a company gateway, a self-hosted relay, LM Studio on another machine, or a provider we have not wired up. Give it a name, paste the address and your key, fill in the model name, then tick what it can actually do: