openclaw/docs/lightweight-phone-install.md

title, summary, read_when

title	summary	read_when
Android Phone (Lightweight)	Run OpenClaw on a cheap or old Android phone using Termux	You want to run the Gateway on a spare Android device You have a low-RAM or old Android phone you want to repurpose

OpenClaw on a cheap Android phone

A spare Android phone running Termux makes a reasonable always-on gateway node: no extra hardware, charges on a USB cable, and survives power cuts on a USB battery bank.

This is a Linux-in-Termux install. The phone runs the Gateway only; configure a hosted model (Anthropic, OpenAI) rather than a local model — local LLMs need GPU RAM.

---

Minimum requirements

Item	Minimum	Recommended
RAM	3 GB	4 GB+
Free storage	3 GB	5 GB+
Android version	8.0 (API 26)	10+
CPU	Any ARMv8 (64-bit)	4+ cores
Battery / power	Always plugged in, or USB bank	Dedicated USB charger

RAM note: Node 22 plus the gateway idle at ~200–350 MB. Under 3 GB of RAM the OS will kill background processes; 3 GB is workable with the optimizations below.

32-bit (ARMv7) devices are not supported — Node 22 requires a 64-bit OS. Check: uname -m in Termux should print aarch64.

---

Step 1: install Termux

Install Termux from F-Droid, not the Play Store. The Play Store version is abandoned and will have a too-old environment.

1. Enable "Install from unknown sources" for your browser (Settings > Apps > your browser > Install unknown apps).
2. Download and install from: https://f-droid.org/packages/com.termux/
3. Open Termux and update base packages:

pkg update && pkg upgrade -y

---

Step 2: install Node 22

Node 22 ships in Termux's package repository:

pkg install nodejs-lts -y

Verify:

node -v   # must be v22.x or higher
npm -v

If nodejs-lts gives you Node 20, check the Termux repo version or upgrade Termux itself first:

pkg upgrade -y

---

Step 3: install OpenClaw

npm install -g openclaw@latest

If this fails with EACCES or ENOENT:

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
npm install -g openclaw@latest

Verify:

openclaw --version

---

Step 4: run onboarding

openclaw onboard

Skip --install-daemon on the first run — Termux services work differently (see Step 6).

What to configure during onboarding:

• Auth: Use an API key (Anthropic or OpenAI). OAuth is harder to keep alive on a phone.
• Model: Pick a small, fast model — see the model recommendations below.
• Channels: Telegram bot or Discord bot are the most reliable on a phone; WhatsApp requires a stable always-on connection and is prone to disconnects.
• Workspace: accept the default (~/.openclaw/workspace).

---

Step 5: model and memory config for low-resource devices

Edit ~/.openclaw/openclaw.json (create it if missing). Use a cheap, fast model to reduce latency and API cost. claude-haiku-4 is the recommended default for low-resource setups.

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-haiku-4",
      },
      // Keep session history short to limit memory use during compaction
      session: {
        dmHistoryTurns: 20,
        groupHistoryTurns: 10,
      },
      // Disable sandbox (saves RAM; only skip this if you need code execution)
      sandbox: {
        mode: "off",
      },
    },
  },
}

If you have an OpenAI key instead:

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4o-mini",
      },
    },
  },
}

Do not run local models on a phone. They require GPU RAM that Android phones do not expose to Termux processes.

---

Step 6: keep it running (wake lock + background service)

Android aggressively kills background processes. You need two things:

A) Termux wake lock

Inside Termux, acquire a wake lock before starting the gateway:

termux-wake-lock

This keeps the CPU from sleeping while Termux is in the foreground or background. Requires the Termux:API app to be installed:

pkg install termux-api -y

Also install Termux:API from F-Droid: https://f-droid.org/packages/com.termux.api/

B) Disable battery optimization for Termux

1. Go to Settings > Apps > Termux > Battery.
2. Set to Unrestricted (or "Don't optimize" depending on your Android version).
3. Do the same for Termux:API if installed.

On some phones (Xiaomi, Samsung, Huawei, OnePlus) there is a secondary "protected apps" or "auto-launch" list — add Termux there too.

C) Run the gateway in a tmux session

Install tmux so the gateway survives accidental terminal closes:

pkg install tmux -y

Start a session:

tmux new-session -s gateway
termux-wake-lock
openclaw gateway run --bind loopback --port 18789

Detach with Ctrl+B then D. Reattach later with:

tmux attach -t gateway

D) Termux:Boot for auto-start after reboot

Install Termux:Boot from F-Droid: https://f-droid.org/packages/com.termux.boot/

Create the startup script:

mkdir -p ~/.termux/boot
cat > ~/.termux/boot/start-openclaw.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
termux-wake-lock
export PATH="$HOME/.npm-global/bin:$PATH"
tmux new-session -d -s gateway
tmux send-keys -t gateway "openclaw gateway run --bind loopback --port 18789 > /tmp/openclaw-gateway.log 2>&1" Enter
EOF
chmod +x ~/.termux/boot/start-openclaw.sh

After a reboot, Termux:Boot will run this script automatically. Verify with:

tmux attach -t gateway
tail -f /tmp/openclaw-gateway.log

---

Step 7: verify

openclaw gateway status
openclaw channels status
openclaw health

Check the log if something is wrong:

tail -n 50 /tmp/openclaw-gateway.log

---

Accessing the gateway remotely

The gateway binds to loopback by default. To reach it from another device:

Tailscale (recommended):

pkg install wget -y
wget -qO tailscale-install.sh https://tailscale.com/install.sh
bash tailscale-install.sh
tailscale up

Then expose the gateway over Tailscale:

openclaw gateway run --bind tailnet --port 18789

See Gateway remote access.

---

Common issues on cheap hardware

Gateway OOM-killed silently: Symptom: gateway stops responding, tmux session shows a dead shell. Fix: re-check battery optimization is disabled; acquire wake lock before starting; reduce history turns in config (see Step 5).

node: command not found after reboot: Fix: your PATH is not set in the boot script. Add the full path to Node:

export PATH="/data/data/com.termux/files/usr/bin:$HOME/.npm-global/bin:$PATH"

Add this line near the top of ~/.termux/boot/start-openclaw.sh.

sharp install error: Fix: skip the native build (you don't need sharp for gateway-only use):

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Termux exits when screen turns off: Fix: enable "Disable Battery Optimization" for Termux. On MIUI/HyperOS also enable "Auto-start" for Termux in Security/Battery apps.

WhatsApp disconnects frequently: WhatsApp web requires a stable persistent connection. On phones that sleep aggressively this is unreliable. Switch to Telegram or Discord bots instead — they use pull-based polling and are much more stable on constrained hardware.

Slow responses / timeouts on first query: The gateway and Node JIT need a moment to warm up after a restart. The second request will be faster. If timeouts persist, check that your API key is valid:

openclaw health
openclaw doctor

Storage fills up: Session JSONL files grow over time. Clear old sessions:

rm -rf ~/.openclaw/agents/*/sessions/*.jsonl

Or use compaction: send !compact in a chat with the agent to summarize and trim the active session.

---

Useful commands

# Gateway status
openclaw gateway status

# Full health + channel probe
openclaw health
openclaw channels status --probe

# Tail the log
tail -f /tmp/openclaw-gateway.log

# Restart the gateway inside tmux
tmux send-keys -t gateway C-c
tmux send-keys -t gateway "openclaw gateway run --bind loopback --port 18789 > /tmp/openclaw-gateway.log 2>&1" Enter

# Update openclaw
npm install -g openclaw@latest

---

Related docs

• Install — standard install guide
• Getting Started
• Gateway configuration
• Gateway remote access
• VPS hosting — cloud alternative if the phone is too constrained