Koishi Chatbot Framework: Build a Cross-Platform Bot in Minutes

Koishi is a chatbot framework engineered for scalability and versatility. It is designed to run in nearly any environment, interface with a wide array of messaging platforms, and expand its capabilities without requiring changes to the core architecture.

You don't need programming experience to get started. By using the web-based console, you can browse the plugin marketplace and install new features with a single click. Seamlessly connect to QQ, Telegram, and Discord, then manage all your accounts from a unified dashboard where you can monitor data flow in real time. The control panel provides complete transparency into the bot's activities, and you can even send messages through the bot directly from the chat interface. Configuration is straightforward and takes only a few minutes.

For Developers: TypeScript and Hot Reload

Koishi is built entirely on TypeScript, offering a premium developer experience. Every public API includes inline documentation and type hints, allowing you to focus on writing logic rather than searching through external guides. The core is thoroughly unit-tested, ensuring that debugging is a predictable process rather than a chore.

Plugin development is optimized for efficiency. Thanks to native hot reloading, saving a file applies changes immediately. There is no need for manual restarts or lengthy rebuilds, providing the rapid feedback loop necessary for modern development.

Installing on Windows

Download and Setup
Download the .msi installer and follow the setup wizard. The installation process usually takes just a few minutes, though it can take longer on some systems depending on background dependencies. Once the installer finishes, you can launch Koishi directly from the Start menu.

Launch
Open the application and wait briefly for the console to initialize. Your environment is now ready for use.

Alternatives
If you prefer not to use the installer, you can run Koishi within a Docker container or initialize a project using a provided template.

Installing on macOS

Download and Setup
Use the .pkg installer for a streamlined experience. It automatically configures the necessary file permissions and system paths.

Launch
Click the Koishi icon in your Applications folder, and the console will appear within seconds.

Alternatives
Container-based deployments and template-driven projects are also fully supported on macOS.

Installing on Linux

Download and Launch
Download the AppImage file, grant it executable permissions, and run it. Once active, the web console will be accessible at http://localhost:5140.

Alternatives
For a more modular setup, Linux users often opt for Docker containers or manual template installations.

Android (Early Build)

The Android version is currently in an early development phase, so some features may be less stable than their desktop counterparts. To try it out, install either the standard .apk or the extended package. The installer automates the bulk of the configuration; simply tap the icon to begin.

Docker Deployment

Starting the Container
Ensure you have Docker or Podman installed. You can launch the framework using the following commands:

# Standard image (includes Chromium for rendering)
podman run -p 5140:5140 koishijs/koishi

# Lite image (excludes Chromium to save space)
podman run -p 5140:5140 koishijs/koishi:latest-lite

The web console binds to port 5140. To ensure your data persists between container restarts, add a volume mapping such as -v /your/local/path:/koishi. You can also set the system timezone using the environment variable -e TZ=Asia/Shanghai.

Adding Plugins
Once the container is running, navigate to http://host-address:5140 in your browser. You can manage, install, and activate plugins entirely through this web interface. If the page fails to load, ensure your firewall rules allow traffic on port 5140.