KouriChat 1.5: an LLM companion bot that talks through OneBot, not Tencent apps

What KouriChat solves, and for whom

KouriChat is aimed at people who want a persistent fictional character to talk to over a chat protocol, rather than a stateless chatbot in a browser tab. The README describes it as a program for more realistic emotional companionship built on an LLM, and the feature list names immersive roleplay with group chat support, segmented replies with emotion-matched sticker images, and persistent memory storage. Those three items together are the product: a character that remembers prior conversations, splits long model output into human-sized chat messages, and attaches images that match the tone of the reply.

The intended user is someone comfortable running Python tooling on their own machine or a Windows server. The README recommends a Windows Server box for always-on hosting and links to a hosting discount, which tells you the authors expect the bot to sit online continuously rather than run per session. The audience is individual hobbyists, not teams. Multi-user support appears in the feature list under development, so today the deployment model is one operator, one or more characters, one gateway.

The README opens with a hard constraint in brackets: connecting to WeChat, QQ and other Tencent-family software is prohibited. That single line shapes everything else. KouriChat does not ship a Tencent client adapter, so it is not a drop-in replacement for the many QQ bot frameworks that do.

The OneBot plus LLM data flow

The architecture visible in the README is three pieces in a line. A OneBot v11 gateway receives platform messages. KouriChat itself, invoked as the kourichat command, consumes those events, builds a prompt for the configured LLM, and sends the model's reply back through the gateway. The gateway is a separate executable the README calls openclaw-onebotv11.exe, and the quick start says to launch it with the run subcommand before starting KouriChat.

That separation matters. KouriChat owns character state, prompt construction, memory and reply formatting. The gateway owns the platform connection. The README states OneBot protocol compatibility as a shipped feature, and the configuration section names both reverse and forward WebSocket modes for the onebot connection, so the gateway can either dial into KouriChat or accept a connection from it. Which mode you pick is a deployment question about which side can reach the other, not a feature difference.

The reply pipeline is where the companionship framing shows up. The README lists intelligent message segmentation and emotional sticker images as implemented. In practice that means the raw model output is not forwarded verbatim: it is split into multiple chat messages, and sticker selection is driven by the emotional content of the reply. Persistent memory storage is listed separately, which implies conversation history survives a restart rather than living only in the process.

What the README does not give is any detail on how memory is stored, how large it grows, or how it is retrieved into the prompt. That is a gap. For a program whose selling point is remembering you, the storage and retrieval design is the part an adopter most needs to see.

Getting it running: the commands the README actually gives

The README offers two paths. The automatic one is marked as still to be developed, so the manual path is the only real one. It starts from the release artifacts: you fetch the latest kourichat package and the matching elixir core wheel for that version.

The install command is:

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

This uses uv's tool install with a --with flag to pull in the elixir wheel alongside the main package. The version pair is explicit in the command, and the README says to obtain the elixir core corresponding to the version you downloaded. Mismatched wheels are the obvious failure mode here, since nothing in the command resolves versions for you.

Next, the gateway. The README says to get it from the community download and run:

.\openclaw-onebotv11.exe run

Then the bot itself:

kourichat run

There is also a second, newer path described at the top of the README for the 1.5 development build: python main.py init, then fill in kourichat.toml with the onebot reverse or forward WebSocket settings and the LLM api_key, then python main.py run. The two paths do not fully agree with each other, which is worth noting before you follow either. The config file is kourichat.toml and the keys named in the README are the onebot connection mode and the LLM api_key. No other keys are documented in the supplied material.

For the model backend the README points at its own API platform and at a DeepSeek key obtained through SiliconFlow. Any OpenAI-compatible endpoint is presumably usable, but the README only names those two, so treat the config key format for other providers as unverified.

Where KouriChat 1.5 is the wrong tool

The most concrete limitation is stated by the project itself. Multi-user support, image recognition and voice messages are all listed under development, not implemented. If you need several people talking to separate characters with isolated memory, KouriChat does not do that yet. If you want the character to see a picture someone sent, it cannot. If you want to send voice notes, it cannot.

The second limitation is the Tencent prohibition. Anyone whose friend group lives on QQ or WeChat cannot point KouriChat at it. The OneBot v11 protocol is a standard that many gateways implement, but the README's own gateway is the only one it names, and it is distributed through the community rather than through a package index. That means your platform reach is bounded by what gateways you can find and run, and the project explicitly declines to supply the Tencent ones.

The third is deployment friction. There is no automatic installer. You are assembling a wheel install, a second wheel, a downloaded executable and a TOML file by hand. The README also recommends a Windows Server for hosting, and the example commands are Windows paths with backslashes, so the documented path is Windows-first even though the language is Python. Running this on Linux is likely possible but is not described in the material.

Finally, the two quick-start paths in the README conflict: one uses uv tool install with a kourichat console command, the other uses python main.py with an init step. A reader cannot tell from the README alone whether these are two supported entry points or one stale one. That ambiguity is a real cost for anyone trying to reproduce a working setup.

How it differs from a general-purpose chat bot framework

The obvious comparison is with general-purpose bot frameworks that also speak OneBot, such as NoneBot2. The difference is in what sits behind the protocol layer. NoneBot2 is a plugin host: you get an event dispatch system and a plugin ecosystem, and any conversational behaviour, memory or persona logic is something you write or install as a plugin. KouriChat ships the conversational layer as the product. Character roleplay, message segmentation, sticker selection and persistent memory are in the box, and the configuration surface is small: a gateway connection and an LLM key.

That trade runs both ways. With NoneBot2 you can build anything, including the exact behaviour KouriChat provides, but you maintain it. With KouriChat you get the companion behaviour immediately and inherit its roadmap. The features it has not built yet, multi-user and multimodal input, are exactly the kind of thing a general framework would let you add yourself without waiting for a release.

A second comparison point is hosted companion apps. Those give you the character with no install, but you do not control the model, the memory store or the conversation data. KouriChat's value proposition is that the LLM key is yours and the process runs on your hardware. That is the reason to accept the manual install.

Licence and maintenance cost

The licence situation needs care. The repository metadata reports NOASSERTION, meaning GitHub could not classify the licence file automatically. The README's own badge says FSL. Those two signals do not match, and FSL is not a standard open source licence in the way MIT or Apache-2.0 are. The practical consequence is that you should open the LICENSE file in the repository and read it before you build anything on top of KouriChat or redistribute it. Nothing in the supplied material tells you what FSL here permits or forbids, so any assumption about commercial use or modification rights is unfounded.

On maintenance, the release cadence visible in the metadata is roughly one release per several months, with v1.5.0.1 in September 2026, v1.4.3.2 in October 2025 and 1.4.3.1 in September 2025. The 1.5 line is described as a complete rewrite, which means upgrade cost between 1.4 and 1.5 is not a patch: the entry points changed, the config file is now kourichat.toml, and the install is a wheel pair rather than whatever 1.4 used. If you are already running 1.4, budget for a re-deployment rather than an in-place update.

The runtime cost is ongoing and external: an LLM API key that you pay for, plus whatever the gateway and hosting cost. The README points at the project's own API platform with a small signup credit and at a DeepSeek key via SiliconFlow, so the cost model is per-token through a third party. For a bot that is meant to run continuously and remember long histories, that is a recurring bill, not a one-time setup.

Who should adopt KouriChat, and what to check first

KouriChat fits a single operator who wants a self-hosted roleplay companion on a platform reachable through OneBot v11, is comfortable installing Python wheels with uv and running a separate gateway executable, and is willing to pay an LLM provider per token. It fits that person well, because the alternative is writing the persona, memory and message-formatting layer yourself on top of a framework like NoneBot2.

It does not fit anyone who needs multi-user isolation, image or voice input, or a Tencent platform connection. All four of those are either listed as unfinished or explicitly prohibited in the README, and no amount of configuration changes that.

The first thing to verify before you commit is the LICENSE file, because the repository says NOASSERTION and the README badge says FSL, and you cannot plan around a licence you have not read. The second is that your elixir wheel version matches your kourichat wheel version, since the documented install command pins them together and nothing resolves that for you. The third is which of the README's two start-up paths is current for the build you downloaded. If you cannot get a reply through the gateway after kourichat run, the mismatch is almost certainly in the kourichat.toml onebot WebSocket direction, forward versus reverse, rather than in the LLM key.

Editorial conclusion

Adopt KouriChat if you want a self-hosted roleplay companion that speaks OneBot v11 and you are willing to run a separate gateway binary and point the bot at your own LLM API key. Do not adopt it if you need multi-user isolation, image or voice input, or a one-command installer: the README lists all three as unfinished or absent. Before committing, read the LICENSE file itself, because the repository reports NOASSERTION while the README badge says FSL, and confirm the elixir wheel version matches kourichat-1.5.0.1 exactly, since the install command pins both together.

Official sources

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