← All guides AI Release
RU Subscribe to @ai_release1

How to Run AstrBot on Android Without a PC: Step-by-Step Setup with PRoot, NapCat and WebUI

Updated: 27.10.2026 · AI Release · @ai_release1
How to Run AstrBot on Android Without a PC: Step-by-Step Setup with PRoot, NapCat and WebUI

TL;DR

- Android device, Android 7.0 or newer (confirm the current minimum in the Termux release notes)

- Termux installed from F-Droid or the Termux GitHub releases — the Google Play build is deprecated and will not work

- proot-distro with a Debian container inside Termux

- Several gigabytes of free internal storage

- A QQ account for the bot (use a secondary account, not your main one)

- The QQ mobile app on a phone, to scan the login QR code

- An API key for one of the LLM providers supported by AstrBot (check the provider list in its documentation)

Requirements and setup

Illustration: Requirements and setup
Illustration: Requirements and setup

Placeholders used in this guide

PlaceholderReplace with
`<astrbot-repo-url>`clone URL copied from the AstrBot repository page
`<astrbot-webui-port>`the WebUI port AstrBot prints on startup
`<napcat-release-archive>`download URL of the Linux build from the NapCat releases page
`<napcat-webui-port>`the port NapCat prints for its own WebUI
`<napcat-ob11-port>`the OneBot 11 HTTP/WebSocket port you configure in NapCat
`<onebot-token>`a password you invent and paste into both sides
`<llm-api-key>`your provider key

Pre-flight checklist

Step 1. Build the Debian PRoot container in Termux

If you have never used a Linux container on Android, read How to Run Linux on Android Without Root: Termux, PRoot, and AI Tools first — it covers the Termux basics this step assumes.

What to do: open Termux and install the container tooling.

pkg update && pkg upgrade -y
pkg install -y proot-distro
proot-distro install debian
proot-distro login debian

Inside the container, install the runtime AstrBot needs:

apt update && apt upgrade -y
apt install -y python3 python3-venv python3-pip git curl unzip nano
python3 --version

Then take a wake lock so Android does not freeze Termux when the screen turns off:

termux-wake-lock

Why: PRoot gives you a normal Debian userland — apt, python3, git — without unlocking the bootloader. termux-wake-lock stops the system from suspending the process tree, which is the single most common reason a half-finished install dies overnight.

How to check:

cat /etc/os-release

Expected: a block starting with PRETTY_NAME="Debian ..." and ID=debian. Then python3 --version should print Python 3.x.y — compare the major/minor number against the minimum listed in the AstrBot documentation; if it is lower, install a newer Python or use a Debian release that ships a newer one.

Step 2. Install AstrBot and NapCat, then wire them together over OneBot 11

Illustration: Step 2. Install AstrBot and NapCat, then wire them together over OneBot 11
Illustration: Step 2. Install AstrBot and NapCat, then wire them together over OneBot 11

Two processes are involved. AstrBot is the bot framework: it receives messages, calls the LLM, and sends replies. NapCat is the QQ protocol adapter: it logs into QQ and exposes a local API. They talk over OneBot 11, a standard JSON/HTTP+WebSocket protocol, so AstrBot never touches QQ internals directly.

What to do (2A — AstrBot):

cd /root
git clone <astrbot-repo-url> AstrBot
cd AstrBot
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

The first start prints the WebUI address, for example http://127.0.0.1:<astrbot-webui-port>/. Copy that exact line — do not guess the port. Open it in the Android browser on the same device; PRoot shares the phone's network stack, so loopback works.

What to do (2B — NapCat):

cd /root
mkdir -p napcat && cd napcat
curl -L -o napcat.zip <napcat-release-archive>
unzip napcat.zip

Start the launcher from that folder and follow the on-screen QR code: scan it with the QQ mobile app logged into the bot account. Open NapCat's own WebUI at http://127.0.0.1:<napcat-webui-port>/ if you prefer a browser over the terminal.

Use the plain Linux build. Docker generally does not work inside PRoot because it needs kernel features the container does not provide.

What to do (2C — connect them): in the NapCat WebUI enable the HTTP and WebSocket servers, set <onebot-token> as the access token, and note <napcat-ob11-port>. Then in the AstrBot WebUI open the platform/adapter section, add the aiocqhttp (OneBot 11) adapter, and fill in:

FieldValue
Host`127.0.0.1`
Port`<napcat-ob11-port>`
Token`<onebot-token>`

Finally add your LLM provider in AstrBot and paste <llm-api-key>.

Why: OneBot 11 decouples the two halves. You can restart NapCat without reinstalling AstrBot, and the token prevents any other local app from impersonating the adapter.

How to check: confirm both ports are listening.

ss -tlnp | grep -E ':(<astrbot-webui-port>|<napcat-ob11-port>)'

You should see two LISTEN lines. Then ask NapCat who it is logged in as:

curl -s -X POST http://127.0.0.1:<napcat-ob11-port>/get_login_info \
  -H "Authorization: Bearer <onebot-token>" \
  -H "Content-Type: application/json" -d '{}'

Expected: JSON containing user_id and nickname of the bot account. A 401 means the token does not match.

Step 3. Run an end-to-end test and keep it alive

Illustration: Step 3. Run an end-to-end test and keep it alive
Illustration: Step 3. Run an end-to-end test and keep it alive

What to do: keep two Termux sessions open (swipe from the left edge → New session). Session A runs proot-distro login debian → cd /root/napcat → the NapCat launcher. Session B runs proot-distro login debian → cd /root/AstrBot → source .venv/bin/activate → python main.py. Then send a message from a second QQ account to the bot in a group where it is a member, or a private message.

Why: starting the adapter first guarantees the WebSocket endpoint exists when AstrBot connects; otherwise AstrBot retries and the log fills with connection warnings.

How to check: three signals at once.

1. The AstrBot console prints an incoming message event with the sender and text.

2. The WebUI dashboard shows the connected adapter and a message counter above zero.

3. QQ shows the bot's reply within a few seconds.

If you see the incoming event but no reply, the message reached AstrBot and the failure is in the LLM provider configuration, not in NapCat.

Troubleshooting

Problem. The install stops when the screen turns off.

pip install --no-cache-dir -r requirements.txt

Problem. AstrBot cannot reach NapCat.

Problem. pip install fails while building a wheel.

apt install -y build-essential python3-dev libffi-dev
pip install --no-cache-dir -r requirements.txt

Summary and next steps

You now have a Debian container inside Termux running NapCat as the QQ adapter and AstrBot as the bot logic, connected over OneBot 11 with a shared token and reachable through a local WebUI. Next, add a second platform adapter or a plugin in the AstrBot WebUI, and read How to Run an AI Model Locally on Android: Apps and Setup if you want inference on the device instead of a cloud provider.

FAQ

Can I run AstrBot on Android without root?

Yes. PRoot emulates a root filesystem in user space, so apt and python3 work inside Debian while the Android system itself stays untouched and unrooted.

Does NapCat work inside PRoot?

Yes, as the plain Linux build launched from the Termux session. Docker-based deployment generally fails there because the container cannot access the kernel features Docker requires.

Do I need a separate QQ account for the bot?

Use one. A bot that replies automatically to many messages behaves unlike a human account, and losing a secondary account costs you the bot, not your personal chats.

How do I open the AstrBot WebUI from my laptop?

By default it binds to loopback, so only the phone can reach it. Change the bind address in the AstrBot configuration to a LAN-reachable interface and restart — check the documentation for the exact config key, then open http://<phone-lan-ip>:<astrbot-webui-port>/.

🤖 AI summary

Related guides

How to Run Linux on Android Without Root: Termux, PRoot, and AI Tools

Пошаговое руководство по запуску полноценного Linux на Android-смартфоне без root-прав с помощью Termux и PRoot, включая

How to Run Metal Gear Solid 2 HD and Other NVIDIA SHIELD Ports on Android

Руководство по установке портов игр SHIELD на ARM64-смартфоны: где брать файлы, какие нужны данные, как настроить геймпа

How to Run an AI Model Locally on Android: Apps and Setup

Инструкция по запуску LLM на смартфоне с Android: выбор приложений, установка моделей и ограничения по памяти.