跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
Python

安卓手机使用 Termux 搭配 AstrBot 与 NapCat 搭建 QQ 机器人

综述由AI生成简介 Termux Termux 是一款运行于 Android 系统的开源终端模拟器。该软件提供了 Linux 环境,即使设备不具备 root 权限也可使用。通过自带的包管理器(Pacman、APT),Termux 可以安装许多现代化的开发和系统维护工具,例如 zsh、Python、Ruby、NodeJS、MySQL 等软件。 Termux 目前已经恢复在 Google Play 更新,但仍在 F…

FrontendX发布于 2026/4/6更新于 2026/5/2583K 浏览
安卓手机使用 Termux 搭配 AstrBot 与 NapCat 搭建 QQ 机器人

简介

1. Termux

Termux 是一款运行于 Android 系统的开源终端模拟器。该软件提供了 Linux 环境,即使设备不具备 root 权限也可使用。通过自带的包管理器(Pacman、APT),Termux 可以安装许多现代化的开发和系统维护工具,例如 zsh、Python、Ruby、NodeJS、MySQL 等软件。

Termux 目前已经恢复在 Google Play 更新,但仍在 F-Droid 和 GitHub 保持更新。

2. AstrBot

AstrBot 致力于成为一个开源的一站式 Agentic 聊天机器人平台及开发框架。通过它,你能够在多种消息平台上部署和开发一个支持大语言模型(LLM)的聊天机器人。

  • 大模型对话。支持接入多种大模型服务。支持多模态、工具调用、MCP、原生知识库、人设等功能。
  • 多消息平台支持。支持接入 QQ、企业微信、微信公众号、飞书、Telegram、钉钉、Discord、KOOK 等平台。支持速率限制、白名单、百度内容审核。
  • Agent。完善适配的 Agentic 能力。支持多轮工具调用、内置沙盒代码执行器、网页搜索等功能。
  • 插件扩展。深度优化的插件机制,支持开发插件扩展功能,社区插件生态丰富。
  • WebUI。可视化配置和管理机器人,功能齐全。

3. NapCat

基于 TypeScript 构建的 Bot 框架,通过相应的启动器或者框架,主动调用 QQ Node 模块提供给客户端的接口,实现 Bot 的功能。

魔法版:猫猫框架通过魔法的手段获得了 QQ 的发送消息、接收消息等接口。

为了方便使用,猫猫框架将通过一种名为 OneBot 的约定将你的 HTTP / WebSocket 请求按照规范读取,再去调用猫猫框架所获得的 QQ 发送接口之类的接口。

这是通过 NapCatQQ 协议实现端接入 QQ。

  • 请合理控制使用频率。过于频繁地发送消息可能会被判定为异常行为,增加触发风控机制的风险。
  • 本项目严禁用于任何违反法律法规的用途。若您意图将 AstrBot 应用于非法产业或活动,我们明确反对并拒绝您使用本项目。

前置准备:

  • 一个 QQ 号(最好不是新创建的 QQ 号)。
  • 一台具有摄像功能的手机以扫码登录 QQ。

NapCat 提供了大量的部署方式,包括 Docker、Windows 一键安装包等等。

部署步骤

1. 安装 Termux

  • 从 F-Droid 应用商店下载 Termux。不要从 Google Play 下载,那里的版本可能已过时。
  • 链接:F-Droid - Termux
  • 部分安卓手机应用商店会有 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# 下,可以进入到下一步了。

如果步骤遇到 git clone 失败,那么其后的 cd 命令也不会生效。请跳转到常见问题。

运行 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
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 一键使用脚本

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
  1. 进入 AstrBot 的管理面板。
  2. 点击左边栏 消息平台。
  3. 然后在右边的界面中,点击 + 新增适配器。
  4. 选择 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
  1. 切记后面加一个 /ws!
  2. 这里的 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 管理面板 具有管理插件、查看日志、可视化配置、查看统计信息等功能。

文章配图

NapCatQQ 安装方法 可点击查看更多详细操作。

目录

  1. 简介
  2. 1. Termux
  3. 2. AstrBot
  4. 3. NapCat
  5. 部署步骤
  6. 1. 安装 Termux
  7. 2. 更新系统包
  8. 换源 (可选)
  9. 3. 申请存储权限
  10. 正式部署
  11. 安装 proot-distro 及其他必须组件
  12. 登录 Ubuntu 环境
  13. 添加第三方 PPA
  14. 安装 Python
  15. 克隆 AstrBot 仓库
  16. 运行 AstrBot
  17. 退出
  18. 重新启动
  19. 挂后台
  20. NapCat 部署
  21. Termux
  22. Linux
  23. 通过 Docker 部署
  24. 连接到 AstrBot
  25. 在 AstrBot 配置 aiocqhttp
  26. 配置管理员
  27. 在 NapCatQQ 中添加 WebSocket 客户端
  28. 常见问题
  29. 问题一
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫,关注极客日志

微信公众号「极客日志V2」,在微信中扫描左侧二维码关注。展示文案:极客日志V2 zeeklog

更多推荐文章

查看全部
  • WeblogicTool 部署与运行环境配置指南
  • Python YAML 模块实战:接口测试参数存储与配置
  • SpringBoot 整合 Neo4j 图数据库项目实战详解
  • 滑动窗口算法专题:四道经典题目深度解析
  • 大语言模型 LLM 核心技术及应用场景分析
  • MinIO 分布式对象存储介绍及与 SeaweedFS 对比
  • Java Lambda 与 Stream 详解
  • 基于 RTX 5090 云服务器部署 Stable Diffusion WebUI 指南
  • C++ 多线程同步之互斥锁(mutex)实战
  • Linux 进程间通信:命名管道(FIFO)实战指南
  • Claude Code 安装配置与项目实战指南
  • Java 泛型详解:语法、擦除与通配符
  • 算法实战:替换所有问号与提莫攻击
  • Stable Diffusion 入门指南:零基础 AI 绘图实战
  • 基于 Spring Boot 与 Leaflet 的省级旅游口号 WebGIS 可视化实践
  • ArrowDL BT 下载工具 v4.2.1 中文版安装教程
  • Unity Shader Graph Triplanar 节点原理解析与实战
  • AI 印象派工坊与 Stable Diffusion 轻量部署对比评测
  • Open WebUI MCPo 技术解析:MCP 工具转 OpenAPI 代理方案
  • 当前好用的 AI 辅助编程工具有哪些?一篇看懂 2026 年主流选择

相关免费在线工具

  • curl 转代码

    解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online

  • Markdown转HTML

    将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online

  • HTML转Markdown

    将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online

  • JSON 压缩

    通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online