AstrBot 本地部署教程

目标架构

本教程实现的架构：WSL2 本地部署 AstrBot + Telegram 接入 + HAPI 插件 + 人格配置。

AstrBot 以本地源码方式运行在 WSL2 中，直接连接 Telegram 官方 Bot API，无需任何中间层，安全且响应快。

一、WSL2 安装与配置

1.1 启用 Windows 虚拟化组件

以管理员身份打开 PowerShell，依次执行：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完毕后重启电脑。

1.2 手动下载并安装 Ubuntu 到 D 盘

由于 wsl --install 容易因网络或商店问题失败，推荐手动导入镜像到指定位置。

在浏览器中下载镜像文件（选 amd64 版本）：

https://cloud-images.ubuntu.com/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz

下载完成后，在管理员 PowerShell 中执行：

mkdir D:\wsl\Ubuntu
wsl --import Ubuntu-22.04 D:\wsl\Ubuntu "你的下载路径\ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz" --version 2

验证安装成功：

wsl -l -v

看到 Ubuntu-22.04 Stopped 2 即为成功，原始 tar.gz 文件之后可以删除。

1.3 配置镜像网络（共享 Windows 代理）

在 PowerShell 中打开配置文件：

notepad $env:USERPROFILE\.wslconfig

写入以下内容并保存：

[wsl2]
nestedVirtualization=true
ipv6=true

[experimental]
autoMemoryReclaim=gradual
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

此配置让 WSL 直接复用 Windows 的网络栈，Windows 上开启的代理在 WSL 内也可直接使用，无需在 Linux 内部额外配置 export http_proxy。

执行以下命令使配置生效：

wsl --shutdown

1.4 创建个人用户

进入 WSL：

wsl

系统默认以 root 登录，执行以下命令创建普通用户：

adduser 你的用户名
usermod -aG sudo 你的用户名

将该用户配置为默认登录账户：

echo -e "[user]\ndefault=你的用户名" >> /etc/wsl.conf

退出后重启 WSL 使配置生效：

exit

wsl --shutdown
wsl

重新进入后提示符应显示 你的用户名@主机名。

1.5 换国内源并安装基础工具

Ubuntu 默认连接国外服务器较慢。若代理的 TUN 模式干扰了 apt（表现为卡在 Waiting for headers），先临时关闭代理 TUN 模式，换源后再重新开启：

sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list
sudo sed -i 's/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list

更新并安装基础工具。使用 -E 参数可以将当前用户的环境变量（包括代理配置）传递给 sudo：

sudo -E apt update && sudo -E apt install zsh tmux git curl wget -y

安装 Oh My Zsh（使用 Gitee 国内镜像）：

sh -c "$(curl -fsSL https://gitee.com/pocmon/ohmyzsh/raw/master/tools/install.sh)"

安装过程中输入 Y 将 zsh 设为默认 shell，后续终端提示符会变为 ➜。

二、本地部署 AstrBot

2.1 安装 uv 包管理器

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv --version

看到版本号输出即安装成功。

2.2 克隆 AstrBot 源码

务必在家目录（~ 即 /home/你的用户名）下操作，不要在 /mnt/c/ 等 Windows 路径下克隆，否则会有跨文件系统性能问题：

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

2.3 安装依赖并启动

uv sync
uv run main.py

启动后终端会显示：

✨✨✨ AstrBot v4.x.x WebUI 已启动
➜ 本地: http://localhost:6185
默认用户名和密码: astrbot

保持此终端窗口运行，不要关闭，它是机器人的后台进程。

三、手机上创建 Telegram Bot

在 Telegram 中搜索 @BotFather，发送：

/newbot

按提示依次输入 Bot 的显示名称和用户名（用户名必须以 bot 结尾），创建成功后 BotFather 会返回一个 Token，格式如：

8524119611:AAGOu-jdGsjGHR5ER59YRxofdd6Xpxu8VIY

保存这个 Token，后续配置中需要使用。

四、AstrBot 网页端配置

浏览器访问 http://127.0.0.1:6185，用默认账号密码 astrbot 登录。

4.1 接入 Telegram

进入左侧菜单的消息平台，点击添加，选择 Telegram，填入 BotFather 提供的 Token。

代理地址若需填写，格式使用 HTTP 协议（如 http://127.0.0.1:7890），不要填 socks5 格式，否则会触发依赖缺失报错：

To use Socks5 proxies, PTB must be installed via 'pip install "python-telegram-bot[socks]"'

保存后重启 AstrBot，终端出现 Telegram Platform Adapter is running 即为接入成功。

重启方式：在运行 AstrBot 的 WSL 终端按 Ctrl+C 停止，然后重新执行：

uv run main.py

4.2 接入大模型 API

进入左侧菜单的 AI 配置 → 提供商，点击添加：

ID：填一个自定义名称（如 deepseek）
提供商类型：选择对应平台
API Key：填入对应平台的密钥
模型：填入模型名称（如 deepseek-chat）

4.3 配置管理员 ID

获取自己的 Telegram 用户 ID：在 Telegram 中搜索 @getmyid_bot 或 @IDBot，发送任意消息，机器人会回复一串数字即为你的 User ID。

也可以直接在 AstrBot 终端日志中查找，向机器人发消息后日志会打印出发送者 ID，格式类似：

[telegram(telegram)] Unknown/... id=8752812866

进入 AstrBot 管理面板的设置 → 核心配置，找到管理员列表，填入你的 User ID，保存。

五、人格配置

5.1 创建人格

进入左侧菜单的人格，点击新建，设置名称和系统提示词。

系统提示词参考结构：

你是[名字]，[用户名]的专属助手。你说话风格[描述风格]，回复时[行为习惯]。

权限说明：只有 [用户名] 可以让你操控电脑或执行任务，其他人的此类请求一律拒绝。

角色扮演指南：
- 你在对话中始终保持角色，不自称 AI 或语言模型
- 每次回复控制在一到两句话以内，除非任务需要详细说明
- 回复时可以加入适当的动作描写体现个性

5.2 关联人格到机器人

进入左侧菜单的机器人，找到你的 Telegram 机器人，在关联人格下拉框中选择刚创建的人格，点击保存。

改完人格后在 Telegram 中发送以下命令清除旧对话上下文，让新人格立即生效：

/new

未完待续…