# ChatLuna: thirteen model adapters behind one Koishi plugin

> A Koishi plugin that turns a chat platform into a multi-model assistant, with eleven provider-API adapters and two for self-hosted endpoints, presets as yaml files in your Koishi data folder, and moderation delegated to a separate service.

**ChatLunaLab/chatluna** — 多平台模型接入，可扩展，多种输出格式，提供大语言模型聊天服务的插件 | A bot plugin for LLM chat with multi-model integration, extensibility, and various output formats

- Repository: https://github.com/ChatLunaLab/chatluna
- Website: https://chatluna.chat
- Stars: 440 · Forks: 51
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/chatlunalab-chatluna

## Eleven provider APIs, two endpoints you host yourself

Adapters live as separate packages under packages/, and the table splits them by how the model is reached. Eleven connect through a local client to an official provider API: OpenAI in adapter-openai, Azure OpenAI in adapter-azure-openai, Google Gemini in adapter-gemini, the Claude API in adapter-claude, Deepseek in adapter-deepseek, Qwen in adapter-qwen, Doubao in adapter-doubao, Zhipu in adapter-zhipu, Spark in adapter-spark, Wenxin in adapter-wenxin and Hunyuan in adapter-hunyuan. Two use a self-built API instead: Ollama in adapter-ollama, which is noted as supporting mixed CPU and GPU deployment, and RWKV in adapter-rwkv, which can also run locally. The notes in that table are dated marketing rather than benchmarks, so treat the claim about one model outperforming GPT-3.5 as the author's summary. The useful signal is the split itself: a hosted provider needs an API key and a bill, while Ollama and RWKV need a machine and nothing else.

## Three modes and four output kinds

Interaction is split three ways: chat, browse and Agent. Output is split four ways: text, voice, image and mixed. Voice is text to speech, and the project credits the vits service from initialencounter, which also shows up in the root manifest as the @initencounter/vits dev dependency. Image output has two sides, rendered image replies and image input, and streaming responses are supported. An MCP client extension, packages/extension-mcp, adds tool protocols to the plugin rather than requiring a rebuild. Content moderation runs through the Koishi censor service at censor.koishi.chat, which means moderation is somebody else's deployment, not a filter compiled into the plugin, and a rate limiting and blacklist system sits alongside it. Context awareness and long-term memory are a separate extension package again, packages/extension-long-memory. The ticked items on the project's own list also cover a room-based dialogue system, the preset system, a refactor to v1, localization support, and onboarding more models and platforms.

## Personas are yaml files in your Koishi data folder

Since 1.0.0-alpha.10 the preset system is file based rather than hardcoded. New personas are yaml configuration files, the one shipped in the repository being catgirl.yml under packages/core/resources/presets/. Every preset is loaded from one directory, the path of the Koishi installation running the plugin plus /data/chathub/presets, and nothing else is read. That means adding or editing a persona is a file operation in that folder followed by a command to switch to it, and a wrong path silently leaves you on the old persona. The preset system has its own documentation page at chatluna.chat/guide/preset-system/introduction.html, and the getting-started guide sits at chatluna.chat/guide/getting-started.html. Web search for the agent is likewise pluggable: packages/service-search offers Google through its API, Bing through API or web, DuckDuckGO Lite and Tavily, so the retriever is a choice rather than a fixed dependency.

## Cloning a fork needs a path mapping and one build

Development starts from any Koishi template project, not from a clone of ChatLuna itself:

```bash
# yarn
yarn clone ChatLunaLab/chatluna
# npm
npm run clone ChatLunaLab/chatluna
```

Replace ChatLunaLab/chatluna with your own fork. Then the template's tsconfig.json has to point at the checkout, mapping every plugin name onto the packages directory:

```json
{
  "extends": "./tsconfig.base",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "koishi-plugin-chatluna-*": ["external/chatluna/packages/*/src"]
    }
  }
}
```

A build is mandatory before the first run, because the project is too tangled to load unbuilt:

```bash
# yarn
yarn workspace @root/chatluna-koishi build
# npm
npm run build -w @root/chatluna-koishi
```

The root scripts show the order that build implies: process-dynamic-import runs first with lint, then yakumo builds shared-prompt-renderer, then core, then everything else. That step lives in scripts/ as processDynamicImport.ts and is launched through tsx, so the package tree is rewritten before any package is compiled, and a resources/ directory at the root holds shared assets. Once the build is done, yarn dev or npm run dev starts the template project for secondary development. Hot module replacement works in Koishi, but the project warns it may not be fully compatible here, and a bug found that way should be reported with a rebuild and a Koishi restart attempted.

## The README says 1.0 while the tags say 1.4.0

The status line at the top of the Chinese README reads that the project is at its 1.0 release, developing slowly and preparing a v2. The release feed tells a different version story: v1.4.0-alpha.45 on 28 August 2026, v1.4.0-rc.0 on 7 September, v1.4.0 on 19 September. The default branch is v1-dev, not main. The root package.json explains why two numbers coexist, because the root package is private, fixed at version 1.0.0 and named @root/chatluna-koishi, while yakumo publishes each workspace package separately, with pub sending the latest tag and pub:next the prerelease one. Bumping versions and upgrading dependencies are also yakumo jobs rather than npm ones, and the workspaces field is the single glob packages/*. The TODO list is fully ticked, including one item struck through as abandoned, importing and exporting conversation records, which the text admits was never finished.

## No model, no storage, no liability

The usage notice is the part a deployer should read twice. ChatLuna supplies no generative AI service of its own: users must obtain an algorithm API from an organization or individual that provides production AI services, and must use services available in their own region and follow local law. The project states it is not responsible for what the model generates, that all results and operations are the user's own responsibility, that information storage is configured entirely by the user since the project provides no storage of its own, and that it accepts no responsibility for data security, public opinion risk, or a model being misled, abused or misused. The same notice asks developers and users to honour the open source agreement and not use the framework, or any derivative product built on it, for purposes that could harm a country or society, or for services that have not been security assessed and filed. The Help section is equally direct: Web UI and Http Server are unchecked goals, Project Documentation is ticked, and the team says its remaining capacity is scarce.

## A Koishi plugin built on Koishi's own conventions

Everything runs on Koishi, described in the credits as a cross-platform, extensible, high-performance NodeJS chatbot framework, and the manifest confirms the dependency set: @koishijs/client, @koishijs/cache, @koishijs/censor, @koishijs/plugin-database-memory and @koishijs/plugin-hmr, with ESLint, Prettier and a yarn 4.14.1 packageManager pinned in the repository root. Extensibility is also claimed through LangChain, and the project credits AstrBot, a Python framework for agentic personal and group assistants, plus two earlier plugins it read: koishi-plugin-openai and chathub. The root is set up for agent-assisted work as well as humans, with AGENTS.md, .agents/ and .claude/ directories, and for monorepo tooling with yakumo.yml, .yarnrc.yml, tsconfig.json extending tsconfig.base.json, .eslintrc.yml, .eslintignore, .prettierrc and .editorconfig. Three READMEs sit at the root, Chinese in README.MD, English in README_EN.MD and Japanese in README_JP.MD, the last push to the v1-dev branch is dated 23 September 2026, and the repository is not archived.

## Conclusion

ChatLuna fits a Koishi operator who wants one bot to front several model providers and does not want a web UI or an HTTP server around it, since the plugin installs under Koishi without config edits and the docs sit at chatluna.chat. It does not fit anyone who wants ChatLuna to supply the model or store the transcripts, because the project states plainly that it provides no generative AI service and no storage of its own. Before you deploy it, read the usage notice about which API you are allowed to use in your region, and check the preset folder, since every persona file is loaded from your Koishi directory plus /data/chathub/presets and nothing else. If you fork it for development, budget for the ordered yakumo build before anything runs.

## FAQ

### What is ChatLuna and where does it run?

ChatLuna is a Koishi plugin that provides large language model chat. It installs under Koishi without extra configuration edits, ships as koishi-plugin-chatluna on npm, and its documentation lives at chatluna.chat.

### Which models can ChatLuna connect to?

Thirteen adapters ship: eleven through official provider APIs, OpenAI, Azure OpenAI, Google Gemini, the Claude API, Deepseek, Qwen, Doubao, Zhipu, Spark, Wenxin and Hunyuan, and two through endpoints you host yourself, Ollama and RWKV. Several of the Chinese providers are noted for handing out free token allowances to new registrations.

### How do I change ChatLuna's persona?

Since 1.0.0-alpha.10 presets are yaml files. The shipped persona is catgirl.yml in the core package, every preset is loaded from the path of your Koishi directory plus /data/chathub/presets, and you switch personas with a command after adding or editing files there.

### Does ChatLuna include a web UI or an HTTP server?

Neither is built yet. The Help section lists Web UI and Http Server as goals that are not checked off, marks Project Documentation as done, and says the team has very little capacity left to finish them.

### Do I need my own model API key to run ChatLuna?

Yes. The project states that it provides no generative AI service itself and that users must obtain an API from an organization or individual offering production AI services, using one available in their own region and complying with local law. Users are responsible for all generated results.

## Sources

- [ChatLunaLab/chatluna on GitHub](https://github.com/ChatLunaLab/chatluna)
- [License: AGPL-3.0](https://github.com/ChatLunaLab/chatluna/blob/v1-dev/LICENSE)
- [Project website](https://chatluna.chat)
- [README](https://github.com/ChatLunaLab/chatluna/blob/v1-dev/README.md)
- [Releases](https://github.com/ChatLunaLab/chatluna/releases)

---

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