ChatLuna: a Koishi plugin that puts twelve LLM providers behind one chat interface

The problem: one bot, many model providers, no shared layer

A Koishi bot that talks to an LLM usually starts as a thin wrapper around one vendor SDK. The wrapper handles the HTTP call, maybe a system prompt, and returns text. The moment you want a second provider, or voice output, or a per-channel persona, the wrapper grows into a small framework. ChatLuna is that framework, packaged as a Koishi plugin. The README describes it as a bot plugin for LLM chat with multi-model integration, extensibility and various output formats, and the adapter table lists twelve providers: OpenAI, Azure OpenAI, Google Gemini, Claude, Deepseek, Qwen, Doubao, Zhipu, Spark, Wenxin, Hunyuan, Ollama and RWKV. Eleven of those are reached through a local client against the vendor's official API; Ollama and RWKV are reached through a self-hosted API endpoint. The audience is specific. You need to be running Koishi already, because the plugin installs through the Koishi plugin mechanism and the README states it can be installed under Koishi without editing configuration files. If you are building a Discord bot on discord.js or a Slack app, nothing here applies to you.

What sits between your message and the model

The README states the extensibility is based on LangChain and the Koishi API. That is the architectural claim, and it explains the repository layout: packages/adapter-openai, packages/adapter-gemini, packages/adapter-ollama and so on are separate packages, each a provider binding, with a core package holding the preset resources and a set of extension packages such as extension-long-memory and extension-mcp. So the data flow is: a chat message arrives through Koishi's platform adapters, the core plugin assembles a request using the active preset and conversation state, an adapter package translates that into the provider's API call, and the response comes back through an output layer that can emit plain text, speech, images, or a mix. The README lists three operating modes, chat, browse and Agent, and separately lists context awareness with long-term memory, rate limiting, a blacklist system, and content moderation through the Koishi censor service. The Agent mode and MCP client support are the parts worth noting, because they mean the plugin is not only forwarding text to a completion endpoint. The MCP extension is documented in packages/extension-mcp, and the README marks MCP protocol client support as complete in its TODO list.

Presets are YAML files on disk, and that is the main configuration surface

Since version 1.0.0-alpha.10, ChatLuna uses YAML preset files for personas. The README gives the default folder as the Koishi data directory plus /data/chathub/presets, and states that all preset files are loaded from that folder, so you can add and edit files there and then switch personas with a command. A bundled example lives at packages/core/resources/presets/catgirl.yml. This is a real design decision with real consequences. Personas are files, not database rows, which means they are easy to version and diff, and equally easy to break with a YAML indentation error. The README does not document the full schema of a preset file in the excerpt available, so you would need the preset-system documentation page to know which keys are accepted. Rate limiting, the blacklist, and moderation are mentioned as features but the README does not give their config keys. Treat the feature list as a map of what exists, not as a configuration reference.

Getting it running: install, clone, build

The simplest path is the one the README recommends: install the plugin under Koishi without editing config files, then follow the getting-started guide at chatluna.chat. If you want to modify the source, the README gives a different path. Inside any Koishi template project, run yarn clone ChatLunaLab/chatluna or npm run clone ChatLunaLab/chatluna, substituting your own fork's address if you have one. Then edit the template project's tsconfig.json and add a path mapping under compilerOptions.paths: "koishi-plugin-chatluna-*": ["external/chatluna/packages/*/src"]. The README is explicit that the project is complex enough that you must build it once before first use, with yarn workspace @root/chatluna-koishi build or npm run build -w @root/chatluna-koishi. After that, yarn dev or npm run dev starts the template project. One warning is worth repeating verbatim in substance: Koishi supports hot module replacement, but the README says this project may not be fully compatible with it, and if you hit a bug while using HMR, the suggested fix is to rebuild and restart Koishi rather than debug the hot reload. Node 18 or higher is required.

Where it will disappoint you

The README's own status line says version 1.0 is the current release and development is slow while the team prepares v2. The release list tells the same story from a different angle: v1.4.0-rc.0, then v1.4.0-alpha.45, then v1.4.0-alpha.44. The line you would install is an alpha or release candidate of a version that has not shipped as stable, on a branch named v1-dev. That is not a reason to avoid the project, but it is a reason to pin a version rather than track latest. The second limitation is scope. ChatLuna is a Koishi plugin, so it inherits Koishi's deployment model and its platform coverage. If you need a language model gateway that other services can call over HTTP, the README's own help section lists Web UI and Http Server as unstarted goals, which means there is no server component to point at. The third is capacity. The README states the project group's capacity is extremely scarce and that it cannot take on more goals, which is an unusually direct statement about maintenance bandwidth. Expect pull requests to move slowly.

How it differs from calling LangChain directly

The obvious alternative is to use LangChain yourself, since ChatLuna is built on it. The difference is where the integration work lives. With LangChain directly, you own the conversation store, the persona handling, the rate limiter, the output formatting, and the platform glue for every chat network you support. ChatLuna keeps the LangChain layer but supplies the Koishi-side pieces: presets as YAML, per-room conversation state, the rate limit and blacklist system, moderation through Koishi's censor service, and output that can be text, speech, image or mixed. A second alternative, named in the README's acknowledgements, is AstrBot, described there as a one-stop Python framework for agentic personal and group chat assistants with multi-platform bot deployment. The difference is the runtime and the framework boundary: AstrBot is a Python framework you build a bot inside, while ChatLuna is a plugin you drop into a bot you already have. If your bot is Python, AstrBot is the closer fit. If your bot is Koishi and TypeScript, ChatLuna avoids a second runtime entirely.

Licence and the cost of keeping up

ChatLuna is AGPL-3.0. The practical consequence, stated plainly and without legal advice: if you modify the code and let users interact with it over a network, the AGPL's source-availability condition is generally understood to apply to your modified version. The README adds its own usage notice, saying the project does not directly provide any generative AI service and that users must obtain their own API credentials from providers, that users are responsible for complying with local law on which generative AI services may be used, and that the project does not take responsibility for model output or for data security. Those are the project's words, not a legal position you can rely on. On upgrade cost: the version numbering suggests frequent alpha and release candidate churn, the preset format changed at 1.0.0-alpha.10, and the README notes that session import and export was abandoned rather than completed. Budget for reading release notes before each bump, and check whether your preset YAML still parses after one.

Editorial conclusion

Adopt ChatLuna if you already operate a Koishi instance and want one plugin to handle provider routing, presets and output formatting. Do not adopt it if you need a standalone HTTP endpoint, a frozen API, or a project that accepts pull requests quickly, since the README states the team has very limited capacity. Before installing, verify two things: that your Node version is at least 18, and that the preset directory resolves to the path your Koishi instance actually uses, because presets are loaded from disk at startup and a wrong path leaves you with no personas to switch to.

Official sources

1. ChatLunaLab/chatluna on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases