从零开始搭建你的第一个AI聊天机器人(一)：AstrBot本地部署教程

本文是 从零开始搭建你的第一个AI聊天机器人系列教程的第 1 篇
👉 本篇目标：成功在本地跑起 AstrBot 管理后台

• 第 2 篇：AstrBot 管理后台详细使用说明
• 第 3 篇：AstrBot + QQ，部署一个真正可用的聊天机器人

---

如果你最近在研究 AI 聊天机器人，想要一个：

• ✅ 可以 本地部署
• ✅ 支持 QQ / 微信 / Telegram / Discord
• ✅ 可接入 ChatGPT / Claude / Gemini
• ✅ 拥有 Web 管理后台
• ✅ 可扩展、可深度折腾

那么你一定绕不开一个项目：AstrBot。

这篇文章将一步一步带你完成 AstrBot 的本地部署，不需要 Linux 基础、不需要服务器，Windows 电脑即可完成。

---

📚 目录

1. 什么是 AstrBot？
2. 部署前的准备工作
3. 安装 Python 环境
4. 安装 uv 包管理器
5. 下载 AstrBot 项目
6. 安装项目依赖
7. 启动 AstrBot
8. 访问管理后台
9. 常见问题解答

一、什么是 AstrBot？

AstrBot 是一个 开源的一站式 AI 聊天机器人平台。

你可以把它理解为一个：

聊天机器人的“中控系统”

通过 AstrBot，你可以：

• 🤖 在 QQ / 微信 / Telegram / Discord 等平台部署机器人
• 🧠 接入 ChatGPT、Claude、Gemini 等大语言模型
• 📦 构建 专属知识库
• 🔧 为机器人添加记忆、工具调用、联网搜索等能力

支持的平台

平台	状态
QQ（OneBot / 官方）	✅
微信	✅
Telegram	✅
Discord	✅
飞书 / 钉钉 / Slack	✅

---

二、部署前的准备工作

💻 硬件要求

项目	建议
操作系统	Windows 10 / 11（64 位）
内存	4GB 以上
硬盘空间	至少 2GB

本教程以 Windows 为例，Linux / macOS 操作类似。

---

📦 需要的软件

• Python 3.10 或更高版本
• uv（Python 包管理器）

不用担心，下面会手把手教你安装。

---

三、安装 Python 环境

1️⃣ 检查是否已安装 Python

按 Win + R → 输入 cmd → 回车，在命令行中输入：

python --version

判断结果：

• ✅ 如果显示类似 Python 3.11.0 的内容 → 已安装，跳到第四部分
• ❌ 如果显示 不是内部或外部命令 → 未安装，继续下面的步骤

步骤 2：下载 Python

1. 打开浏览器，访问 Python 官网：
   👉 https://www.python.org/downloads/
2. 点击黄色的 “Download Python 3.x.x” 按钮下载

步骤 3：安装 Python

1. 双击下载的安装文件
2. 会弹出安装界面

⚠️ 【重要】一定要勾选底部的 “Add Python to PATH” 选项！

这一步非常关键，如果不勾选，后面的命令都无法正常使用！

3. 点击 “Install Now” 开始安装
4. 等待安装完成后，点击 “Close” 关闭

步骤 4：验证安装

1. 关闭之前的命令提示符窗口
2. 重新打开命令提示符（Win + R → cmd → 回车）
3. 输入：

python --version

如果显示 Python 版本号（如 Python 3.11.0），说明安装成功！🎉

---

四、安装 uv 包管理器

uv 是一个超快的 Python 包管理器，AstrBot 使用它来管理依赖。

步骤 1：打开命令提示符

按 Win + R，输入 cmd，按回车。

步骤 2：安装 uv

在命令提示符中输入以下命令，然后按回车：

pip install uv

等待安装完成，会显示：

Successfully installed uv-x.x.x

步骤 3：验证安装

输入以下命令验证：

uv --version

如果显示版本号（如 uv 0.9.15），说明安装成功！🎉

---

五、下载 AstrBot 项目

方式一：从 GitHub 下载

1. 打开浏览器，访问：
   👉 https://github.com/AstrBotDevs/AstrBot
2. 点击绿色的 “Code” 按钮
3. 点击 “Download ZIP”
4. 下载完成后，解压到你想要的位置
   例如：E:\AITool\AstrBot

方式二：使用 Git 克隆

如果你已经安装了 Git，可以在命令提示符中输入：

git clone https://github.com/AstrBotDevs/AstrBot.git

---

六、安装项目依赖

步骤 1：打开命令提示符

按 Win + R，输入 cmd，按回车。

步骤 2：进入项目目录

假设你的项目解压在 E:\AITool\AstrBot-master\AstrBot-master

输入以下命令（注意替换成你的实际路径）：

cd /d E:\AITool\AstrBot-master\AstrBot-master

💡 小技巧：cd /d 可以同时切换盘符和目录

步骤 3：安装依赖

输入以下命令：

uv sync

等待安装完成。

⏳ 第一次安装可能需要 3-10 分钟，请耐心等待！

看到类似以下提示，说明安装成功：

Resolved 156 packages in 2ms
Audited 154 packages in 39ms

---

七、启动 AstrBot

步骤 1：确保在项目目录

如果你关闭了命令提示符，需要重新进入项目目录：

cd /d E:\AITool\AstrBot-master\AstrBot-master

步骤 2：启动程序

输入以下命令：

uv run main.py

步骤 3：等待启动

程序会显示一些日志信息，当你看到类似以下内容时，说明启动成功：

AstrBot v4.8.0
正在启动 WebUI, 监听地址: http://0.0.0.0:6185
AstrBot 启动完成。

⚠️ 重要注意事项

1. 不要关闭命令提示符窗口 - 关闭后机器人就会停止运行
2. 如何停止程序 - 按 Ctrl + C
3. 如何再次启动 - 重复上述步骤

---

八、访问管理后台

步骤 1：打开浏览器

程序启动后，打开你的浏览器（Chrome、Edge、Firefox 等都可以）。

步骤 2：访问后台地址

在地址栏输入：

http://localhost:6185

按回车访问。

步骤 3：登录系统

你会看到登录界面，使用以下默认账号登录：

项目	值
用户名	astrbot
密码	astrbot

步骤 4：修改密码（强烈建议）

登录后，请立即修改默认密码！

路径：设置 → 系统设置 → 修改密码

---

九、常见问题解答

❓ 问题 1：提示 “python 不是内部或外部命令”

原因：Python 没有正确安装或没有添加到 PATH

解决方法：

1. 重新安装 Python
2. 安装时一定要勾选 “Add Python to PATH”
3. 安装完成后重新打开命令提示符

---

❓ 问题 2：提示 “uv 不是内部或外部命令”

原因：uv 没有正确安装

解决方法：重新执行安装命令：

pip install uv

---

❓ 问题 3：安装依赖时下载很慢或报错

原因：网络连接问题，默认使用国外的 PyPI 源

解决方法：使用国内镜像源

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

然后重新执行 uv sync

---

❓ 问题 4：启动时显示端口被占用

错误信息：Address already in use: 6185

原因：6185 端口被其他程序占用

解决方法：

1. 检查是否有其他 AstrBot 在运行
2. 修改配置文件中的端口号
3. 或者关闭占用该端口的程序

---

❓ 问题 5：浏览器无法访问 localhost:6185

解决方法：

1. 确保 AstrBot 程序正在运行
2. 检查命令提示符窗口是否显示 “启动完成”
3. 尝试使用以下地址访问：
   • http://127.0.0.1:6185
   • http://localhost:6185

---

❓ 问题 6：命令提示符显示乱码

原因：Windows 命令提示符的编码问题

影响：不影响正常使用，只是日志显示有问题

解决方法：

• 可以忽略
• 或使用 Windows Terminal 替代传统命令提示符

---

🎉 写在最后

如果你已经成功看到 AstrBot 管理后台页面，
那么恭喜你 —— 本地部署已经完成 🎉

📌 下一篇文章将介绍：

• AstrBot 管理后台的详细使用方法
• 如何配置大语言模型
• 机器人基础能力的开启方式

📌 第三篇将进入重头戏：
👉 AstrBot + QQ，部署一个真正可用的聊天机器人

如果你觉得本文对你有帮助，欢迎 收藏 / 点赞 / 转发，
我们下一篇见 👋