KouriChat 1.5: an LLM companion bot that refuses to touch WeChat or QQ

What KouriChat actually is, and who it is built for

KouriChat is a Python program that gives an LLM a persistent character and lets that character hold conversations with people over chat platforms. The repository describes it as a "more realistic emotional companionship program based LLM", and the feature list backs that up: immersive roleplay including group chats, segmented replies with emotional sticker images, and persistent memory storage. The audience is people who want a character to talk to, not a task assistant. The project's own documentation is written for that audience, down to a homepage, a companion API service and a set of community groups.

One constraint defines the project more than any feature. The repository description opens with a bracket that reads, in translation, that connecting to WeChat, QQ and other Tencent-owned software is forbidden. KouriChat reaches users through third-party platforms instead, and its protocol layer is OneBot. That single rule shapes deployment, support and the kind of questions a new user will have.

OneBot in, LLM out: the shape of the pipeline

The architecture visible from the repository is a small pipeline. A gateway process speaks OneBot v11 to the chat platform. KouriChat itself connects to that gateway over WebSocket, which is why websockets is a declared dependency and why the setup file asks for either a reverse or a forward WebSocket endpoint. From there, messages go to an LLM provider through an API key, and the reply comes back through the same socket.

The packaging tells you the rest. pyproject.toml declares cordis-python and elixir as dependencies, and the project ships a separate elixir-0.1.0-py3-none-any.whl that uv installs alongside the main wheel. The frontend is a separate directory, built by build.ps1 into kourichat/webui/static/, and the hatch build configuration deliberately packs that static output into both the wheel and the sdist so the console works on a client machine right after install. That is a considered choice: the WebUI is not an optional extra bolted on later, it is treated as part of the artifact. The README points at an external DeepWiki page for a full system architecture description, which is worth reading because the repository itself does not spell out the internal module boundaries.

Installing KouriChat 1.5 from the release wheels

The README gives a manual deployment path and states that automatic deployment is still to be developed. You need two artifacts from the release: the kourichat wheel and the matching elixir core wheel. The command below installs both into one uv tool environment, which is the layout the project expects.

uv tool install .\kourichat-1.5.0.1-py3-none-any.whl --with .\elixir-0.1.0-py3-none-any.whl

Before that, the README's quick-start line describes an initialization step and a run step, with the configuration file kourichat.toml in between. The quick-start states that you fill in an OneBot reverse or forward WebSocket endpoint and an LLM api_key, then run the program. The repository's declared Python floor is 3.14, so an older interpreter will not satisfy the requirement.

python main.py init
python main.py run

The gateway is a separate download. The README says to get it from the community, not from this repository, and shows it being started first:

.\openclaw-onebotv11.exe run
kourichat run

Note the split between the two entry points. The quick-start uses python main.py, while pyproject.toml registers a console script named kourichat pointing at kourichat.main:main, and the manual deployment section uses kourichat run. Both routes exist in the repository. What you should see after a successful start is the gateway listening for OneBot connections and KouriChat connecting to it; the WebUI console is served by the aiohttp-based webui plugin that ships inside the wheel.

The parts that are not finished

The README separates implemented features from work in progress, and the second list is short and blunt: multi-user support, image recognition and voice messages are all still under development. For a companionship bot, that list matters more than it looks. Without multi-user support, the deployment model is effectively one operator running characters for a limited set of conversations, and without image recognition or voice, the bot is text and stickers only.

The bigger limitation is the platform ban. If your plan is to have the character message you inside WeChat or QQ, KouriChat is the wrong tool by design, and the project says so in its own description. You must supply an OneBot-compatible platform and a gateway binary that the repository does not host. That gateway is described as coming from the community, which means its version, its maintenance and its security posture are outside this repository's control. The README also does not document rollback or downgrade steps between releases, and it does not describe what happens to stored memories when you change LLM provider. Since persistent memory is a headline feature, that silence is worth taking seriously before you put a character into long-term use.

How this differs from a general chat frontend

The obvious comparison is a self-hosted chat UI such as Open WebUI, which sits in front of an LLM API and gives you a browser conversation window. The difference is where the conversation happens. Open WebUI expects you to open a page and type; KouriChat expects a message to arrive from a chat platform through OneBot, and it answers there. That changes everything downstream: character persistence, reply segmentation, sticker selection and group-chat handling are all built around asynchronous messages rather than a request and a response in a text box.

The second difference is the packaging of the character layer. A generic frontend treats the model as the product and the persona as a prompt you paste in. KouriChat treats the persona, its memory and its expressive behaviour as the product, and the model as a swappable dependency behind an api_key. If you want a general assistant, the first kind of tool is a better fit. If you want a character that lives in a chat client and remembers you, the second is what you are actually shopping for.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-06, the same day as the v1.5.0.1 release. The release history shows a long gap before that: v1.4.3.2 landed on 2025-10-18 and 1.4.3.1 on 2025-09-11. So the project moves in bursts, and 1.5 is described in the README as a complete rewrite and a development version. A rewrite plus a development label is a warning about upgrade cost, not a guarantee of stability.

Licensing needs your own reading. The README badge says FSL, while the repository metadata reports NOASSERTION, meaning GitHub could not classify the LICENSE file automatically. Those two signals do not agree, and the practical consequences for redistribution or for running the bot as a paid service depend on the actual licence text. Read LICENSE yourself; this is not legal advice and the repository alone is not enough to settle the question.

Operationally, the recurring costs are the LLM API key and whatever machine you leave running. The README's deployment recommendation suggests a Windows Server box kept online, and it links both a project-operated API and a third-party provider for keys. Because the install is two wheels plus an externally sourced gateway, a version bump is not a single command: you reinstall both wheels from the matching release and confirm your gateway still speaks the same OneBot version.

Editorial conclusion

Adopt KouriChat if you want an LLM companion character living behind an OneBot-compatible platform and you are comfortable running a Python wheel alongside a second Elixir wheel from the same release. Do not adopt it if your users expect to reach the bot from WeChat or QQ: the project bans those integrations outright. Before committing, verify the licence text in LICENSE, since GitHub reports NOASSERTION, and confirm that the openclaw-onebotv11.exe gateway you download from the community matches the version your release expects.

Frequently asked questions

Official sources

1. Issues
2. KouriChat/KouriChat on GitHub
3. Project website
4. README
5. Releases