How to Install and Run AstrBot
This guide is based on the open-source project AstrBot by AstrBotDevs, licensed under AGPL-3.0. StackGuide AI is not affiliated with AstrBot.
AstrBot is an AI agent assistant and development framework that connects to messaging platforms, language models, plugins and AI features, so one bot can answer, use tools, and run in a chat you already use. As of October 31, 2026, its GitHub repository has 45,272 stars. Its README also describes it as an alternative to OpenClaw-style personal agent setups; this guide covers only the official bot platform path, not any personal-account automation.
What AstrBot is, and who it is for
Three ideas define it. First, it is multi-platform: official adapters cover Telegram, Discord, Slack, Feishu (Lark), DingTalk, WeChat Official Accounts, WeCom, QQ through the OneBot v11 protocol implementation, LINE, Satori, KOOK, Misskey and Mattermost, with more community adapters listed in the README. Second, it is model-flexible: OpenAI-compatible services, Anthropic, Google Gemini, DeepSeek, Zhipu AI, Moonshot AI, and self-hosted Ollama and LM Studio are all listed as supported model services. Third, it is extensible: plugin extensions, a knowledge base, persona settings, an agent sandbox for isolated code and shell execution, and a WebUI and Web ChatUI for managing and talking to the bot.
It suits developers and small teams who want a bot on an official platform account, with a model and plugins they control. It is not a way to automate a personal chat account, and this guide deliberately does not describe any such use: use only the official bot accounts and adapters the platform provides, and check that platform's terms before connecting anything.
Prerequisites
- An official bot account on the platform you choose: for example a Telegram bot from BotFather, a Discord application bot, or a WeChat Official Account. Create that account through the platform's own process first, and keep its token secret.
- A language model to connect: an API key for a hosted provider, or a local model served by Ollama or LM Studio. AstrBot itself is the framework; it does not ship with a free hosted model.
- uv, for the quick path, or Docker, for the server path: the quick path requires uv installed. See the uv documentation for installing uv itself.
- A machine that stays on, if the bot must always reply: a bot that only runs while your laptop is awake will miss messages when the laptop sleeps. A small server or a Docker host suits an always-on bot better.
Step 1: Install AstrBot with uv
For a quick first run, install with uv for Python 3.12, initialise once, and run:
uv tool install astrbot --python 3.12
astrbot init # Only execute this command for the first time to initialize the environment
astrbot runTo update later, run:
uv tool upgrade astrbot --python 3.12The README notes that on macOS, security checks may make the first run of the astrbot command take about ten to twenty seconds. That delay on a first run is expected, not a failure.
Step 2: Connect one official platform and one model
Open the WebUI, add your model provider and key, or point AstrBot at your local Ollama or LM Studio endpoint, and then add exactly one platform adapter to start. Use the token from the official bot account you created in the prerequisites, and save it only in AstrBot's own configuration, never in a chat message or a public file.
Send the bot a test message on that platform, and confirm three things: the bot replies, it uses the model you configured, and it does not reply in places you did not intend it to. Only after that single-platform test works should you add a second platform, a plugin, or a knowledge base. Adding everything at once makes it impossible to tell which part broke.
Alternative path: Docker, and desktop apps
For a more stable, production-ready deployment, the README recommends Docker or Docker Compose and points to its own Docker deployment documentation. That documentation is the source for the container commands, so follow it rather than a guessed docker run line from elsewhere; the README itself does not publish a full compose file.
For desktop use, there is also a separate AstrBot desktop application for ChatUI, and a Launcher for fast deployment and isolated multi-instance use. The README says the desktop app is designed for desktop usage and is not recommended for server scenarios, so choose the path that matches where the bot will actually live.
Common problems and fixes
| Problem | Fix |
|---|---|
| The first run on macOS seems stuck | Wait. The README says macOS security checks can make the first run take about ten to twenty seconds. |
| The bot never replies | Check the adapter configuration and the token first, then check that AstrBot is actually running and that the model provider responds. Test one platform at a time. |
| The bot replies with the wrong model | Check the model provider selected in the WebUI. A local Ollama endpoint and a hosted API key are different providers, and the wrong one is usually a configuration choice, not a bug. |
| You are tempted to connect a personal account | Do not. Use an official bot account and adapter, and check the platform's terms. This guide does not cover personal-account automation, and neither does a legitimate deployment. |
| A plugin breaks the bot | Disable plugins one at a time, starting with the most recently added, and check the plugin's own documentation before re-enabling it. |
FAQ
Does AstrBot need a hosted model? No. It supports hosted providers and self-hosted Ollama and LM Studio. The choice is yours, but you must configure one of them; AstrBot does not include a model of its own.
Can one AstrBot serve several platforms? Yes, through its adapters, but start with one, prove it works, and only then add another. Each platform has its own bot account and token.
What is the agent sandbox for? According to the README, it provides isolated, safe execution of code and shell calls, with session-level resource reuse, so agent tool use does not run unchecked on your host.
Is there a one-click cloud deployment? The README lists a RainYun one-click cloud deployment service for users who do not want to manage a server. That is a third-party service with its own terms and pricing, so check those before using it; it is not part of AstrBot itself.
Licence and attribution
AstrBot is licensed under AGPL-3.0. In plain terms, and not as legal advice: you may use it commercially under that licence's terms, but if you modify it and offer it over a network, AGPL-3.0 requires you to make the corresponding source available to users of that network service. That matters for a bot, because a bot is a network service by nature: running a modified AstrBot for other people triggers the source-offering duty in a way that running it only for yourself does not. Keep the licence notice with any copy you redistribute, and remember that each platform's terms and each model's terms apply on top of AstrBot's licence.
What to try next
Once one platform and one model work, add a single plugin and a short persona setting, then test the bot with a question it should answer from its knowledge base. That sequence tests the three layers AstrBot is built from: platform, model, and extension.
This guide was checked against the official README and repository as of October 31, 2026. StackGuide AI did not run this tool for this guide, so this guide makes no claim based on running the tool; the commands below are the ones the official README publishes.