简介
1. Termux
Termux 是一款运行于 Android 系统的开源终端模拟器。该软件提供了 Linux 环境,即使设备不具备 Root 权限也可使用。通过自带的包管理器(Pacman、APT),Termux 可以安装许多现代化的开发和系统维护工具,例如 zsh、Python、Ruby、NodeJS、MySQL 等软件。
Termux 目前在 F-Droid 和 GitHub 保持更新。
2. AstrBot
AstrBot 致力于成为一个开源的一站式 Agentic 聊天机器人平台及开发框架。通过它,你能够在多种消息平台上部署和开发一个支持大语言模型(LLM)的聊天机器人。
- 大模型对话:支持接入多种大模型服务。支持多模态、工具调用、MCP、原生知识库、人设等功能。
- 多消息平台支持:支持接入 QQ、企业微信、微信公众号、飞书、Telegram、钉钉、Discord、KOOK 等平台。
- Agent:完善适配的 Agentic 能力。支持多轮工具调用、内置沙盒代码执行器、网页搜索等功能。
- 插件扩展:深度优化的插件机制,支持开发插件扩展功能,社区插件生态丰富。
- WebUI:可视化配置和管理机器人,功能齐全。
3. NapCat
基于 TypeScript 构建的 Bot 框架,通过相应的启动器或者框架,主动调用 QQ Node 模块提供给客户端的接口,实现 Bot 的功能。
为了方便使用,猫猫框架将通过一种名为 OneBot 的约定将你的 HTTP / WebSocket 请求按照规范读取,再去调用猫猫框架所获得的 QQ 发送接口之类的接口。
这是通过 NapCatQQ 协议实现端接入 QQ。
前置准备:
- 一个 QQ 号(最好不是新创建的 QQ 号)。
- 一台具有摄像功能的手机以扫码登录 QQ。
NapCat 提供了大量的部署方式,包括 Docker、Windows 一键安装包等等。
步骤
1. 安装 Termux
- 从 F-Droid 应用商店下载 Termux。不要从 Google Play 下载,那里的版本可能已过时。
- 部分安卓手机应用商店会有 Termux 软件可以直接下载。
2. 更新系统包
打开 Termux,依次执行以下命令,更新软件源并安装基础工具。
pkg update && pkg upgrade
pkg install python git wget curl
换源 (可选)
建议更换源以获得更好的安装体验,但此换源并不会使 git clone 变得更快。
termux-change-repo
选择第一个 Mirror group Rotate between several mirrors,随后选择第三个 Mirrors in Chinese Mainland All in Chinese Mainland,等待跑完即可。
3. 申请存储权限
执行以下命令,会弹窗请求文件权限,请务必允许。
termux-setup-storage
正式部署
安装 proot-distro 及其他必须组件
首先安装 uv、git 和 proot-distro。
pkg install uv git proot-distro
使用 proot-distro 安装 ubuntu 环境。
中国大陆概率访问 GitHub,故建议使用加速器或代理。
proot-distro install ubuntu
登录 Ubuntu 环境
下载及配置完成会有提示 Log in with: proot-distro login ubuntu,输入相同的即可登入:
proot-distro login ubuntu
此时便进入了 Ubuntu 环境,我们需使用 apt 命令安装软件包了。
添加第三方 PPA
Python 3.10 并不在官方的软件源中,而 uv 所要求的 Python 版本为 3.10,所以进行此步为必须。
使用 apt 安装 software-properties-common (添加 PPA 前置)。
apt update && apt install software-properties-common
添加 deadsnakes PPA (Python 官方维护)。
add-apt-repository ppa:deadsnakes/ppa && apt update
添加时你可能会看到:Press [ENTER] to continue or Ctrl-c to cancel.,此时按下回车 (换行) 即可。
安装 Python
在进行完以上步骤后,即可安装 Python 3.10。
apt install python3.10
克隆 AstrBot 仓库
直到这里,您所处的路径应为 ~# 而不是其他次级目录,以防找不到项目目录:
git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot
如果一切顺利的话,您应该进入到了 ~/AstrBot# 下,可以进入到下一步了。
运行 AstrBot
uv run main.py
如果使用 uv 下载软件包时速度慢,可以更换源 (以 清华源 为例)。
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
如果没有报错,那么你可以看到 uv 在安装所需的包后出现类似 WebUI 已启动,可访问 并附带了几条链接。
如果有,那么恭喜你,你已经部署好了 AstrBot 并且运行了,接下来你可以尝试访问 localhost:6185 验证可用性。
提示:
Termux 与主机共享一个网络,即:Termux 的 IP 地址就是主机的 IP 地址,你也可使用 ifconfig 查看主机 IP 地址。
默认用户名和密码是 astrbot 和 astrbot。
退出:如需退出 proot-distro,可以使用 exit。
重新启动:每次重新进入 Termux 时需重新打开 proot 环境并启动 AstrBot,可以使用命令如下:
proot-distro login ubuntu cd AstrBot && uv run main.py
挂后台:开启
如需在一个 session 里面同时运行多个进程 (eg. AstrBot 和 Napcat),可以使用
uv run main.py & ......
关闭:上文运行后会有类似 [1] 1145 的输出,如需关闭进程,则可使用
kill -9 1145
或
pkill -9 -f "uv run main.py"
提示:也可以使用 screen 命令,较 & 更易操控。
apt install screen #安装 screen
screen -S <name> #创建新的会话
screen -r <name> #重新连接会话
screen -ls #列举会话
screen -X -S <name> quit #关闭会话
Ctrl + a + d #退出当前窗口
警告:在退出时,请注意保存自己的任务,以防数据丢失。
后台存活:如需让服务端在后台存活,可以在 设置 -> 应用和服务 -> 应用启动管理 -> Termux 改为 手动管理 并 允许后台活动 (或类似选项)。
接下来,你需要部署任何一个消息平台,才能够实现在消息平台上使用 AstrBot。
NapCat.Termux - 安卓 Termux 部署 recommend
Termux
curl -o napcat.termux.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.termux.sh && bash napcat.termux.sh
仓库地址:NapCat.installer
Linux
看这篇文章:NapCat.Installer - Linux 一键使用脚本 (支持 Ubuntu 20+/Debian 10+/Centos9)
Napcat WebUI 在哪打开:在 napcat 的日志里会显示 WebUI 链接。
如果是 linux 命令行一键部署的 napcat:docker log <qq 号>。
Docker 部署的 NapCat:docker logs napcat。
通过 Docker 部署
如果用 Docker 部署,将无法正常接收到 语音数据、文件数据。这意味着语音转文字、沙箱的文件输入功能将无法使用。可以接收到文字消息、图片消息等其他类型的消息。
默认您安装了 Docker。 在终端执行以下命令即可一键部署。
docker run -d \
-e NAPCAT_GID=$(id -g) \
-e NAPCAT_UID=$(id -u) \
-p 3000:3000 \
-p 3001:3001 \
-p 6099:6099 \
--name napcat \
--restart=always \
mlikiowa/napcat-docker:latest
执行成功后,需要查看日志以得到登录二维码和管理面板的 URL。
docker logs napcat
请复制管理面板的 URL,然后在浏览器中打开备用。 然后使用你要登录的 QQ 扫描出现的二维码,即可登录。 如果登录阶段没有出现问题,即成功部署。
连接到 AstrBot
在 AstrBot 配置 aiocqhttp
- 进入 AstrBot 的管理面板
- 点击左边栏
消息平台 - 然后在右边的界面中,点击
+ 新增适配器 - 选择
aiocqhttp(OneBotv11)
弹出的配置项填写:
- ID(id):随意填写,用于区分不同的消息平台实例。
- 启用 (enable): 勾选。
- 反向 WebSocket 主机地址:请填写你的机器的 IP 地址。一般情况下请直接填写
0.0.0.0 - 反向 WebSocket 端口:填写一个端口,例如
6199。
点击 保存。
配置管理员
填写完毕后,进入 配置 页,点击 其他配置 选项卡,找到 管理员 ID,填写你的 QQ 号(不是机器人的 QQ 号)。
切记点击右下角 保存,AstrBot 重启并会应用配置。
在 NapCatQQ 中添加 WebSocket 客户端
切换回 NapCatQQ 的管理面板,点击 网络配置->新建->WebSockets 客户端。

在新弹出的窗口中:
- 勾选
启用。 URL填写ws://宿主机 IP:端口/ws。如ws://localhost:6199/ws或ws://127.0.0.1:6199/ws。- 消息格式:
Array - 心跳间隔:
5000 - 重连间隔:
5000
- 切记后面加一个
/ws! - 这里的 IP 不是
0.0.0.0
点击 保存。
前往 AstrBot WebUI 控制台,如果出现 aiocqhttp(OneBot v11) 适配器已连接。 相关蓝色的日志,说明连接成功。
此时,你的 AstrBot 和 NapCatQQ 应该已经连接成功。使用 私聊 的方式在 QQ 对机器人发送 /help 以检查是否连接成功。
常见问题
问题一
如果 git clone 失败,那么其后的 cd 命令也不会生效,故在运行命令时请注意路径是否正确。
如果需要再次执行如上命令,建议先执行
rm -r AstrBot
之后再运行
git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot
AstrBot 管理面板 具有管理插件、查看日志、可视化配置、查看统计信息等功能。



