# How to Run AstrBot on Android Without a PC: Step-by-Step Setup with PRoot, NapCat and WebUI > AI Release · @ai_release1 · https://ai-release.org/guides/kak-zapustit-astrbot-na-android-bez-pk-poshagovaya-usta_en.html ## TL;DR - **Time to complete:** 60–90 minutes (most of it is downloading packages) - **Difficulty:** Advanced - **You will need:** - 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](https://ai-release.org/guides/img/kak-zapustit-astrbot-na-android-bez-pk-poshagovaya-usta-en-1.jpg?v=1793133931) - **Android version:** 7.0+. Older devices may fail to install the current Termux build. - **Storage:** keep several GB free. The Debian root filesystem, Python wheels and the QQ client all live on internal storage. - **Termux source:** F-Droid or GitHub releases only. The Play Store build is abandoned and its package repository is broken. - **Network:** stable Wi-Fi. The first `pip install` pulls hundreds of megabytes. - **Accounts:** a QQ account you can afford to lose (bots can be flagged), plus an LLM API key. - **Skills:** comfortable typing shell commands and reading logs. No Android rooting is required — PRoot (a user-space `chroot` that fakes root without touching the kernel) keeps everything inside Termux. **Placeholders used in this guide** | Placeholder | Replace with | |---|---| | `` | clone URL copied from the AstrBot repository page | | `` | the WebUI port AstrBot prints on startup | | `` | download URL of the Linux build from the NapCat releases page | | `` | the port NapCat prints for its own WebUI | | `` | the OneBot 11 HTTP/WebSocket port you configure in NapCat | | `` | a password you invent and paste into both sides | | `` | your provider key | **Pre-flight checklist** - [ ] Termux opens and `pkg update` finishes without errors - [ ] `proot-distro` is installed - [ ] A Debian container is installed and logs in - [ ] QQ mobile app is installed on a phone with the bot account logged in - [ ] LLM API key is saved somewhere you can copy from ## 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](https://ai-release.org/guides/kak-zapustit-linux-na-android-bez-root-termux-proot-i-i.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) first — it covers the Termux basics this step assumes. **What to do:** open Termux and install the container tooling. ```bash 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: ```bash 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: ```bash 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:** ```bash 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](https://ai-release.org/guides/img/kak-zapustit-astrbot-na-android-bez-pk-poshagovaya-usta-en-2.jpg?v=1793133937) 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):** ```bash cd /root git clone 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:/`. 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):** ```bash cd /root mkdir -p napcat && cd napcat curl -L -o napcat.zip 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:/` 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 `` as the access token, and note ``. Then in the AstrBot WebUI open the platform/adapter section, add the `aiocqhttp` (OneBot 11) adapter, and fill in: | Field | Value | |---|---| | Host | `127.0.0.1` | | Port | `` | | Token | `` | Finally add your LLM provider in AstrBot and paste ``. **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. ```bash ss -tlnp | grep -E ':(|)' ``` You should see two `LISTEN` lines. Then ask NapCat who it is logged in as: ```bash curl -s -X POST http://127.0.0.1:/get_login_info \ -H "Authorization: Bearer " \ -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](https://ai-release.org/guides/img/kak-zapustit-astrbot-na-android-bez-pk-poshagovaya-usta-en-3.jpg?v=1793133951) **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.** - Error: `[Process completed (signal 9) - press Enter]` in the Termux session - Cause: Android battery optimisation kills background processes, and the out-of-memory killer reaps Python builds that spike RAM. - Solution: run `termux-wake-lock`, then open Android Settings → Apps → Termux → Battery → set to **Unrestricted**. Re-run the failed command (for `pip`, adding `--no-cache-dir` reduces peak disk and memory use): ```bash pip install --no-cache-dir -r requirements.txt ``` **Problem. AstrBot cannot reach NapCat.** - Error: an HTTP `401 Unauthorized` from the `get_login_info` call, or `websocket connection closed` repeating in the AstrBot log - Cause: the token in the AstrBot adapter differs from the one in the NapCat config, or the adapter points at NapCat's WebUI port instead of the OneBot 11 port. - Solution: re-copy `` into both fields, verify the port with `ss -tlnp | grep `, then restart both processes in the order NapCat → AstrBot. **Problem. `pip install` fails while building a wheel.** - Error: `error: subprocess-exited-with-error` followed by `gcc: not found` or `Python.h: No such file or directory` - Cause: a dependency has no prebuilt wheel for your Python version and falls back to compiling from source, but the container has no compiler. - Solution: install the toolchain and retry: ```bash 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](https://ai-release.org/guides/kak-zapustit-ii-model-lokalno-na-android-prilozheniya-i.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) 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://:/`.