README_EN.MD

中文 | English | 日本語

A bot plugin for LLM chat services with multi-model integration, extensibility, and various output formats.

Project Status: 1.0 Official Release (Slow development, preparing for v2 version)

📸 Screenshots

Preset	Agent Mode & Streaming Output	Image Rendering

✨ Features

• 🚀 Highly extensible (LangChain & Koishi APIs)
• 🎭 Custom conversation presets
• 🛡️ Rate limiting & blacklist system
• 🎨 Multi-format output (text, voice, image, mixed)
• 🧠 Context-aware with long-term memory
• 🔀 Three modes: chat, browsing, agent
• 🔒 Content moderation via Koishi censor

📝 Roadmap

• Room-based conversation system
• Content moderation
• TTS support (via vits service)
• Image rendering for replies
• Multi-model integration
• Preset system
• Conversation import/export (abandoned)
• v1 refactoring
• Streaming responses
• Image multi-modal input support
• MCP Protocol Client Support
• i18n support

🚀 Quick Start

Install the plugin directly in Koishi without editing any configuration files. For details, see our docs.

🔌 Supported Models

Model/Platform	Integration	Features
OpenAI	Official API	Customizable, Agent/browsing modes
Azure OpenAI	Official API	Similar to OpenAI
Google Gemini	Official API	Fast, outperforms GPT-3.5
Claude API	Official API	Large context, often beats GPT-3.5
Deepseek	Official API	Domestic renowned model
Tongyi Qianwen	Official API	Free quota available
Doubao	Local Client, Official API Access	Model developed by ByteDance, offers free quota
Zhipu	Official API	Free tokens for new users
Xunfei Spark	Official API	Free quota for new users
Wenxin Yiyan	Official API	Baidu's model
Hunyuan	Official API	Tencent's model
Ollama	Self-hosted	Open-source, CPU/GPU support
RWKV	Self-hosted	Open-source model

Web search support:

• Google (API)
• Bing (API & Web)
• DuckDuckGO (Lite)
• Tavily (API)

🎭 Presets

From 1.0.0-alpha.10, we use YAML for more customizable presets. Default preset: catgirl.yml

Preset folder: <koishi_dir>/data/chathub/presets

For more info, see preset system docs.

🔧 Development

Clone the repo:

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

Update tsconfig.json:

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

Build the project:

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

Start development with yarn dev or npm run dev.

Note: HMR may not be fully compatible. If issues occur, rebuild and restart.

🆘 Contributing

We need help with:

• Web UI
• HTTP Server
• Project Documentation

PRs and discussions are welcome!

👥 Contributors

📢 Usage Notice

Developed by ChatLunaLab.

ChatLuna is an LLM-based chatbot framework. We collaborate with the open-source community to advance LLM technology. Users must comply with open-source agreements and avoid using this project for potentially harmful purposes or unevaluated services.

This project doesn't provide AI services directly. Users must obtain API access from AI service providers.

Users are responsible for complying with local laws and using locally available AI services.

The project isn't responsible for algorithm-generated results. All results and operations are the user's responsibility.

Users configure their own data storage. The project doesn't provide direct data storage.

The project isn't liable for user-caused data security issues, public opinion risks, or model misuse.

🙏 Credits

Koishi - A cross-platform, extensible, high-performance Node.js chatbot framework.

AstrBot - A one-stop Agentic Python framework for personal and group chat assistants, multi-platform bot deployment.

Thanks to these open-source projects for inspiration:

koishi-plugin-openai

chathub