aidanpark/openclaw-android

한국어 | 中文 | 日本語

Because Android deserves a shell.

The standard approach to running OpenClaw on Android requires installing proot-distro with Linux, adding 700MB-1GB of overhead. OpenClaw on Android eliminates this by installing just the glibc dynamic linker (ld.so), letting you run OpenClaw without a full Linux distribution.

Standard approach: Install a full Linux distribution in Termux via proot-distro.

┌───────────────────────────────────────────────────┐
│ Linux Kernel                                      │
│ ┌───────────────────────────────────────────────┐ │
│ │ Android · Bionic libc · Termux                │ │
│ │ ┌───────────────────────────────────────────┐ │ │
│ │ │ proot-distro · Debian/Ubuntu              │ │ │
│ │ │ ┌───────────────────────────────────────┐ │ │ │
│ │ │ │ GNU glibc                             │ │ │ │
│ │ │ │ Node.js → OpenClaw                    │ │ │ │
│ │ │ └───────────────────────────────────────┘ │ │ │
│ │ └───────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────┘

This project: No proot-distro — just the glibc dynamic linker.

┌───────────────────────────────────────────────────┐
│ Linux Kernel                                      │
│ ┌───────────────────────────────────────────────┐ │
│ │ Android · Bionic libc · Termux                │ │
│ │ ┌───────────────────────────────────────────┐ │ │
│ │ │ glibc ld.so (linker only)                 │ │ │
│ │ │ ld.so → Node.js → OpenClaw                │ │ │
│ │ └───────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────┘

A standalone Android app is also available. It bundles a terminal emulator and a WebView-based UI into a single APK — no Termux required.

• One-tap setup: bootstrap, Node.js, and OpenClaw installed from within the app
• First install in the app (v0.4.5 or later): the app runs the first install itself and shows its progress in 7 steps; you can cancel during any step. An unfinished install (cancelled, the app was closed, or Android stopped it) is continued from where it stopped on the Continue the installation screen. Reinstall the base system repairs a broken base system without clearing the app's data (the home folder is kept). When the setup is done, a button types openclaw onboard into the terminal; press Enter to start onboarding
• Built-in dashboard for gateway control, runtime info, and tool management
• Tool installation: Settings → Additional Tools installs tmux, ttyd, dufs, Android Tools, Playwright, Claude Code, Gemini CLI, and Codex CLI through the setup script (post-setup.sh --tools-only); tmux, ttyd, dufs, and Android Tools are checked against the signed Termux package list. A tool whose install failed or whose --version check fails is shown as not working, with a Reinstall button. code-server, OpenCode, the SSH server, and Chromium cannot be installed from the app yet; code-server can be installed in the app's terminal with oa --install
• Install & Update: Settings → Install & Update runs oa --update from the app and shows its progress and result. It can be cancelled only in the early steps (before step 3, replacing the core files). The screen also shows the OpenClaw and Node.js versions, the result of the last update run from the app, and the gateway status with a Stop gateway button (only for a gateway started in the app's terminal)
• Works independently of Termux — installing the app does not affect an existing Termux + oa setup
• The app and an existing Termux setup are independent installs, but both start the OpenClaw gateway on the same default port (18789). Run the gateway in only one of them at a time

Download the APK from the Releases page.

• Android 7.0 or higher (Android 10+ recommended)
• ~2GB free storage (2000 MB; checked before a new install and before an update that changes the pinned versions)
• Wi-Fi or mobile data connection

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 of these:

1. glibc environment — Installs the glibc dynamic linker (via pacman's glibc-runner) so standard Linux binaries run without modification. The package list is verified against the Termux signing key before anything is installed
2. Node.js (glibc) — Downloads official Node.js linux-arm64 and wraps it with an ld.so loader script (no patchelf, which causes segfault on Android)
3. Path conversion — Automatically converts standard Linux paths (/tmp, /bin/sh, /usr/bin/env) to Termux paths
4. Temp folder setup — Configures an accessible temp folder for Android
5. Service manager bypass — Configures normal operation without systemd
6. OpenCode integration — If selected, installs OpenCode using proot + ld.so concatenation for Bun standalone binaries

1. Prepare Your Phone
2. Install Termux
3. Initial Termux Setup
4. Install OpenClaw — one command
5. Start OpenClaw Setup
6. Start OpenClaw (Gateway)

Configure Developer Options, Stay Awake, charge limit, and battery optimization. See the Keeping Processes Alive guide for step-by-step instructions.

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

Open the Termux app and paste the following command to install curl (needed for the next step).

pkg upgrade -y && pkg install -y curl

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

During the upgrade you may see questions about configuration files ((Y/I/N/O/D/Z) [default=N] ?). Press Enter to keep the default.

Don't skip the upgrade: installing curl alone on a fresh Termux can leave curl broken (CANNOT LINK EXECUTABLE "curl"). If that already happened, see Troubleshooting.

Tip: Use SSH for easier typing From this step on, you can type commands from your computer keyboard instead of the phone screen. See the Termux SSH Setup Guide for details.

Paste the following command in Termux.

curl -sL https://myopenclawhub.com/install | 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.

As instructed in the installation output, run:

openclaw onboard

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

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.

The gateway occupies the terminal while running, so open a new tab for it. Tap the hamburger icon (☰) on the bottom menu bar, or swipe right from the left edge of the screen (above the bottom menu bar) to open the side menu. Then tap NEW SESSION.

In the new tab, run:

openclaw gateway

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

Android may kill background processes or throttle them when the screen is off. See the Keeping Processes Alive guide for all recommended settings (Developer Options, Stay Awake, charge limit, battery optimization, and Phantom Process Killer).

See the Termux SSH Setup Guide for SSH access and dashboard tunnel setup.

The dashboard itself is at http://127.0.0.1:18789/. If it asks for a token (or shows "unauthorized"), print the token and open the dashboard with it:

node -p "require(process.env.HOME + '/.openclaw/openclaw.json').gateway.auth.token"

Then paste it into the dashboard's auth field, or open http://127.0.0.1:18789/#token=<token>. Keep the token private. Details: Dashboard asks for a token.

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.

After installation, the oa command is available for managing your installation:

oa --update && source ~/.bashrc

This single command updates all installed components at once:

• OpenClaw — Core package, kept at the pinned, verified version (currently 2026.10.2 — not always the newest release)
• code-server — Browser IDE
• OpenCode — AI coding assistant
• AI CLI tools — Claude Code, Gemini CLI, Codex CLI (Termux)
• Android patches — Compatibility patches from this project

Already up-to-date components are skipped. Components you haven't installed are not touched — only what's already on your device gets updated. Safe to run multiple times.

If the gateway was running during the update, restart it afterwards (stop it and run openclaw gateway again, or restart the app) so it picks up the updated runtime.

Only one setup, update or tools run happens at a time (a new install, oa --update and a tool install from the Claw app share one lock). If another run is in progress, oa --update prints [FAIL] Another update, setup or tools run is in progress. Try again when it has finished. and exits with code 2 without changing the installation (see Troubleshooting).

When an update changes the pinned versions (for example the move to Node.js 24.21.0 and OpenClaw 2026.9 in Script v1.2.0), oa --update adds these safeguards:

• It needs 2000 MB of free space. If there is not enough, it stops before changing anything and shows the space needed and the space left.
• If the OpenClaw gateway is running, it stops without changing anything. Stop the gateway (Ctrl+C) and run oa --update again. In the Claw app, you can stop a gateway started in the app's terminal with Settings → Install & Update → Stop gateway; the app's Update button also stops such a gateway first. If the app stopped the gateway for the update, start it again from the Dashboard afterwards.
• It first creates a data backup in ~/.openclaw-android/backup/pre-update/ (only the latest 3 are kept). If Node.js does not answer while this backup is made, the update stops before Node.js and OpenClaw are changed; run it again, or set OA_SKIP_PRE_UPDATE_BACKUP=1 to update without the backup (your data is then not migrated automatically).
• After the install, it checks the OpenClaw configuration and data. If a data migration is needed and this run made the backup, it runs openclaw doctor --fix once automatically (up to 2 minutes). If that fails, it shows the backup location and the manual steps (stop the gateway, then run openclaw doctor --fix) and ends as a failure.

Set OA_SKIP_AUTO_DOCTOR=1 to turn off the automatic migration, or OA_SKIP_PRE_UPDATE_BACKUP=1 to skip the automatic backup.

oa --update never moves Node.js or OpenClaw to a lower version (for example when an older file is served right after a release). To lower them on purpose, set both OA_ALLOW_OPENCLAW_DOWNGRADE=1 and OA_ALLOW_NODE_DOWNGRADE=1. oa --restore restores data only, not the programs.

Note: openclaw update (and openclaw --update) is intentionally blocked — a guard keeps OpenClaw pinned to the version verified by this project. The gateway's "update available" notice is turned off for you (update.checkOnStart=false; if you turned it back on, it may print something like update available … Run: openclaw update — use oa --update instead). openclaw update status (read-only) still works. OpenClaw 2026.10.2 can also start its own update from the dashboard's Update button, from the agent's gateway tool, and from openclaw gateway call update.run; these paths do not go through the openclaw command guard, so the Node.js wrapper blocks OpenClaw's own update as well ([BLOCKED]). Its messages may suggest openclaw update --yes or openclaw update repair; both are blocked, so use oa --update.

If the oa command is not available (older installations), run it with curl:

curl -sL https://myopenclawhub.com/update | bash && source ~/.bashrc

OpenClaw's built-in backup command (openclaw backup create) relies on hardlinks, which Android blocks in app-private storage; the hard-link patch that OpenClaw on Android applies lets it copy instead (see the hard-link patch paragraph below). The oa --backup command archives your whole OpenClaw data folder (~/.openclaw) with tar and takes consistent snapshots of the SQLite databases. It then checks the archive with openclaw backup verify when OpenClaw accepts it, and otherwise with a gzip and tar check (OpenClaw 2026.9 and later reject archives that contain its absolute plugin-skills link; backups made since script v1.3.4 leave that link out, and restoring older ones works normally). If Node.js does not answer within the time limit (OA_NODE_PROBE_TIMEOUT, 30 s for quick calls; OA_NODE_WORK_TIMEOUT, 300 s for each database snapshot), the command stops with exit code 75 and creates no archive, instead of saving a copy that may be incomplete.

To create a backup:

oa --backup

Backups are stored in ~/.openclaw-android/backup/ with a timestamped filename (e.g., 2026-03-14T00-00-00.000Z-openclaw-backup.tar.gz). You can also specify a custom path: oa --backup ~/my-backups/. Each backup includes your configuration, state, conversation history, workspaces, and agents (logs, temporary files, plugin dependency folders and the generated plugin-skills links are left out).

Keep backups private. A backup contains your API keys and login credentials. The file is created so that only you can read it (shared storage such as /sdcard may ignore that); do not share it or upload it anywhere public.

Claw app: if oa --backup says backup.sh not found (apps installed before this feature), run oa --update once.

Before an update that changes the pinned versions, oa --update also creates a backup in ~/.openclaw-android/backup/pre-update/ automatically (the latest 3 are kept). See Update.

To restore from a backup:

oa --restore

This command lists all available backups in the default backup directory, including the pre-update/ ones. Simply select the number of the backup you wish to restore. The tool automatically detects the platform from the backup manifest and restores into ~/.openclaw/ on this device (backups made on another device work too). Stop the OpenClaw gateway first; the command refuses to run while it is up. Before overwriting anything, it saves a safety backup of your current data in ~/.openclaw-android/backup/pre-restore/. Files created after the backup was made are kept. A confirmation is required. If the backup was made with a newer OpenClaw version than the one installed, it warns you and asks for confirmation (the default is No). If the backup was made with an older OpenClaw version, it tells you to run openclaw doctor --fix after the restore. oa --restore restores data only, not the programs. If the safety backup cannot be saved (for example, no free space), the restore stops without changing anything; free some space and try again, or run oa --restore --force-no-safety to restore without one.

Data moved from another environment. After a move between the Claw app and Termux, between a debug and a release app, or a restore of a backup from another device, OpenClaw's data can still contain the home path of the other app (/data/data/<other package>/files/home/...). Android answers an access to another app's folder with a permission error (EACCES), and OpenClaw 2026.9's data migration stops there. oa --update (just before the configuration check) and every oa --restore (a restore on the same environment included) now rewrite those paths in the agent database registrations and stale lease rows of OpenClaw's state database and in the agent workspace and agentDir values of openclaw.json. Before changing anything, they save copies named ~/.openclaw/state/openclaw.sqlite.oa-before-repair-<timestamp> and ~/.openclaw/openclaw.json.oa-before-repair-<timestamp> (the latest 3 are kept). If a value cannot be repaired automatically, a warning says so; edit that path in openclaw.json to a location under your current home ($HOME). See the Troubleshooting Guide.

See the Troubleshooting Guide for detailed solutions.

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.

OpenClaw's local LLM support used node-llama-cpp. The pinned OpenClaw version no longer lists node-llama-cpp among its dependencies (its documentation describes a managed llama-server instead), and we have not tested local inference on a phone with this version — the notes below describe general limits, not a verified setup.

However, there are practical constraints:

For experimentation, small models like TinyLlama 1.1B (Q4, ~670MB) can run on the phone. For production use, cloud LLM providers are recommended.

Why --ignore-scripts? The installer uses npm install -g openclaw@2026.10.2 --ignore-scripts (the pinned version) because install scripts of native dependencies (node-gyp builds, prebuilt-binary downloads) mostly fail in Termux, and a single failure stops the whole installation. OpenClaw's essential parts work without them, so the scripts are skipped and only what is needed is restored explicitly.

openclaw-android/
├── bootstrap.sh                # curl | bash one-liner installer (downloader)
├── install.sh                  # Platform-aware installer (entry point)
├── oa.sh                       # Unified CLI (installed as $PREFIX/bin/oa)
├── post-setup.sh               # Claw App post-bootstrap setup (OTA delivery)
├── update.sh                   # Thin wrapper (downloads and runs update-core.sh)
├── update-core.sh              # Lightweight updater for existing installations
├── uninstall.sh                # Clean removal (orchestrator)
├── patches/
│   ├── glibc-compat.js        # Node.js runtime patches (os.cpus, networkInterfaces)
│   ├── argon2-stub.js          # JS stub for argon2 native module (code-server)
│   ├── termux-compat.h         # C header for Bionic native builds (sharp)
│   ├── spawn.h                 # POSIX spawn stub header
│   ├── systemctl               # systemd stub for Termux
│   ├── apply-patches.sh        # Legacy patch orchestrator (v1.0.2 compat)
│   └── patch-paths.sh          # Legacy path fixer (v1.0.2 compat)
├── scripts/
│   ├── lib.sh                  # Shared function library (colors, platform detection, prompts)
│   ├── check-env.sh            # Pre-flight environment check
│   ├── install-infra-deps.sh   # Core infrastructure packages (L1)
│   ├── install-glibc.sh        # glibc-runner installation (L2 conditional)
│   ├── install-nodejs.sh       # Node.js glibc wrapper installation (L2 conditional)
│   ├── install-build-tools.sh  # Build tools for native modules (L2 conditional)
│   ├── backup.sh               # Backup and restore OpenClaw data (oa --backup/--restore)
│   ├── build-sharp.sh          # Build sharp native module (image processing)
│   ├── install-chromium.sh     # Install Chromium for browser automation
│   ├── install-playwright.sh   # Install Playwright browser automation library
│   ├── install-code-server.sh  # Install/update code-server (browser IDE)
│   ├── install-opencode.sh     # Install OpenCode
│   ├── setup-env.sh            # Configure environment variables
│   └── setup-paths.sh          # Create directories and symlinks
├── platforms/
│   ├── openclaw/               # OpenClaw platform plugin
│   │   ├── config.env          # Platform metadata and dependency declarations
│   │   ├── env.sh              # Platform-specific environment variables
│   │   ├── install.sh          # Platform package install (npm, patches, clawdhub)
│   │   ├── update.sh           # Platform package update
│   │   ├── openclaw-shim.sh    # Writes the `openclaw update` version-pin guard
│   │   ├── uninstall.sh        # Platform package removal
│   │   ├── limits.sh           # Time limits for node/npm calls (update, verify, status)
│   │   ├── status.sh           # Platform status display
│   │   ├── verify.sh           # Platform verification checks
│   │   └── patches/            # Platform-specific patches
│   │       ├── openclaw-apply-patches.sh
│   │       ├── openclaw-patch-paths.sh
│   │       ├── openclaw-patch-hardlink.sh  # Android hard-link/reflink fallback for OpenClaw
│   │       └── openclaw-build-sharp.sh
├── tests/
│   └── verify-install.sh       # Post-install verification (orchestrator + platform)
└── docs/
    ├── disable-phantom-process-killer.md    # Keeping Processes Alive guide (EN)
    ├── disable-phantom-process-killer.ko.md # Keeping Processes Alive guide (KO)
    ├── 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

┌─────────────────────────────────────────────────────────────┐
│  Orchestrators (install.sh, update-core.sh, uninstall.sh)  │
│  ── Platform-agnostic. Read config.env and delegate.       │
├─────────────────────────────────────────────────────────────┤
│  Shared Scripts (scripts/)                                  │
│  ── L1: install-infra-deps.sh (always)                     │
│  ── L2: install-glibc.sh, install-nodejs.sh,               │
│         install-build-tools.sh (conditional on config.env) │
│  ── L3: Optional tools (user-selected)                     │
├─────────────────────────────────────────────────────────────┤
│  Platform Plugins (platforms/<name>/)                       │
│  ── config.env: declares dependencies (PLATFORM_NEEDS_*)  │
│  ── install.sh / update.sh / uninstall.sh / ...            │
└─────────────────────────────────────────────────────────────┘

# platforms/openclaw/config.env
PLATFORM_NEEDS_GLIBC=true
PLATFORM_NEEDS_NODEJS=true
PLATFORM_NEEDS_BUILD_TOOLS=true

MIT

The Claw app's terminal libraries (android/terminal-emulator, android/terminal-view) come from Termux and are under the Apache License 2.0.