AstrBot 部署实战：QQ/Telegram/飞书全平台机器人搭建

30 分钟快速搭建支持多消息平台的 AI 聊天机器人，支持 Telegram、飞书、QQ 等主流通讯软件

目标读者：1-3 年后端开发者，想快速搭建自己的 AI 聊天机器人

核心依赖：Python 3.10+、uv 包管理器、消息平台开发者账号

收获：掌握 AstrBot 部署全流程，能搭建多平台 AI 助手

---

1. 项目简介与架构

AstrBot 是一个开源的 AI Agent 聊天机器人平台，由 Python 开发，支持多种即时通讯软件的接入。它的设计理念是「陪伴与能力不应该是对立的」——既要有情感陪伴的能力，又要能可靠地完成各种任务。

1.1 支持的消息平台

1.2 核心特性

• 多模型支持：OpenAI、Claude、Gemini、DeepSeek 等
• Agent 能力：支持 MCP 协议，可调用外部工具
• 人格配置：内置 Persona 系统，可定制 AI 性格
• 知识库：支持 RAG，导入文档让 AI 拥有专业知识
• WebUI：可视化控制台，配置更直观

---

2. 环境准备

2.1 安装 uv

AstrBot 推荐使用 uv 进行安装，这是新一代 Python 包管理器，速度比 pip 快 10 倍以上。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

安装完成后，验证一下：

uv --version
# 输出类似: uv 0.5.0

2.2 安装 AstrBot

一条命令完成安装：

uv tool install astrbot

2.3 初始化项目

astrbot init

这个命令会创建项目目录结构：

.
├── data/              # 数据目录
│   ├── cmd_config.json  # 主配置文件
│   └── config/         # 多配置文件目录
├── logs/              # 日志目录
└── plugins/           # 插件目录

进入项目目录：

cd astrbot

---

3. 配置消息平台适配器

AstrBot 支持多种消息平台，这里我们演示三种主流平台的配置方法。

3.1 Telegram 机器人配置

Telegram 是配置最简单的方式，只需要一个 Bot Token。

3.1.1 创建 Bot

1. 在 Telegram 搜索 @BotFather
2. 发送 /newbot 创建新机器人
3. 按照提示设置名称和用户名
4. 复制 Bot Token（形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）

3.1.2 配置文件

打开 data/cmd_config.json，在 platform 数组中添加：

{
    "platform": [
        {
            "type": "telegram",
            "enable": true,
            "token": "你的BotToken"
        }
    ]
}

3.1.3 获取 Chat ID

启动机器人后，向机器人发送消息，然后访问：

https://api.telegram.org/bot<TOKEN>/getUpdates

在返回的 JSON 中找到 "chat":{"id":123456789}，这就是你的 Chat ID。

3.2 飞书机器人配置

飞书是国内企业常用的办公平台，配置稍微复杂一些。

3.2.1 创建应用

1. 访问 飞书开放平台
2. 创建企业应用
3. 在「权限管理」中添加以下权限：
   • im:chat:readonly - 读取群信息
   • im:message:send_as_bot - 以机器人身份发送消息
   • im:message:receive - 接收消息

3.2.2 创建机器人

1. 在应用中添加「机器人」能力
2. 复制 App ID 和 App Secret

3.2.3 配置文件

{
    "platform": [
        {
            "type": "lark",
            "enable": true,
            "app_id": "你的AppID",
            "app_secret": "你的AppSecret",
            "verification_token": "你的VerificationToken"
        }
    ]
}

3.3 QQ 机器人配置（OneBot）

QQ 机器人需要配合 NapCat 或 LLOneBot 使用。

3.3.1 安装 NapCat

推荐使用 NapCat 作为 QQ 客户端：

# 方式一：Docker 部署（推荐）
docker pull napneko/napcat:latest

# 方式二：直接安装
# 参考 https://napneko.github.io/

3.3.2 配置文件

{
    "platform": [
        {
            "type": "onebot",
            "enable": true,
            "ws_host": "127.0.0.1",
            "ws_port": 3001,
            "http_port": 3000
        }
    ]
}

3.3.3 启动 NapCat

docker run -d \
  --name napcat \
  -p 3000:3000 \
  -p 3001:3001 \
  -v ./data:/app/data \
  napneko/napcat:latest

---

4. 配置大语言模型

没有大模型，机器人就只是一个传话筒。这一步至关重要。

4.1 使用 Defapi（推荐）

Defapi 是一个 AI 模型聚合平台，价格只有官方的半价，而且国内访问速度快。

4.1.1 注册 Defapi

1. 访问 Defapi 注册账号
2. 在控制台获取 API Key

4.1.2 配置文件

在 cmd_config.json 中添加 provider 配置：

{
    "provider": [
        {
            "id": "defapi",
            "type": "openai_chat_completion",
            "model": "claude-sonnet-4-20250514",
            "key": ["你的Defapi-API-Key"],
            "api_base": "https://api.defapi.org/v1",
            "enable": true
        }
    ],
    "provider_settings": {
        "default_provider_id": "defapi",
        "enable": true
    }
}

4.2 使用 OpenAI 官方

如果你有 OpenAI API Key：

{
    "provider": [
        {
            "id": "openai",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["sk-xxx"],
            "api_base": "https://api.openai.com/v1",
            "proxy": "http://127.0.0.1:7890",
            "enable": true
        }
    ]
}

4.3 使用 DeepSeek

国内开发者推荐使用 DeepSeek，性价比高：

{
    "provider": [
        {
            "id": "deepseek",
            "type": "openai_chat_completion",
            "model": "deepseek-chat",
            "key": ["sk-xxx"],
            "api_base": "https://api.deepseek.com/v1",
            "enable": true
        }
    ]
}

---

5. 启动与验证

5.1 启动服务

astrbot

你会看到类似输出：

INFO - AstrBot 启动中...
INFO - WebUI: http://localhost:6185
INFO - 平台适配器加载完成: telegram, lark, onebot
INFO - Provider 加载完成: defapi
INFO - AstrBot 启动完成!

5.2 访问控制台

打开浏览器访问 http://localhost:6185，默认账号：

• 用户名：astrbot
• 密码：astrbot

5.3 测试对话

在对应的消息平台向机器人发送消息：

你好！你是谁？

如果一切正常，机器人会使用配置的大模型进行回复。

---

6. 常见问题排查

6.1 机器人启动失败

问题：ModuleNotFoundError: No module named 'astrbot'

解决：

# 重新安装
uv tool uninstall astrbot
uv tool install astrbot

6.2 消息收不到

问题：发送消息给机器人，但没有响应

排查步骤：

1. 检查平台适配器是否启用：

astrbot -p

1. 检查日志：

tail -f logs/astrbot.log

1. 确认平台配置正确，Token/密钥无误

6.3 模型调用失败

问题：Error: API request failed

排查步骤：

1. 确认 API Key 正确
2. 检查网络连接（国内需要代理）
3. 查看模型名称是否正确
4. 确认账号余额充足

6.4 速率限制

问题：429 Too Many Requests

解决：配置多个 API Key 实现负载均衡：

{
    "provider": [
        {
            "id": "openai-multi",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["key1", "key2", "key3"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

6.5 Telegram 机器人无法私聊

问题：只能群聊，私聊没反应

解决：需要与 BotFather 对话，发送 /start 激活机器人，然后私聊才能生效。

6.6 飞书机器人无法接收消息

问题：飞书机器人配置正确但收不到消息

解决：

1. 确认应用已发布
2. 确认已添加机器人到群聊或开启私聊
3. 检查公网访问是否正常

---

7. 进阶扩展

7.1 插件开发

AstrBot 支持插件扩展，创建 plugins/my_plugin/main.py：

from astrbot.api.event import filter, EventMessage

@filter()
async def handle_hello(event: EventMessage):
    if event.message_str == "hello":
        await event.reply("Hello! I'm your AI assistant!")

7.2 配置人格

在控制台「人格」页面创建 persona，设置系统提示词：

你是一个友好的 AI 助手，喜欢用简洁的语言回答问题。

7.3 MCP 集成

AstrBot 支持 MCP 协议，可以调用外部工具。在控制台「技能」页面配置 MCP 服务。

7.4 知识库 RAG

在控制台创建知识库，上传文档，让 AI 拥有特定领域的知识。

---

扩展阅读

• AstrBot 官方文档
• AstrBot GitHub
• NapCat QQ 部署指南
• 飞书开放平台文档
• OneBot 协议规范