# go-cqhttp: the OneBot implementation its own author asked you to leave

> A Go rewrite of the CQHTTP protocol bridge for QQ bots, carrying an explicit abandonment notice, a sign server requirement, and the dependency list that explains why.

**Mrs4s/go-cqhttp** — A lightweight, natively cross-platform Go implementation of cqhttp.

- Repository: https://github.com/Mrs4s/go-cqhttp
- Stars: 10,622 · Forks: 1,563
- Language: Go
- License: AGPL-3.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/mrs4s-go-cqhttp

## The abandonment notice sits above the documentation links

The most important content in this README is four lines long and appears before the compatibility section. It states that because QQ has been steadily tightening its defences against protocol libraries and keeps changing its encryption schemes, the maintainers no longer have the capacity to continue, and recommends that bot developers migrate to the headless NTQQ project as soon as possible. A migration issue is linked directly from that paragraph.

This placement is worth noting because it is the opposite of how abandonment is usually communicated. It is not in an archived banner, not at the bottom of a changelog, not behind a deprecation notice in the docs site. It is the first substantive paragraph, above the documentation, downloads and quick start links, which means nobody can read the README without reading it.

The repository is not archived. The last push was 2026-07-10 and the project has 314 open issues against 10,630 stars. The most recent tagged release is v1.2.0 from October 2023, and its release notes point readers at the same migration issue. So the code is a year of pushes newer than the last release tag, which tells you development continued for a while before the notice went up, and stopped without a final release.

The distinction matters if you are evaluating this for production. There is a difference between a maintained project you have decided not to use, and an unmaintained one. This is the second, and the README is upfront about it.

## OneBot v11, four transports and a pile of extensions

The compatibility claim is specific: go-cqhttp implements the large majority of OneBot v11, with some extensions on top. The protocol has four transport modes and the README confirms all four. HTTP API, reverse HTTP POST, forward WebSocket and reverse WebSocket. Supporting all four is unusual for a bot bridge, and it means a bot framework written against OneBot can talk to this implementation over whichever transport it prefers without the bridge author having to guess.

The extension list is where the Go implementation diverges usefully from the specification. Reverse WebSocket multi-point connection and HTTP POST multi-point reporting let several consumers attach to one bot instance. Message recall events, parsing and sending reply messages, and parsing and sending merged forwards are all listed as extensions rather than standard features. Changing a group name is supported too, which OneBot's standard API set does not require.

Then there are the CQ codes, the string-encoded message segments, and this is where the project is unusually complete. The README splits them into two tables: those conforming to the OneBot standard, including face, record, video, at, share, music, reply, forward, node, xml and json; and extensions or slight deviations, including image, redbag, poke, node, cardimage and tts. `CQ:cardimage` is described in the README as a kind of XML image message, and `CQ:tts` is text to speech. Neither exists in the standard.

If you are writing a bot framework and want to be sure you are not missing a capability, that second table is the checklist. It is a real amount of functionality beyond the specification, and it is the main reason to prefer this implementation over a minimal one if you need the extras.

## The sign server is where the protocol fight shows up in the code

The v1.1.0 release notes are the most revealing document in the repository. The release adds custom `SignServer` configuration, described as the way to resolve `code: 45` errors and some message-sending risk-control rejections. Later work added a request timeout setting for the sign server, a `waitSignServer` option, and Bearer authentication on sign server requests, with the 1.2.0 notes mentioning support for qsign versions above 1.1.6.

Read those four changes together and the architecture becomes clear. QQ required some computation to be presented with each outbound message, the computation moved to an external service, and go-cqhttp grew a dependency on that service plus the timeout and authentication machinery to talk to it safely. That is a protocol author losing an arms race and building infrastructure to keep up, which is exactly what the abandonment notice describes.

The go.mod tells the same story from the dependency side. `github.com/fumiama/go-base16384` and `github.com/fumiama/go-hide-param` are libraries for the encoding and parameter-hiding schemes the client needs, `github.com/wdvxdr1123/go-silk` handles the SILK audio codec used for voice messages, and `github.com/fumiama/imgsz` reads image dimensions. Alongside those sit ordinary infrastructure choices: logrus for logging, gjson for JSON, testify for tests, goleveldb and a mongo driver for the database layer, plus sqlite and yaml.

The mirror database choice is itself interesting. `github.com/FloatTech/sqlite` and `go.mongodb.org/mongo-driver` together suggest the bridge can persist its data to either, which is a pragmatic answer to the reality that some deployments already run Mongo.

The Dockerfile shows how it ships. A Go 1.20 alpine builder produces a statically linked binary, then a final alpine image installs ffmpeg, coreutils, shadow, su-exec and tzdata, creates an unprivileged user, and defaults the timezone to Asia/Shanghai with an explicit UID and GID of 99 and 100. That static build and the ffmpeg dependency exist for the same reason: voice messages need transcoding and audio encoding, and those operations are awkward to port.

## Reading the codebase as a protocol reference

There is a reasonable case for keeping this repository around even if you never run it. The tree is organised in a way that maps directly onto the concepts involved. `server/` is the transport layer, holding the four connection modes. `modules/` and `pkg/` hold the platform protocol implementation, where the encryption and message encoding live. `coolq/` is the compatibility layer for the older CoolQ HTTP API. `db/` is persistence, `internal/` holds private helpers, `global/` holds configuration state, and `cmd/` is the command entry point beside `main.go`.

That separation is the useful part. If you are building a OneBot-compatible bridge in another language, or a headless QQ client from scratch, this is a working reference for how the protocol pieces fit together: how a message is encoded, how a CQ code is parsed, how a sign server response is validated. None of that knowledge is available from the OneBot specification, because the specification only covers the API surface and not how to produce valid requests.

The `.goreleaser.yml` and `scripts/` directory indicate a conventional release pipeline, and `.golangci.yml` shows linting is configured. The `docs/` directory holds the extension API documentation linked from the README as `docs/cqhttp.md`, and the live documentation site sits at docs.go-cqhttp.org.

So the repository splits cleanly into two things. The running service is not something to start new work on. The protocol knowledge inside it is still hard to get anywhere else, and that part did not stop being accurate when the maintainer stopped.

## What the ecosystem moved to instead

The search data around this project names the successors, which is more useful than any evaluation of go-cqhttp itself. NapCatQQ appears repeatedly, as does Nonebot2, and NapCat is the headless option the maintainer's own notice points at by way of the NTQQ project. There is also a related ecosystem around Mirai, the Java bot framework go-cqhttp's client library derives from, and the OneBot protocol has become the de facto standard that lets a bot framework swap implementations without rewriting anything.

That last point is what makes migration cheap. Because go-cqhttp's value was never the QQ protocol itself but its OneBot v11 conformance, a framework that speaks OneBot can point at a different bridge and keep its own code. The cost of moving is configuration, not a rewrite. The same reasoning explains why the project was forked so heavily, at 1,573 forks, since a fork with a patched sign server or a different transport was often the fastest route to something working.

What you give up in the move is the extension set, and that is the real trade to evaluate. `CQ:tts` text to speech, `CQ:cardimage`, the poke and redbag codes, and merged forward message handling are all implemented here. Whether the successor implements them is worth checking against your bot's actual requirements rather than assuming, because those extensions are where implementations differ most.

For anyone still running go-cqhttp in production today, the practical advice has two parts. The sign server is now a hard dependency rather than an optional integration, so its availability becomes part of your availability. And since the protocol continues to change, a deployment that works this month is not evidence that it will work next quarter.

## Conclusion

go-cqhttp is a well-built implementation of a protocol that its maintainer has walked away from, and the README says so in the second paragraph rather than the footer. The repository is still there, the 10,630 stars are still there, and the code is still readable if you want to understand how a QQ protocol bridge is put together. What has gone is the maintenance that would have handled the next encryption change. Read the migration issue before you plan anything new, and treat the sign server requirement in the 1.1.0 release notes as the shape of the problem: this project was already compensating for a closed protocol, and it lost that race.

## FAQ

### What is the main purpose of Go?

That question is about the Go language rather than about this repository, so it is worth separating the two. go-cqhttp is written in Go, and its Go version is visible in go.mod, which declares go 1.20, and in the Dockerfile, which builds from golang:1.20-alpine.

### Is go-cqhttp still maintained?

No, and the README says so directly. It states that because QQ keeps changing its encryption schemes the maintainers can no longer continue the project, and recommends migrating to the headless NTQQ project. The repository is not archived and the last push was 2026-07-10, but the most recent tagged release is v1.2.0 from October 2023.

### What protocol does go-cqhttp implement?

OneBot v11, which it reports as covering the large majority of, with extensions on top. It supports four transports: HTTP API, reverse HTTP POST, forward WebSocket and reverse WebSocket, and it adds extension CQ codes including cardimage, tts, poke and redbag that are not part of the standard.

### What is the sign server in go-cqhttp?

It is an external service go-cqhttp calls to obtain a value QQ requires on outbound messages. The v1.1.0 release added configurable sign server support specifically to resolve code 45 errors and some message-sending risk-control rejections, and later releases added timeouts and Bearer authentication for those requests.

## Sources

- [Issues](https://github.com/Mrs4s/go-cqhttp/issues)
- [License: AGPL-3.0](https://github.com/Mrs4s/go-cqhttp/blob/master/LICENSE)
- [Mrs4s/go-cqhttp on GitHub](https://github.com/Mrs4s/go-cqhttp)
- [README](https://github.com/Mrs4s/go-cqhttp/blob/master/README.md)
- [Releases](https://github.com/Mrs4s/go-cqhttp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mrs4s-go-cqhttp