AstrBot全指南：

AstrBot 是开源免费一站式 AI 聊天智能体基础设施（当前版本 v4.5.0），核心功能是一键在 QQ、企业微信、飞书、Telegram、Discord 等聊天软件中搭建 AI 机器人。它集成了大模型、RAG 知识库与海量插件，个人、社团及小微企业均可落地智能机器人。

一、平台基础介绍

1. 项目背景

• 上线时间：2022 年底由开发者 Soulter 开源上线。
• 社区影响力：GitHub 拥有 14.3k+ Star，1100+ Fork，120+ 贡献者。
• 生态规模：社区拥有 640+ 官方插件、800+ 扩展插件；7 天活跃部署实例 8600+，活跃用户 25 万+，Docker 镜像拉取超 227 万次。
• 官方网站：https://astrbot.app
• 开源仓库：GitHub
• 商用合作邮箱：community@astrbot.app

2. 产品定位

AstrBot 定位为IM 即时通讯原生 AI 智能体底座。用户无需从零写代码，通过图形化 WebUI 可视化配置，即可将主流大模型对接进各类聊天软件。主要应用场景包括群机器人、智能客服、私人 AI 助手及知识库问答机器人。

3. 支持接入平台

官方原生支持

• 即时通讯：QQ (OneBot v11)、Telegram、Discord、Slack
• 企业通讯：企业微信（应用/客服/机器人）、飞书、钉钉、Satori、Misskey
• 其他：微信公众号、微信客服

社区拓展支持

• 平台包括：KOOK、Bilibili、VoceChat 等聊天平台。

二、核心主要功能

1. 多模型接入（全主流大模型兼容）

• 原生 API 直连：支持 OpenAI、Google Gemini、Anthropic Claude。
• 兼容接入：支持 Kimi、DeepSeek、GLM 智谱、Minimax、Ollama、LMStudio（本地离线大模型）。
• LLMOps 平台对接：支持 Dify、Coze 扣子、阿里云百炼等平台。
• 音视频能力：集成 Whisper 语音转文字、Minimax TTS 文字转语音，支持机器人语音聊天。

2. 原生 RAG 知识库（Beta 功能）

• 文档格式：支持 PDF、DOCX、Markdown 等，基于 Markitdown 解析文档。
• 检索方案：采用稠密向量检索与 BM25 稀疏检索多路混合召回方案。
• 多库绑定：单个机器人会话可挂载多个知识库，聊天时自动引用文档内容作答。
• 后台统计：可视化管理文档与分块数量、嵌入模型及访问统计。

3. Agent 智能体与 MCP 协议

• 内置 Agent 沙箱：支持子智能体编排。
• 工具调用：AI 可联网查资料，调用插件完成复杂任务。
• 生态拓展：支持 MCP 协议拓展自定义能力。

4. 640+ 海量插件生态（社区免费）

所有插件均可通过 WebUI 一键安装，无需手动编码。

• 群聊交互：如“心流（主动回复）”，实现群聊根据上下文自动主动说话。
• 资源工具：如"Pixiv_Search"，用于搜索插画、漫画、排行榜，含内容风控过滤。
• 记忆系统：如"LivingMemory"，模拟类人脑长期记忆，机器人可记住用户历史对话。
• 娱乐工具：如"AI 自动匹配表情包”，包含云端表情库管理功能。
• 模型测评：如"LMArena"，提供免费调用多款开源模型进行对话测试。

5. Web 可视化管理后台

提供图形化面板，功能包括：

• 新建机器人
• 配置适配器
• 绑定聊天平台
• 管理知识库与插件安装
• 查看运行日志
• 权限白名单配置（零代码配置机器人）

三、适用人群

1. 个人用户（学生/AI 爱好者）

• 私人助手：搭建 QQ 或 TG 私人 AI 助手、专属知识库机器人（导入笔记/书籍进行提问）。
• 群聊娱乐：群聊娱乐机器人（表情包、搜图、闲聊）。
• 本地部署：本地 Ollama 部署离线 AI，无需联网即可使用。

2. 社团/社群运营（QQ 群/飞书群）

• 社群服务：社群自动答疑、新人欢迎、关键词自动回复。
• 文档管理：群文档知识库问答，方便群友查找资料。

3. 中小企业/个体户

• 智能客服：在企业微信或微信公众号部署智能客服，导入产品手册作为知识库，自动回复客户咨询，降低人工成本。
• 内部知识库：员工在企业微信内查询规章制度、产品资料。

4. 开发者/运维

• 二次开发：定制开发自定义插件、对接自研大模型。
• SaaS 服务：搭建 SaaS 机器人服务，对外提供部署方案。

四、免费与付费详情

✅ 永久免费项目

1. AstrBot 本体软件：100% 开源免费商用，无授权费、无部署数量限制、无机器人数量上限。
2. 插件生态：全部官方及社区 640+ 插件免费下载使用。
3. 基础功能：WebUI 后台、RAG 基础知识库、Agent 基础功能全免费。
4. 安装资源：Docker、pip、Windows 一键安装包全部免费下载。

⚠️ 按需自费项目（非平台收费，第三方费用）

1. 大模型 API 资费：使用 OpenAI、Claude、Kimi 等商用 API 需按 token 计费；若使用 Ollama 本地模型则完全免费（电脑本地跑模型，无 API 费用）。
2. 服务器成本：自建部署需要云服务器或本地电脑，云主机费用需自行支付；也可选择雨云、硅基流动、UCloud 等合作算力服务商按需选购。
3. 第三方平台开通费用：企业微信机器人、微信公众号认证等部分渠道需要平台官方收取认证费（如腾讯/飞书官方收取，与 AstrBot 无关）。
4. 付费增值：社区少量定制化付费插件、企业定制部署服务（非强制）。

总结：纯个人用户若使用 Ollama 本地大模型配合免费插件，零成本落地完整机器人。

五、三种安装使用步骤（从易到难）

方式 1：Windows 一键安装（小白首选）

1. 访问官网 astrbot.app 下载 Windows 一键安装器。
2. 双击安装，自动配置运行环境，浏览器会自动打开 Web 管理后台（默认本地端口）。
3. 配置流程：

• ①添加模型：填入 API Key（或选择 Ollama 本地）。
• ②新建机器人。
• ③选择平台（如 QQ、企业微信）。
• ④按指引完成平台机器人授权对接。
• ⑤上传知识库、安装插件、聊天测试。

方式 2：Docker 部署（服务器/云主机首选，推荐）

1. 在服务器上放行 2333 端口。
2. 执行以下命令一键拉取并启动：
3. bash

docker run -d -p 2333:2333 astrbot/astrbot:latest
docker run -d -p 2333:2333 astrbot/astrbot:latest

1. 浏览器访问 服务器 IP:2333 进入 WebUI。
2. 后续配置同 Windows：添加模型→新建机器人→适配器对接平台。

方式 3：Pip 源码部署（开发者）

1. 执行安装命令：
2. bash

pip install astrbot
pip install astrbot

1. 运行程序：
2. bash

astrbot run
astrbot run

1. 适合需要二次开发、自定义源码的用户。

基础使用流程（通用 5 步）

1. 准备模型：

• 云端：去 OpenAI、DeepSeek 等官网获取 API Key。
• 本地：安装 Ollama，下载 Qwen、Llama 等开源模型（零 API 费）。

1. Web 后台添加模型：在后台添加模型提供商，粘贴 Key 或填写本地 Ollama 地址。
2. 创建机器人实例：选择要接入的聊天平台（如 QQ、企微、TG）。
3. 配置平台适配器：按平台指引获取机器人 token/密钥完成绑定。
4. 完善功能：可选上传知识库、安装插件，完成后在聊天窗口@机器人对话。

六、部署与使用避坑大全

1. 部署环境坑

• 数据持久化：Docker 部署时必须挂载数据目录，否则重启容器配置与知识库会全清空。
• 端口连通：云服务器需在安全组放行 2333 端口，否则外网无法打开 WebUI。
• 系统版本：CentOS 低版本或老旧 Windows 容易依赖报错，建议优先使用 Win10+ 或 Ubuntu 22.04+。

2. 大模型接入坑

• Key 错误：机器人无回复时，优先核对 API Key、接口地址及模型名称；国内接口注意填写自定义 base_url。
• Ollama 连接：本地 Ollama 需开启远程访问，服务器部署需填写本机内网 IP，并放行 11434 端口。
• 模型兼容：小众模型优先选择「OpenAI 兼容格式」接入。

3. 聊天平台对接坑

• QQ OneBot：QQ 官方风控严格，个人号极易风控封号，建议优先使用机器人框架或官方 QQ 机器人渠道，避免使用私人大号。
• 企业微信/飞书：机器人应用权限需勾选“通讯录”、“消息接收/发送”权限，否则收不到群消息。
• Telegram/Discord：通常需要科学环境才能获取机器人 token、收发消息，无代理适配器可能无法连通。

4. 知识库 RAG 坑

• 文档解析：PDF 加密或损坏文件无法上传，需转成非加密 PDF 或 Markdown 再上传。
• 检索效果：检索答非所问时，优先选择 OpenAI_Embedding 等模型，自建向量库需核对分块大小。
• 绑定缺失：创建机器人后必须在机器人配置页绑定对应知识库，否则 AI 不会调用文档。

5. 插件与运行坑

• 安装失败：插件安装失败可能是版本不匹配，建议更新 AstrBot 本体到最新 v4.5.0 再尝试。
• 不主动发言：心流等主动回复插件需要配置双模型并开启群聊监听白名单。
• 隐私安全：不要把 API Key、企业密钥随意分享或上传到公网配置，避免 API 被盗刷扣费。

6. 合规提醒

• 腾讯协议：QQ 个人号机器人违反腾讯用户协议，商用客服优先选择企业微信/公众号官方机器人渠道。
• 网络法规：对接境外 TG、Discord 需遵守国内网络法规，合规使用网络环境。