手把手教你搭建astrbot

一、什么是 AstrBot？

• AstrBot 是一个易于上手的多平台聊天机器人及开发框架。通过它，你能够在多种消息平台上部署一个支持大语言模型（LLM）的聊天机器人。并以此实现但不限于 AI 知识库问答、角色扮演、群聊管理、LLM Agent 等功能。

• AstrBot 更是强大的 Agent 运行平台。支持子代理 (Sub-Agent) 协同工作、复杂任务编排、工具调用与上下文管理，让 AI 具备真正的行动力。

• 多 AI 提供商兼容支持 OpenAI、Google、Anthropic 及兼容 OpenAI API 的服务商，自由切换模型与推理能力。

• AstrBot 能够提供富有温度的情感交互体验，分段回复与主动对话模拟真实人类的聊天节奏，支持长文本分段发送。通过插件，可以在适当时机主动发起对话，不再只是冷冰冰的问答机器。

• 多平台可接入 QQ、微信生态、企业微信、飞书、钉钉、Telegram、Discord、Slack、KOOK 等平台，一套能力多端复用。

• 完善的插件系统：AstrBot 提供了完善、及其易于上手的插件系统，你可以通过插件实现自己的功能。开发一个插件，只需要几行代码。

二、最常用的两种部署方式

方式 1：Docker Compose 部署（最推荐，适合服务器）

1. 新建一个目录并创建 docker-compose.yml：

services:
  astrbot:
    image: registry.cn-hangzhou.aliyuncs.com/soulter/astrbot:latest
    container_name: astrbot
    restart: always
    ports:
      - "6185:6185"   # AstrBot 控制台 / API 端口
    volumes:
      - ./data:/AstrBot/data
    environment:
      - TZ=Asia/Shanghai
    network_mode: bridge

2. 启动：

docker compose up -d

3. 打开控制台：http://服务器IP:6185，首次启动会要求你设置管理员账号密码。

说明：/AstrBot/data 持久化了所有配置、插件、日志，重装容器不会丢数据。具体镜像与参数以 官方部署文档 为准。

方式 2：pip / 源码部署（适合想二次开发或本机）

需要 Python 3.9+ 环境。

# 1. 创建并进入虚拟环境（推荐）
python -m venv astrbot_env
source astrbot_env/bin/activate   # Windows 用 astrbot_env\Scripts\activate

# 2. 安装 AstrBot
pip install astrbot

# 3. 启动
astrbot

启动后同样访问 http://127.0.0.1:6185 进入控制台。

源码方式（git clone + pip install -r requirements.txt + python main.py）适合开发调试

三、首次登录与基础配置

1. 首次打开控制台，设置管理员账号密码。

2. 进入 "模型服务提供方"（Providers）页面，添加你使用的大模型，例如 DeepSeek：

   • 提供方选 deepseek

   • 填入 API Key（在 DeepSeek 开放平台申请：https://platform.deepseek.com）

   • 选择模型

   • 参考 接入模型服务官方文档 和 DeepSeek 接入 AstrBot。

3. 进入 "消息平台适配器" 页面，添加平台适配器（如 OneBot 11 对接 NapCat）。

四、常见问题解决

五、官方文档链接

• AstrBot 官方文档：https://docs.astrbot.app/

• 接入模型服务（Providers）：https://docs.astrbot.app/providers/start.html

• 接入 OneBot v11 协议：https://docs.astrbot.app/platform/aiocqhttp.html

• DeepSeek 官方接入 AstrBot：https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/astrbot/

• GitHub 仓库：https://github.com/AstrBotDevs/AstrBot