Skip to content

igor-kan/openclaw-android

BranchesTags
 
 

Repository files navigation

OpenClaw on Android

OpenClaw on Android

Android 7.0+ Termux No proot License MIT GitHub Stars

Because Android deserves a shell.

Why?

An Android phone is a great environment for running an OpenClaw server:

  • Sufficient performance — Even models from a few years ago have more than enough specs to run OpenClaw
  • Repurpose old phones — Put that phone sitting in your drawer to good use. No need to buy a mini PC
  • Low power + built-in UPS — Runs 24/7 on a fraction of the power a PC would consume, and the battery keeps it alive through power outages
  • No personal data at risk — Install OpenClaw on a factory-reset phone with no accounts logged in, and there's zero personal data on the device. Dedicating a PC to this feels wasteful — a spare phone is perfect

No Linux install required

The standard approach to running OpenClaw on Android requires installing proot-distro with Ubuntu, adding 700MB-1GB of overhead. OpenClaw on Android eliminates this by patching compatibility issues directly, letting you run OpenClaw in pure Termux.

Standard (proot-distro) This project
Storage overhead 1-2GB (Ubuntu + packages) ~50MB
Setup time 20-30 min 3-10 min
Performance Slower (proot layer) Native speed
Setup steps Install distro, configure Linux, install Node.js, fix paths... Run one command

Requirements

  • Android 7.0 or higher (Android 10+ recommended)
  • ~500MB free storage
  • Wi-Fi or mobile data connection

Step-by-Step Setup (from a fresh phone)

  1. Enable Developer Options and Stay Awake
  2. Install Termux
  3. Initial Termux Setup and Background Kill Prevention
  4. Install OpenClaw — one command
  5. Start OpenClaw Setup
  6. Start OpenClaw (Gateway)
  7. Access the Dashboard from Your PC

Step 1: Enable Developer Options and Stay Awake

OpenClaw runs as a server, so the screen turning off can cause Android to throttle or kill the process. Keeping the screen on while charging ensures stable operation.

A. Enable Developer Options

  1. Go to Settings > About phone (or Device information)
  2. Tap Build number 7 times
  3. You'll see "Developer mode has been enabled"
  4. Enter your lock screen password if prompted

On some devices, Build number is under Settings > About phone > Software information.

B. Stay Awake While Charging

  1. Go to Settings > Developer options (the menu you just enabled)
  2. Turn on Stay awake
  3. The screen will now stay on whenever the device is charging (USB or wireless)

The screen will still turn off normally when unplugged. Keep the charger connected when running the server for extended periods.

C. Set Charge Limit (Required)

Keeping a phone plugged in 24/7 at 100% can cause battery swelling. Limiting the maximum charge to 80% greatly improves battery lifespan and safety.

  • Samsung: Settings > Battery > Battery Protection → Select Maximum 80%
  • Google Pixel: Settings > Battery > Battery Protection → ON

Menu names vary by manufacturer. Search for "battery protection" or "charge limit" in your settings. If your device doesn't have this feature, consider managing the charger manually or using a smart plug.

Step 2: Install Termux

Important: The Play Store version of Termux is discontinued and will not work. You must install from F-Droid.

  1. Open your phone's browser and go to f-droid.org
  2. Search for Termux, then tap Download APK to download and install
    • Allow "Install from unknown sources" when prompted

Step 3: Initial Termux Setup and Background Kill Prevention

Open the Termux app and paste the following command. It updates repos, installs curl, and enables background kill prevention — all in one go.

pkg update -y && pkg upgrade -y && pkg install -y curl && termux-wake-lock

You may be asked to choose a mirror on first run. Pick any — a geographically closer mirror will be faster.

Once termux-wake-lock runs, a notification pins in the status bar and prevents Android from killing the Termux process. To release it later, run termux-wake-unlock or swipe the notification away.

Disable Battery Optimization for Termux

  1. Go to Android Settings > Battery (or Battery and device care)
  2. Open Battery optimization (or App power management)
  3. Find Termux and set it to Not optimized (or Unrestricted)

The exact menu path varies by manufacturer (Samsung, LG, etc.) and Android version. Search your settings for "battery optimization" to find it.

Step 4: Install OpenClaw

Tip: Use SSH for easier typing From this step on, you can type commands from your computer keyboard instead of the phone screen. Run pkg install -y openssh && passwd && sshd on the phone, then connect from your PC with ssh -p 8022 <phone-ip>. See the Termux SSH Setup Guide for details.

Paste the following command in Termux.

curl -sL https://raw.githubusercontent.com/AidanPark/openclaw-android/main/bootstrap.sh | bash && source ~/.bashrc

Everything is installed automatically with a single command. This takes 3–10 minutes depending on network speed and device. Wi-Fi is recommended.

Once complete, the OpenClaw version is displayed along with instructions to run openclaw onboard.

Step 5: Start OpenClaw Setup

As instructed in the installation output, run:

openclaw onboard

Follow the on-screen instructions to complete the initial setup.

openclaw onboard

Step 6: Start OpenClaw (Gateway)

Once setup is complete, start the gateway:

Important: Run openclaw gateway directly in the Termux app on your phone, not via SSH. If you run it over SSH, the gateway will stop when the SSH session disconnects.

openclaw gateway

To stop the gateway, press Ctrl+C. Do not use Ctrl+Z — it only suspends the process without terminating it.

Step 7: Access the Dashboard from Your PC

To manage OpenClaw from your PC browser, you need to set up an SSH connection to your phone. See the Termux SSH Setup Guide to configure SSH access first.

Once SSH is ready, find your phone's IP address. Run the following in Termux and look for the inet address under wlan0 (e.g. 192.168.0.100).

ifconfig

Then open a new terminal on your PC and set up an SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 -p 8022 <phone-ip>

Then open in your PC browser: http://localhost:18789/

Run openclaw dashboard on the phone to get the full URL with token.

Managing Multiple Devices

If you run OpenClaw on multiple devices on the same network, use the Dashboard Connect tool to manage them from your PC.

  • Save connection settings (IP, token, ports) for each device with a nickname
  • Generates the SSH tunnel command and dashboard URL automatically
  • Your data stays local — Connection settings (IP, token, ports) are saved only in your browser's localStorage and are never sent to any server.

Bonus: AI CLI Tools on Your Phone

The compatibility patches included in this project fix Termux's native build environment, enabling popular AI CLI tools to install and run:

Tool Install
Claude Code (Anthropic) npm i -g @anthropic-ai/claude-code
Gemini CLI (Google) npm i -g @google/gemini-cli
Codex CLI (OpenAI) npm i -g @openai/codex

Install OpenClaw on Android first, then install any of these tools — the patches handle the rest.

Claude Code on Termux Gemini CLI on Termux Codex CLI on Termux

Update

If you already have OpenClaw on Android installed and want to apply the latest patches and environment updates:

curl -sL https://raw.githubusercontent.com/AidanPark/openclaw-android/main/update.sh | bash && source ~/.bashrc

This lightweight updater refreshes environment variables and patches without reinstalling everything. Safe to run multiple times.

Uninstall

bash ~/.openclaw-android/uninstall.sh

This removes the OpenClaw package, patches, environment variables, and temp files. Your OpenClaw data (~/.openclaw) is optionally preserved.

Troubleshooting

See the Troubleshooting Guide for detailed solutions.

What It Does

The installer automatically resolves the differences between Termux and standard Linux. There's nothing you need to do manually — the single install command handles all 5 of these:

  1. Platform recognition — Configures Android to be recognized as Linux
  2. Network error prevention — Automatically works around network-related crashes on Android
  3. Path conversion — Automatically converts standard Linux paths to Termux paths
  4. Temp folder setup — Automatically configures an accessible temp folder for Android
  5. Service manager bypass — Configures normal operation without systemd

Performance

CLI commands like openclaw status may feel slower than on a PC. This is because each command needs to read many files, and the phone's storage is slower than a PC's, with Android's security processing adding overhead.

However, once the gateway is running, there's no difference. The process stays in memory so files don't need to be re-read, and AI responses are processed on external servers — the same speed as on a PC.

Technical Documentation for Developers

Project Structure

openclaw-android/
├── bootstrap.sh                # curl | bash one-liner installer (downloader)
├── install.sh                  # One-click installer (entry point)
├── update.sh                   # Lightweight updater for existing installations
├── uninstall.sh                # Clean removal
├── patches/
│   ├── bionic-compat.js        # Platform override + os.networkInterfaces() + os.cpus() patches
│   ├── termux-compat.h         # C/C++ compatibility shim (renameat2 syscall wrapper)
│   ├── spawn.h                 # POSIX spawn stub header for Termux
│   ├── patch-paths.sh          # Fix hardcoded paths in OpenClaw
│   └── apply-patches.sh        # Patch orchestrator
├── scripts/
│   ├── build-sharp.sh          # Build sharp native module (image processing)
│   ├── check-env.sh            # Pre-flight environment check
│   ├── install-deps.sh         # Install Termux packages
│   ├── setup-env.sh            # Configure environment variables
│   └── setup-paths.sh          # Create directories and symlinks
├── tests/
│   └── verify-install.sh       # Post-install verification
└── docs/
    ├── termux-ssh-guide.md     # Termux SSH setup guide (EN)
    ├── termux-ssh-guide.ko.md  # Termux SSH setup guide (KO)
    ├── troubleshooting.md      # Troubleshooting guide (EN)
    ├── troubleshooting.ko.md   # Troubleshooting guide (KO)
    └── images/                 # Screenshots and images

Detailed Installation Flow

Running bash install.sh executes the following 7 steps in order.

[1/7] Environment Check — scripts/check-env.sh

Validates that the current environment is suitable before starting installation.

  • Termux detection: Checks for the $PREFIX environment variable. Exits immediately if not in Termux
  • Architecture check: Runs uname -m to verify CPU architecture (aarch64 recommended, armv7l supported, x86_64 treated as emulator)
  • Disk space: Ensures at least 500MB free on the $PREFIX partition. Errors if insufficient
  • Existing installation: If openclaw command already exists, shows current version and notes this is a reinstall/upgrade
  • Node.js pre-check: If Node.js is already installed, shows version and warns if below 22

[2/7] Package Installation — scripts/install-deps.sh

Installs Termux packages required for building and running OpenClaw.

  • Runs pkg update -y to refresh package repos
  • Installs the following packages:
Package Role Why It's Needed
nodejs-lts Node.js LTS runtime (>= 22) + npm package manager OpenClaw is a Node.js application. Node.js and npm are required to install it via npm install -g openclaw. LTS is used because OpenClaw requires Node >= 22.12.0
git Distributed version control Some npm packages have git dependencies. Sub-dependencies of OpenClaw may reference packages via git URLs. Also needed if installing this repo via git clone
python Python interpreter Used by node-gyp to run build scripts when compiling native C/C++ addons. Required when OpenClaw's dependency tree includes native modules (e.g., better-sqlite3, bcrypt)
make Build automation tool Executes Makefiles generated by node-gyp to compile native modules. Core part of the native build pipeline alongside python
cmake Cross-platform build system Some native modules use CMake-based builds instead of Makefiles. Cryptography-related libraries (argon2, etc.) often include CMakeLists.txt
clang C/C++ compiler Default C/C++ compiler in Termux. Used by node-gyp to compile C/C++ source of native modules. Termux uses Clang as standard instead of GCC
tmux Terminal multiplexer Allows running the OpenClaw server in a background session. In Termux, apps going to background may suspend processes, so running inside a tmux session keeps it stable
ttyd Web terminal Shares a terminal over the web. Used by My OpenClaw Hub to provide browser-based terminal access to the host
pyyaml (pip) YAML parser for Python Required for .skill packaging in OpenClaw. Installed via pip install pyyaml after the Termux packages
  • After installation, verifies Node.js >= 22 and npm presence. Exits on failure

[3/7] Path Setup — scripts/setup-paths.sh

Creates the directory structure needed for Termux.

  • $PREFIX/tmp/openclaw — OpenClaw temp directory (replaces /tmp)
  • $HOME/.openclaw-android/patches — Patch file storage location
  • $HOME/.openclaw — OpenClaw data directory
  • Displays how standard Linux paths (/bin/sh, /usr/bin/env, /tmp) map to Termux's $PREFIX subdirectories

[4/7] Environment Variables — scripts/setup-env.sh

Adds an environment variable block to ~/.bashrc.

  • Wraps the block with # >>> OpenClaw on Android >>> / # <<< OpenClaw on Android <<< markers for management
  • If the block already exists, removes the old one and adds a fresh one (prevents duplicates)
  • Environment variables set:
    • TMPDIR=$PREFIX/tmp — Use Termux temp directory instead of /tmp
    • TMP, TEMP — Same as TMPDIR (for compatibility with some tools)
    • NODE_OPTIONS="-r .../bionic-compat.js" — Auto-load Bionic compatibility patch for all Node processes
    • CONTAINER=1 — Bypass systemd existence checks
    • CXXFLAGS="-include .../termux-compat.h" — Force-include C/C++ compatibility shim for native module builds
    • GYP_DEFINES="OS=linux ..." — Override node-gyp OS detection for Android
    • CPATH="...glib-2.0..." — Provide glib header paths for sharp builds

[5/7] OpenClaw Installation & Patching — npm install + patches/apply-patches.sh

Installs OpenClaw globally and applies Termux compatibility patches.

  1. Copies compatibility patches to ~/.openclaw-android/patches/:
    • bionic-compat.js — Node.js runtime patches (needed during npm install)
    • termux-compat.h — C/C++ build compatibility (renameat2 syscall wrapper)
    • spawn.h → $PREFIX/include/spawn.h — POSIX spawn stub header (if missing)
  2. Runs npm install -g openclaw@latest
  3. patches/apply-patches.sh applies all patches:
    • Verifies bionic-compat.js final copy
    • Runs patches/patch-paths.sh — uses sed to replace hardcoded paths in installed OpenClaw JS files:
      • "/tmp" / '/tmp' → "$PREFIX/tmp" / '$PREFIX/tmp'
      • "/bin/sh" → "$PREFIX/bin/sh"
      • "/bin/bash" → "$PREFIX/bin/bash"
      • "/usr/bin/env" → "$PREFIX/bin/env"
    • Logs patch results to ~/.openclaw-android/patch.log
  4. scripts/build-sharp.sh builds the sharp native module for image processing (non-critical):
    • Installs libvips and binutils packages
    • Installs node-gyp globally
    • Sets GYP_DEFINES and CPATH for Android/Termux cross-compilation
    • Runs npm rebuild sharp inside the OpenClaw directory
    • If the build fails, prints a warning and continues — image processing won't work but the gateway runs normally

[6/7] Installation Verification — tests/verify-install.sh

Checks 7 items to confirm installation completed successfully.

Check Item PASS Condition
Node.js version node -v >= 22
npm npm command exists
openclaw openclaw --version succeeds
TMPDIR Environment variable is set
NODE_OPTIONS Environment variable is set
CONTAINER Set to 1
bionic-compat.js File exists in ~/.openclaw-android/patches/
Directories ~/.openclaw-android, ~/.openclaw, $PREFIX/tmp exist
.bashrc Contains environment variable block

All items pass → PASSED. Any failure → FAILED with reinstall instructions.

[7/7] OpenClaw Update

Runs openclaw update to ensure the latest version. On completion, displays the OpenClaw version and instructs the user to run openclaw onboard to start setup.

License

MIT

About

Run OpenClaw on Android with a single command — no proot, no Ubuntu

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • HTML 60.3%
  • Shell 34.2%
  • C 4.0%
  • JavaScript 1.5%