# Stapxs QQ Lite: a OneBot-compatible QQ client in Vue, shipped to four platforms > A third-party QQ client that speaks the OneBot protocol to a bot backend and renders it as a Vue single page application, with Electron, Tauri and Capacitor builds from the same source and a Server-Sent Events mode for a lighter connection. The awkward parts are the ones the README is upfront about, namely that a bot backend is required and that using one carries risk. **Stapxs/Stapxs-QQ-Lite-2.0** — 一个兼容 OneBot 协议的第三方 QQ 客户端。 Web、全平台实现！ - Repository: https://github.com/Stapxs/Stapxs-QQ-Lite-2.0 - Website: https://stapxs.github.io/Stapxs-QQ-Lite-2.0/ - Stars: 1,341 · Forks: 103 - Language: Vue - License: AGPL-3.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/stapxs-stapxs-qq-lite-2-0 ## What the client is, and what it needs to work Stapxs QQ Lite is an unofficial web QQ client compatible with the OneBot protocol, built with the Vue stack, implemented across web and all platforms. The architecture is the thing to understand before anything else. The client needs a QQ bot backend to provide the service, and because deploying a bot backend is relatively involved, the README directs you to a Bot compatibility issue in the repository to see which bots are currently supported and to read the deployment documentation for the one you choose. So this is not a standalone chat client. It is a frontend for a bot, and the bot is the component that holds the QQ session and talks to the network. The client is the interface, and it is a Vue single page application talking to that backend over the OneBot protocol. The README also states the terms plainly. The web application is for learning and exchange only and should not be used for other purposes, and copyright disputes should be raised as an issue to be negotiated. The project is licensed AGPL-3.0-only, and the repository is not archived with the last push on 2026-10-15. The releases are v3.5.2 from 2026-10-13, v3.5.0 from 2026-07-30 and v3.4.1 from 2026-06-23, and the default branch is `next` rather than `main`. The feature list is the usual QQ client surface, including complex message display, forwarding, replies and recall, group files, group announcements, part of the group settings, highlighted messages, images, favourite emoji and file sending, plus a light and dark mode that switches automatically and a layout that adapts to a portrait screen. ## Four build targets from one source tree The build story is what distinguishes this project, because the same application is compiled four ways. The web build is the base case. Stapxs QQ Lite is a Vue single page application, and building it for a web server produces output in the `dist` directory. The scripts are `yarn dev` for local development, `yarn lint` for the code check and automatic formatting, and `yarn build` for the build itself. ```bash yarn dev yarn lint yarn build ``` Electron support arrived in version 2.3.0, with `yarn dev:electron` and `yarn build:electron`, and the output is the Electron package. Tauri support arrived in version 3.2.0, with `yarn dev:tauri` and `yarn build:tauri`, and the build output goes into the Tauri bundle directory. The README notes that Tauri does not support cross-platform building, so it has to be built on the target platform, and it shows a cross-architecture example with a dmg bundle and a way to list the supported targets with rustup. Capacitor support arrived in version 3.0.0 for mobile. On Android you can open the project in Android Studio through `yarn open:android` and build a signed bundle or APK, or use `yarn build:android` and adjust the key store configuration in `capacitor.config.ts`. On iOS you open it in Xcode through `yarn open:ios` and archive, or use `yarn build:ios`, which runs a shell script that uses the default developer certificate from the keychain. So the same product exists as a web app, a PWA, an Electron desktop app, a Tauri desktop app and a mobile app, and the platform-specific features differ between them, which the README describes as providing some platform-specific features. ## The SSE mode, and why it is a build-time decision Stapxs QQ Lite supports an SSE mode, in which the application connects to the QQ bot backend over HTTP Server-Sent Events plus an HTTP API, which provides a faster and lighter connection. It is even possible to disable the SSE notification push entirely and communicate only over the HTTP API. The configuration is in the `.env` file, and the values are prefixed with `VITE_APP_SSE`: ```ini VITE_APP_SSE_MODE=true VITE_APP_SSE_SUPPORT=true VITE_APP_SSE_EVENT_ADDRESS=api/_events VITE_APP_SSE_HTTP_ADDRESS=api ``` `SSE_MODE` is the master switch, and `SSE_SUPPORT` decides whether SSE event push is supported at all. Setting that second one to false means only the HTTP API is used for communication, and the README spells out the consequences: you will not receive new message pushes or notification pushes, and the chat panel will not update automatically, although you can still fetch new messages by reloading the panel. The important constraint is that SSE mode cannot be switched dynamically. You have to modify the environment configuration before the build, and once SSE mode is enabled the page can no longer use the other connection modes. That is a consequence of how the frontend is built, since the mode is compiled into the bundle through the `VITE_` prefixed variables. It is a reasonable design for a client that has to work across browsers and desktop shells, where the connection strategy has to be known at startup, but it means a deployment has two builds to maintain if both modes are wanted. ## Running it: GitHub Pages, npm, Docker and a plugin There are four ways to get hold of the client, and they suit different situations. The first is the hosted build. The repository enables GitHub Pages, and every push to the main branch is automatically built and published, so there is a live online version you can use directly. The second is npm, and it is the easiest self-hosting route. The web version is published to npm as `ssqq-web`, and you can start it with the npx tool: ```bash npx ssqq-web hostname=127.0.0.1 port=8081 ``` The third is Docker. The project supports Docker deployment natively, and the image is pulled with: ```bash docker pull ghcr.io/stapxs/stapxs-qq-lite-2.0:latest ``` and if you cannot reach GHCR or it is slow for you, there is a mirror: ```bash docker pull ghcr.nju.edu.cn/stapxs/stapxs-qq-lite-2.0:latest ``` The README says to expose the container's 8080 port and that the 80 port can be ignored. The fourth is as a NapCat plugin, installable from the NapCat plugin store with a one-click install button. The release artifacts are the other route, named something like `Stapxs.QQ.Lite--web.zip`, and you can unpack them onto your own web server. The repository also lists the supported package managers in an issue, so a desktop install can update itself rather than needing a manual download each time. ## The bot compatibility question, and the risk note The FAQ section has three questions, and two of them are about the risks rather than the mechanics. The first is whether you can use another QQ HTTP bot. The answer is that if it is compatible with the OneBot 11 protocol you can try to connect, but because of differences in message body formats and interface extensions, in most cases it will not work completely. The list of bots that are known to work is in the project wiki. That is an honest and useful answer. OneBot is a specification with a common core and divergent extensions, and a client that relies on a particular bot's extensions will not run against a different one. The second is whether there is risk in using a bot. The answer is that using a QQ bot service may carry risk, that this risk is not caused by Stapxs QQ Lite but by using a QQ bot service itself, and that you should read the documentation of the bot you use to understand the risk. Putting the responsibility in that place is a deliberate choice for a project whose author is not the author of the bot, and it matches the disclaimer at the top of the README. The third question is what to do when you hit a problem, and the answer is to open an issue, with bug reports and optimisation suggestions both welcome. There is a separate FAQ issue for usage and deployment questions. ## The repository, and the map API key you should replace The top level of the repository shows a project with several build systems in one tree. There is `src/` with the application, and inside it the Tauri and Capacitor projects, plus `build/`, `scripts/`, `capacitor.config.ts`, `electron-builder.yml` and `electron.vite.config.ts`. Then three directories whose names describe their purpose: `ssqq.capacitor-onebot-connector/`, `ssqq.napcat-plugin/` and `ssqq.npx-web-quick-start/`, which is the piece published to npm as `ssqq-web`. The build uses Yarn in its modern form, with a `.yarn/` directory and a `.yarnrc.yml`, and a `.tool-versions` file alongside a `.envrc`, which suggests asdf or direnv is in use for the toolchain. One configuration detail deserves attention. Stapxs QQ Lite uses the AMap API to show the location sharing map, and the `.env` file ships with a default AMap API key. The README says that if you are going to self-host, you should apply for your own API key and replace the default, and it strongly recommends using your own because the default key has a usage limit. That is worth taking literally. A default key baked into a public repository is a shared resource, and a self-hosted deployment that attracts traffic will spend someone else's quota. The `package.json` is the other place to look for the shape of the project. The name is `stapxs-qq-lite` at version 3.5.2, the licence field is AGPL-3.0-only, the type is module, and the scripts cover linting with ESLint across every JavaScript and TypeScript extension, type checking with vue-tsc against `tsconfig.web.json`, a combined `check` script, and separate build and dev scripts for the web, Electron, Tauri, iOS, Android and a NapCat variant built with the `VITE_NAPCAT` flag. ## Where Stapxs QQ Lite is the wrong choice The first wrong case is a deployment with no bot backend. The client is a frontend, and without a bot it displays nothing. That means the operational work is the bot, and the bot deployment is the part the README calls involved and sends you to an issue to read about. The second is a team that wants to use an arbitrary OneBot implementation. The FAQ says the protocol compatibility is necessary but not sufficient, because message body formats and interface extensions differ, and in most cases it will not work completely. You are choosing a specific supported bot, not writing against a specification. The third is an organisation that cannot accept AGPL-3.0, or that has a policy against unofficial clients of a proprietary service. The licence is AGPL-3.0-only and the README restricts the project to learning and exchange, so both the licence and the upstream terms of the service are constraints on commercial use. The fourth is a user who wants one client on every platform from one install. The four build targets are four toolchains: Node and Vite for the web, Electron, a Rust toolchain for Tauri, and Android Studio and Xcode for Capacitor. Building the mobile targets needs the platform SDKs and the signing material, and the Tauri build cannot cross-compile. The fifth is a project that needs a stable client. The default branch is `next`, the release cadence is every few weeks with version numbers in the 3.x range, and the README describes the feature set as complete but not as good as the official client, which is a candid admission of where it sits. ## Conclusion Stapxs QQ Lite suits a developer who wants to work on a QQ client frontend, or a user who wants a web and desktop client for a bot backend they already run, and who is comfortable with the OneBot protocol and with the fact that the bot backend is a separate deployment. It does not suit a team that needs a client with no backend, and it does not suit a project that cannot accept AGPL-3.0. Before adopting it, read the risk note about using a QQ bot service, plan the bot backend deployment first since the client is useless without it, and replace the bundled map API key before self-hosting, because the default one has a usage limit. ## FAQ ### What does Stapxs QQ Lite need to run? It needs a QQ bot backend that speaks the OneBot protocol. The README says the bot backend deployment is relatively involved and points to a Bot compatibility issue listing the supported bots and their deployment documentation. ### How do I self-host the web version of Stapxs QQ Lite? The web build is published to npm as `ssqq-web` and starts with `npx ssqq-web hostname=127.0.0.1 port=8081`. There is also a Docker image at `ghcr.io/stapxs/stapxs-qq-lite-2.0:latest`, a mirror at `ghcr.nju.edu.cn`, and prebuilt release archives to unpack onto a web server. ### What is SSE mode in Stapxs QQ Lite? It is a mode where the app connects to the bot backend over HTTP Server-Sent Events plus an HTTP API, which is faster and lighter. It is configured at build time through the `VITE_APP_SSE` prefixed variables and cannot be switched at run time. ### Can I use any OneBot 11 compatible bot with Stapxs QQ Lite? You can try, but the README is explicit that because of differences in message body formats and interface extensions, in most cases it will not work completely. A list of the bots that are known to work is in the project wiki. ### Which platforms can Stapxs QQ Lite be built for? The web as a Vue single page application and a PWA, Electron since version 2.3.0, Tauri since version 3.2.0, and mobile through Capacitor since version 3.0.0, with Android and iOS builds. Tauri cannot cross-compile and has to be built on the target platform. ## Sources - [License: AGPL-3.0](https://github.com/Stapxs/Stapxs-QQ-Lite-2.0/blob/next/LICENSE) - [Project website](https://stapxs.github.io/Stapxs-QQ-Lite-2.0/) - [README](https://github.com/Stapxs/Stapxs-QQ-Lite-2.0/blob/next/README.md) - [Releases](https://github.com/Stapxs/Stapxs-QQ-Lite-2.0/releases) - [Stapxs/Stapxs-QQ-Lite-2.0 on GitHub](https://github.com/Stapxs/Stapxs-QQ-Lite-2.0) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stapxs-stapxs-qq-lite-2-0