Chatluna
多平台模型接入，可扩展，多种输出格式，提供大语言模型聊天服务的插件 | A bot plugin for LLM chat with multi-model integration, extensibility, and various output formats
Last verified:
What is Chatluna?
ChatLuna is a powerful language model chat service plugin built on LangChain and designed as an extension for the Koishi chatbot framework. It enables users to interact with multiple mainstream large language models including OpenAI, Google Gemini, Anthropic Claude, and Deepseek through a unified interface. The plugin supports multi-platform model integration and continuously expands to add more platform support.
Key features include highly extensible architecture for adding new language models, a flexible preset system for customizing session behavior, intelligent resource management with global cooldown and concurrency limits, multimedia interaction supporting text/images/voice responses, context-aware conversations with chat history saving and long-term memory, and three distinct chat modes (chat, browsing, and plugin/agent). The browsing mode enables web search capabilities while the agent/plugin mode allows models to call external tools including MCP, knowledge bases, and complex utilities.
ChatLuna is designed for Koishi chatbot users who want LLM chat capabilities, chatbot developers building Koishi plugins who need LangChain Model interfaces, and communities or individuals running chat servers who require multi-model chat services with features like role-playing (world books, author comments), content moderation through Koishi's censor service, and various output formats including text, images, and voice synthesis.
Chatluna pricing
Pricing model: Freemium
ChatLuna itself is a free open-source plugin available via npm (koishi-plugin-chatluna). However, using it requires paid API subscriptions from model providers: OpenAI API (paid), Azure OpenAI API (paid), Google Gemini API (requires account, may be charged), and Claude API (paid). The plugin has no built-in subscription or pricing - users pay directly to their chosen AI model provider based on usage. There is no free tier for the LLM services themselves, though the plugin software is free to install and use.
Chatluna pros
- Supports multiple major LLM platforms (OpenAI, Gemini, Claude, Deepseek) in one plugin
- Highly extensible architecture for adding new models or services easily
- Three distinct chat modes for different use cases (chat, browsing, agent)
- Agent mode supports tool calling including MCP and knowledge base integration
- Built on LangChain for reliable model integration
- Flexible preset system for customizing model behavior precisely
- Supports multimodal input including images
- Multiple output formats: text, images, and voice synthesis
- Long-term memory and chat history preservation for personalized experience
- Intelligent resource management with cooldown and concurrency controls
- No complex configuration files needed - simple plugin installation
- Built-in content safety through Koishi censor service integration
- World book and author comment features for role-playing scenarios
- OpenAI-like adapter for any OpenAI-compatible API providers
- Provides LangChain Model interface for other Koishi plugin developers
Chatluna cons
- Requires paid API keys for most models (OpenAI, Claude, Azure OpenAI)
- Only works as a plugin within Koishi framework, not standalone
- Browsing mode requires separate installation of chatluna-search-service plugin
- Agent mode requires additional plugin installation for tools (chatluna-plugin-common or chatluna-mcp-client)
- Development is slow as team prepares for v2 version
- Some features require higher permission levels (preset management needs level 3)
- Configuration can be complex for beginners unfamiliar with Koishi
- Chinese-dominated documentation may limit accessibility for English users
Frequently asked questions about Chatluna
What is ChatLuna?
ChatLuna is a powerful language model chat service plugin built on LangChain that exists as a plugin on Koishi. It supports interaction with multiple mainstream large language models including OpenAI, Google Gemini, and Claude. Beyond providing model chat functionality, it also provides convenient LangChain Model interfaces for other Koishi plugin developers to interact with and extend capabilities using large language models.
Which LLM platforms does ChatLuna support?
ChatLuna integrates Deepseek, OpenAI, Google Gemini, Anthropic Claude, and Azure OpenAI as mainstream platforms. It also provides an openai-like-adapter for any API compatible with OpenAI format, allowing users to add other OpenAI-compatible providers. The plugin continues to expand support for more platforms.
What chat modes are available in ChatLuna?
ChatLuna has three built-in chat modes: chat (default basic mode supporting all preset features like world books, author comments, and long-term memory), agent (allows models to call tools and complete complex tasks), and browsing (web browsing mode that lets models get latest information from external sources). The plugin and browsing modes require additional plugin installations.
How do I enable browsing mode?
Browsing mode is officially maintained but not integrated into the main ChatLuna plugin by default due to size. You need to additionally install the chatluna-search-service plugin to use browsing mode. After installation, you can switch to browsing mode using the chatluna.room.set -c <chatmode> command in regular rooms or configure defaultChatMode in the Koishi console for template clone rooms.
How do I enable agent mode tool calling?
Agent mode is built into the main ChatLuna plugin, but there are no built-in tools available for agent mode. You need to install chatluna-plugin-common or chatluna-mcp-client plugin to provide usable tools for agent mode. Once installed, the model can call tools and continue calling tools based on results until completing tasks.
Does ChatLuna support voice output?
Yes, ChatLuna supports voice output. It can call vits service to render model-generated content as voice and send it. You can use the chatluna.chat.voice command with parameters -s <speakerId> to specify the voice tone ID and -r <room> to specify the room. This enables multimodal interaction with text, images, and voice formats.
How do I configure an OpenAI-compatible API provider?
Install chatluna-openai-like-adapter from the plugin market. Get your API key and API Host from your provider, then go to the openai-like-adapter configuration page. Change the platform name to something unique to avoid conflicts, fill in your API key and OpenAI-compatible request address (format: https://xxx.com/api/v1), and save. Test using chatluna.model.test command to verify successful integration.
What triggers ChatLuna responses?
ChatLuna supports multiple response modes including At response (triggered when bot is mentioned), nickname response (triggered by user's nickname), and room response (direct conversation in current room). Users can input text or images to trigger ChatLuna conversations. The bot creates the appropriate model based on user input and room information, then generates and sends the response.
How do I manage chat presets?
ChatLuna provides commands for preset management: chatluna.preset.list to list available presets with keywords and previews, chatluna.preset.add to add new simple presets, chatluna.preset.clone to clone existing presets, chatluna.preset.set to modify preset content, and chatluna.preset.delete to delete presets. Note that clone, set, and delete commands require level 3 permission or higher.
What does the 403 error mean and how do I fix it?
The 403 error typically occurs when you haven't configured the model, chat mode, and preset for template rooms. To fix it, select the appropriate model, chat mode, and preset for your room, then click the save button in the upper right corner of the Koishi console configuration page. This resolves the configuration issue causing the 403 error.