# KoalaQA: a self-hosted AI support community from Chaitin

> KoalaQA is an AGPL-3.0 TypeScript and Go product that combines a forum, a knowledge base and an LLM answer layer. It installs through a shell script on a Docker host, and it is unusable until you connect a model.

**chaitin/KoalaQA** — KoalaQA 是一款 AI 大模型驱动的开源售后服务社区，提供 AI 回答、AI 搜索、AI 运营等能力，帮助你快速落地售后客服、社区问答、自助服务等场景，帮助团队显著降低人工运营成本、提升客户满意度与响应效率，助力实现 ZCR（Zero Contact Resolution）目标。

- Repository: https://github.com/chaitin/KoalaQA
- Website: https://koalaqa.docs.baizhi.cloud
- Stars: 555 · Forks: 66
- Language: TypeScript
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/chaitin-koalaqa

## The problem KoalaQA targets: support answers that never reach a human

Most support forums fail in a predictable way. The same twenty questions get asked every week, a human answers them again, and the answers live in threads nobody searches. KoalaQA is built around the opposite goal, which the README calls ZCR, Zero Contact Resolution: the user finds the answer without a support agent entering the conversation. The README states that the AI handles roughly 90% of common questions and hands complex ones to a human agent. That figure is the project's own claim, not something verified here.

The intended audience is a company that already has product documentation and wants a public or internal place for it to be asked about. The README lists enterprise internal and external Q&A platforms, developer communities and user service communities. If your support volume is a handful of tickets a week, the forum is overhead. If your product has a documentation set and a steady stream of repeat questions, the shape fits.

## How the answer pipeline is wired: api, raglite, anydoc and an LLM

The docker-compose.yml is the clearest description of the architecture. Four services matter for answering. The api container runs the image tagged v2.46.2 and holds the database DSN, pointing at a PostgreSQL instance named koala-qa-db on port 5432 with sslmode=disable. A service named raglite is the retrieval layer. A service named anydoc handles document ingestion. A service named oss stores objects, and the api container receives OSS_MINIO_SECRET_KEY for it. Messaging runs through NATS: the api container sets MQ_NATS_STREAMS=koala:koala.persistence.>, so persistence events flow over NATS streams rather than direct calls.

That layout tells you where the LLM sits. The README describes the bot scenario: the model retrieves relevant content from the knowledge base, summarizes based on the retrieved results, and answers within that boundary. So the model is not trained on your data and is not answering from memory. It is grounded by retrieval, and anydoc plus raglite are what put your documents into that retrieval index. The README explicitly frames this as keeping the content boundary, which is the honest way to describe it: the answer is only as good as what you imported.

nginx fronts everything. It publishes HTTP_PORT (default 80) and HTTPS_PORT (default 443), and the compose file shows the internal network using addresses under a configurable SUBNET_PREFIX defaulting to 169.254.15. That default is worth a second look: 169.254.0.0/16 is link-local space, and using it for a Docker bridge is unusual. It is configurable, so a host with routing conflicts can move it.

## Installing KoalaQA on a Docker host and reaching the console

The README requires a Linux system with Docker 20.x or newer. You log in as root and run the manager script, which is fetched over HTTPS from release.baizhi.cloud. The README states the command takes several minutes and that you answer prompts during it.

```bash
bash -c "$(curl -fsSL https://release.baizhi.cloud/koala-qa/manager.sh)"
```

When it finishes, the terminal prints a console block. According to the README it contains an internal access address and an external access address on port 443, plus a username, an email and a generated password. Open the access address in a browser, click the login button in the top right, and sign in with the printed email and password. The README does not document what to do if the script fails partway through, and it does not describe an uninstall path.

The compose file shows the environment variables the installer is writing for you, and they are the ones to check if you ever deploy by hand. The api container reads API_ADMIN_EMAIL and API_ADMIN_PASSWORD, MQ_NATS_PASSWORD, DB_PASSWORD, OSS_SECRET_KEY, TIMEZONE (default Asia/Shanghai), and optional HTTPS_PROXY and HTTP_PROXY. NO_PROXY is pre-populated with koala-qa-oss, koala-qa-raglite and koala-qa-anydoc, which is a hint that outbound model calls and internal service calls are expected to take different paths through a proxy.

After login, the README says the first screen asks you to configure an AI model, and that this is mandatory. The README recommends the vendor's own model marketplace for that step and mentions a signup credit. Any OpenAI-compatible endpoint you can reach from the api container should be treated as the thing to test, since the documentation links out rather than describing the interface inline.

## What the knowledge pipeline actually constrains

The README describes a learning loop: the system generates question-and-answer pairs from your content, refines answers, and identifies gaps in the knowledge base to fill. Treat that as a curation workflow, not automation. Someone still has to review what the model generated, because a wrong answer pair that enters retrieval will be retrieved confidently for every future question on that topic. The README's own framing, that answers stay inside the retrieved boundary, cuts both ways: it prevents invention, and it also means a gap in your imports is a gap in every answer.

Authentication is broader than most self-hosted forums. The README lists WeCom QR login, WeChat QR login and OIDC. OIDC is the one that matters outside China; the two QR flows assume your users are on those platforms. Permissions are per-board: the README describes separate boards for different teams and business lines with independently configured access and visibility. There is no mention of SSO group-to-board mapping, so if you run many boards, expect to manage membership by hand or through whatever OIDC claims the deployment supports.

The README also claims web and mobile access. That is a responsive web interface, not a native app, which is fine for reading a thread and worse for anything else.

## The licence is the biggest adoption decision here

The README states the project uses GNU Affero General Public License v3.0 and spells out the consequence in plain terms: you may use, modify and distribute the software, you must release your modifications under the same licence, and if you provide the service over a network you must also open your source. That last clause is the one that catches companies. Running KoalaQA as an internal tool is one thing. Running it as the support surface for a commercial product, with your own modifications, is a different conversation with your legal team. The repository has no separate commercial licence file listed, and the README does not describe a dual-licensing option. Nothing here is legal advice; the point is that AGPL-3.0 is a deliberate choice by the maintainer and it should be read before deployment, not after.

The repository does not expose a LICENSE file at the top level in the entries listed, so the README's licence section is the source of record. Verify the actual LICENSE file in the tree before you rely on it.

## Where KoalaQA is the wrong tool, and what to compare it against

KoalaQA is the wrong choice if you have no LLM endpoint you can call from your infrastructure. The README is explicit that the product will not function normally without a configured model, so the install is only half the work. It is also the wrong choice if you want a managed service with a published price. There is no pricing in the README, and the installation path is a root shell script on your own server, which means you own the database, the object storage and the backups.

For comparison, the related searches turn up ChatWiki and PandaWiki, both of which occupy the same territory: a self-hosted wiki or knowledge base with an AI question-answering layer on top. The difference in approach is where the content comes from. A wiki-first tool starts from pages a human wrote and adds a chat interface over them. KoalaQA starts from a forum with boards, threads and community login, and layers retrieval over the accumulated content. If your support already happens in threads and you want the AI to absorb the repeat traffic, the forum-first shape is the better fit. If your content already lives in curated documentation pages, a wiki-first tool will match your workflow with less structure to maintain. Bytedesk appears in the same searches and points at a different model again, a live-chat product rather than a community, which is the right shape if your users expect a chat window and not a forum.

The honest limitation to weigh: a forum with an AI layer is only as alive as its community. If nobody posts, the retrieval index is just your imported documents, and you have paid the operational cost of running four containers plus PostgreSQL, NATS and object storage to get a documentation search box.

## Conclusion

Adopt KoalaQA if you want a self-hosted forum plus retrieval-grounded answers and you accept AGPL-3.0, including the network-service clause. Skip it if you need a hosted SaaS with published pricing, or if you cannot supply an LLM endpoint, because the README states the product will not work normally without one. Verify three things first: that the manager.sh script and the chaitin-registry.cn-hangzhou.cr.aliyuncs.com images are reachable from your network, that ports 80 and 443 are free or remapped through HTTP_PORT and HTTPS_PORT, and that your team is comfortable with the source-availability obligation AGPL-3.0 imposes on a network service.

## FAQ

### What is KoalaQA?

KoalaQA is an open source AI-driven after-sales service community from Chaitin, combining a forum, a knowledge base and retrieval-grounded AI answers. The README describes it as a way to build internal or external Q&A platforms, developer communities and user service communities.

### How do I install KoalaQA?

You need a Linux host with Docker 20.x or newer, root access, and the command bash -c "$(curl -fsSL https://release.baizhi.cloud/koala-qa/manager.sh)". The README states the script takes several minutes and then prints access addresses plus an admin email and password.

### Does KoalaQA work without an AI model configured?

No. The README states that KoalaQA is driven by a large model and that without connecting one it will not function normally, and the first login prompts you to configure a model.

### What licence does KoalaQA use?

The README states the project uses GNU Affero General Public License v3.0, which requires that modifications be released under the same licence and that the source be opened if you provide the service over a network.

### How much does KoalaQA cost?

The README gives no pricing for KoalaQA itself. It only mentions that the recommended model marketplace gives a signup credit toward model usage, and the software is distributed under AGPL-3.0 rather than a paid licence.

## Sources

- [chaitin/KoalaQA on GitHub](https://github.com/chaitin/KoalaQA)
- [Issues](https://github.com/chaitin/KoalaQA/issues)
- [Project website](https://koalaqa.docs.baizhi.cloud)
- [README](https://github.com/chaitin/KoalaQA/blob/main/README.md)

---

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