openclaw-droid 2.0.1 → 2.0.4

package/README.md

@@ -1,197 +1,210 @@
-# OpenClaw Droid 🤖
-
-> **Run OpenClaw AI Gateway on Android via Termux**
-> One-command setup. Optimized for mobile. Bionic Bypass included.
-
-![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Platform](https://img.shields.io/badge/platform-Android%20%7C%20Termux-green.svg)
-![Version](https://img.shields.io/npm/v/openclaw-droid.svg)
-
-**OpenClaw Droid** makes running [OpenClaw](https://github.com/openclaw/openclaw) on Android effortless. It handles environment setup (proot-distro, Ubuntu, Node.js) and fixes Android-specific issues automatically.
-
-## 🚀 Why OpenClaw Droid?
-
-Running standard Node.js AI tools on Android is painful because of:
-*   **Bionic libc**: Android's C library differs from Linux (glibc), breaking `os.networkInterfaces()` and DNS lookups.
-*   **Permissions**: Termux has restricted access to system resources.
-*   **Environment**: Many tools expect a full Linux userland (Ubuntu/Debian).
-
-**OpenClaw Droid solves this by:**
-1.  Creating a lightweight **Ubuntu** container inside Termux.
-2.  Injecting a **Bionic Bypass** script to fix networking.
-3.  Providing a simple CLI (`openclaw`) to manage the gateway.
-
-## 📦 Installation
-
-### Prerequisites
-*   **Android 10+**
-*   **Termux** (Install from [F-Droid](https://f-droid.org/packages/com.termux/), NOT Play Store)
-*   **Termux:API** and **Termux:GUI** apps (from F-Droid)
-*   ~2GB free storage
-
-### Required Apps Setup
-
-1. **Install Termux** from [F-Droid](https://f-droid.org/packages/com.termux/)
-2. **Install Termux:API** from [F-Droid](https://f-droid.org/packages/com.termux.api/)
-3. **Install Termux:GUI** from [F-Droid](https://f-droid.org/packages/com.termux.gui/)
-4. **Grant permissions** in Android Settings:
-   - Go to Settings → Apps → Termux → Permissions
-   - Grant all permissions (Camera, Microphone, Storage, Location, etc.)
-   - Repeat for Termux:API and Termux:GUI
-5. **Disable battery optimization** for Termux:
-   - Go to Settings → Apps → Termux → Battery
-   - Set to "Unrestricted" or "Don't optimize"
-6. **Grant storage permissions** in Termux:
-   ```bash
-   termux-setup-storage
-   ```
-
-### Install Required Packages
-
-Update package lists and install essential tools:
-
-```bash
-# Update package lists
-pkg update && pkg upgrade
-
-# Install required packages
-pkg install -y git python nodejs-lts tmux nvim proot-distro termux-api termux-gui
-
-# Verify installations
-node --version
-python --version
-```
-
-### One-Command Setup
-Open Termux and run:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/NosytLabs/openclaw-droid/main/install.sh | bash
-```
-
-Or via npm:
-
-```bash
-npm install -g openclaw-droid
-openclaw setup
-```
-
-**IMPORTANT:** Use `npm install -g openclaw@latest` installation method (not bash script) as it's more reliable on Android. The installation may take 15-30 minutes due to llama.cpp compilation from scratch.
-
-## 🎮 Usage
-
-### 1. Initialize
-First, configure your API keys:
-
-```bash
-openclaw onboarding
-```
-> **IMPORTANT:** Select **Loopback (127.0.0.1)** for Binding.
-
-### 2. Start Gateway
-Launch the OpenClaw gateway:
-
-```bash
-openclaw start
-```
-
-**Recommended:** Run the gateway in a tmux session for better process management:
-
-```bash
-# Install tmux first if not installed
-pkg install tmux
-
-# Start a new tmux session
-tmux new -s openclaw
-
-# Run the gateway
-openclaw start
-
-# Detach from tmux (keep it running): Ctrl+B, then D
-# Reattach to tmux session: tmux attach -t openclaw
-```
-
-The dashboard will be available at:
-- **http://127.0.0.1:18789** (on the phone)
-- **http://<phone-ip>:18789** (from other devices on WiFi, requires gateway.bind = lan)
-
-### 3. Enable Screen Overlay (Optional)
-
-To allow OpenClaw to display overlay messages on your screen:
-
-```bash
-# In a separate tmux window or terminal:
-tmux new-window
-cd ~
-python ~/overlay_daemon.py
-```
-
-Or use the built-in command:
-
-```bash
-openclaw overlay
-```
-
-Now OpenClaw can write to the screen by creating `~/overlay.txt`:
-
-```bash
-printf 'Hello from OpenClaw!' > ~/overlay.txt
-```
-
-The overlay daemon watches for changes to `~/overlay.txt` and displays the content as a screen overlay. This is useful for displaying status updates, notifications, or important information to the user.
-
-### 4. Other Commands
-
-| Command | Description |
-| :--- | :--- |
-| `openclaw status` | Check installation health |
-| `openclaw update` | Update OpenClaw to latest version |
-| `openclaw shell` | Open Ubuntu shell |
-| `openclaw repair` | Re-install dependencies if broken |
-| `openclaw <cmd>` | Run any OpenClaw command (e.g., `openclaw doctor`) |
-
-## ⚠️ Troubleshooting
-
-**"Setup not complete" error**
-*   Run `openclaw setup` again.
-*   If it persists, run `openclaw repair`.
-
-**Process killed in background**
-*   Go to Android Settings → Apps → Termux → Battery → **Unrestricted**.
-
-**Permission denied errors**
-*   Run `termux-setup-storage` to grant storage permissions
-*   Ensure Termux:API and Termux:GUI have proper permissions
-
-**Cannot access /tmp/openclaw errors**
-*   OpenClaw requires a custom TMPDIR on Termux. The installer should configure this automatically.
-*   If you still see these errors, manually add to `~/.bashrc`:
-  ```bash
-  echo 'export TMPDIR="$PREFIX/tmp"' >> ~/.bashrc
-  echo 'export TMP="$TMPDIR"' >> ~/.bashrc
-  echo 'export TEMP="$TMPDIR"' >> ~/.bashrc
-  echo 'if [ ! -d "$TMPDIR" ]; then mkdir -p "$TMPDIR"; fi' >> ~/.bashrc
-  source ~/.bashrc
-  mkdir -p /data/data/com.termux/files/usr/tmp/openclaw
-  ```
-
-**"systemd not found" errors**
-*   These are normal on Android/Termux and can be safely ignored.
-*   OpenClaw will function without systemd.
-
-**Installation fails on dependencies**
-*   Some dependencies may fail to install initially. Install them manually:
-  ```bash
-  pkg install -y python git proot-distro
-  npm install -g openclaw@latest
-  ```
-*   The llama.cpp compilation takes 15-30 minutes - let it complete.
-
-**Gateway not accessible from other devices**
-*   Ensure `gateway.bind` is set to `lan` in your openclaw.json
-*   Check your phone's IP address: `ip addr show wlan0`
-*   Access via: `http://<phone-ip>:18789`
-
-## 📜 License
-
-MIT License.
+# OpenClaw Droid 🤖
+
+> **Run OpenClaw AI Gateway on Android via Termux**
+> One-command setup. Optimized for mobile. Bionic Bypass included.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Platform](https://img.shields.io/badge/platform-Android%20%7C%20Termux-green.svg)
+![Version](https://img.shields.io/npm/v/openclaw-droid.svg)
+
+**OpenClaw Droid** makes running [OpenClaw](https://github.com/openclaw/openclaw) on Android effortless. It handles environment setup (proot-distro, Ubuntu, Node.js) and fixes Android-specific issues automatically.
+
+## 🚀 Why OpenClaw Droid?
+
+Running standard Node.js AI tools on Android is painful because of:
+*   **Bionic libc**: Android's C library differs from Linux (glibc), breaking `os.networkInterfaces()` and DNS lookups.
+*   **Permissions**: Termux has restricted access to system resources.
+*   **Environment**: Many tools expect a full Linux userland (Ubuntu/Debian).
+
+**OpenClaw Droid solves this by:**
+1.  Creating a lightweight **Ubuntu** container inside Termux.
+2.  Injecting a **Bionic Bypass** script to fix networking.
+3.  Providing a simple CLI (`openclaw`) to manage the gateway.
+
+## 📦 Installation
+
+### Prerequisites
+*   **Android 10+**
+*   **Termux** (Install from [F-Droid](https://f-droid.org/packages/com.termux/), NOT Play Store)
+*   **Termux:API** and **Termux:GUI** apps (from F-Droid)
+*   ~2GB free storage
+
+### Required Apps Setup
+
+1. **Install Termux** from [F-Droid](https://f-droid.org/packages/com.termux/)
+2. **Install Termux:API** from [F-Droid](https://f-droid.org/packages/com.termux.api/)
+3. **Install Termux:GUI** from [F-Droid](https://f-droid.org/packages/com.termux.gui/)
+4. **Grant permissions** in Android Settings:
+   - Go to Settings → Apps → Termux → Permissions
+   - Grant all permissions (Camera, Microphone, Storage, Location, etc.)
+   - Repeat for Termux:API and Termux:GUI
+5. **Disable battery optimization** for Termux:
+   - Go to Settings → Apps → Termux → Battery
+   - Set to "Unrestricted" or "Don't optimize"
+6. **Grant storage permissions** in Termux:
+   ```bash
+   termux-setup-storage
+   ```
+
+### Install Required Packages
+
+Update package lists and install essential tools:
+
+```bash
+# Update package lists
+pkg update && pkg upgrade
+
+# Install x11-repo (required for termux-gui)
+pkg install -y x11-repo
+
+# Install required packages
+pkg install -y git python nodejs-lts proot-distro termux-api termux-gui
+
+# Verify installations
+node --version
+python --version
+```
+
+If termux-gui is unavailable, continue without it (overlay features disabled).
+
+### One-Command Setup
+Open Termux and run:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NosytLabs/openclaw-droid/main/install.sh | bash
+```
+
+Or via npm:
+
+```bash
+npm install -g openclaw-droid
+openclaw setup
+```
+
+**IMPORTANT:** Use `npm install -g openclaw@latest` installation method (not bash script) as it's more reliable on Android. The installation may take 15-30 minutes due to llama.cpp compilation from scratch.
+
+## 🎮 Usage
+
+### 1. Initialize
+First, configure your API keys:
+
+```bash
+openclaw onboarding
+```
+> **IMPORTANT:** Select **Loopback (127.0.0.1)** for Binding.
+
+### 2. Start Gateway
+Launch the OpenClaw gateway:
+
+```bash
+openclaw start
+```
+
+**Recommended:** Run the gateway in a tmux session for better process management:
+
+```bash
+# Install tmux first if not installed
+pkg install tmux
+
+# Start a new tmux session
+tmux new -s openclaw
+
+# Run the gateway
+openclaw start
+
+# Detach from tmux (keep it running): Ctrl+B, then D
+# Reattach to tmux session: tmux attach -t openclaw
+```
+
+The dashboard will be available at:
+- **http://127.0.0.1:18789** (on the phone)
+- **http://<phone-ip>:18789** (from other devices on WiFi, requires gateway.bind = lan)
+
+### 3. Enable Screen Overlay (Optional)
+
+To allow OpenClaw to display overlay messages on your screen:
+
+```bash
+# In a separate tmux window or terminal:
+tmux new-window
+cd ~
+python ~/overlay_daemon.py
+```
+
+Or use the built-in command:
+
+```bash
+openclaw overlay
+```
+
+Now OpenClaw can write to the screen by creating `~/overlay.txt`:
+
+```bash
+printf 'Hello from OpenClaw!' > ~/overlay.txt
+```
+
+The overlay daemon watches for changes to `~/overlay.txt` and displays the content as a screen overlay. This is useful for displaying status updates, notifications, or important information to the user.
+
+### 4. Other Commands
+
+| Command | Description |
+| :--- | :--- |
+| `openclaw status` | Check installation health |
+| `openclaw update` | Update OpenClaw to latest version |
+| `openclaw shell` | Open Ubuntu shell |
+| `openclaw repair` | Re-install dependencies if broken |
+| `openclaw <cmd>` | Run any OpenClaw command (e.g., `openclaw doctor`) |
+
+## ⚠️ Troubleshooting
+
+**"Setup not complete" error**
+*   Run `openclaw setup` again.
+*   If it persists, run `openclaw repair`.
+
+**Process killed in background**
+*   Go to Android Settings → Apps → Termux → Battery → **Unrestricted**.
+
+**Permission denied errors**
+*   Run `termux-setup-storage` to grant storage permissions
+*   Ensure Termux:API and Termux:GUI have proper permissions
+
+**Cannot access /tmp/openclaw errors**
+*   OpenClaw requires a custom TMPDIR on Termux. The installer should configure this automatically.
+*   If you still see these errors, manually add to `~/.bashrc`:
+  ```bash
+  echo 'export TMPDIR="$PREFIX/tmp"' >> ~/.bashrc
+  echo 'export TMP="$TMPDIR"' >> ~/.bashrc
+  echo 'export TEMP="$TMPDIR"' >> ~/.bashrc
+  echo 'if [ ! -d "$TMPDIR" ]; then mkdir -p "$TMPDIR"; fi' >> ~/.bashrc
+  source ~/.bashrc
+  mkdir -p /data/data/com.termux/files/usr/tmp/openclaw
+  ```
+
+**"systemd not found" errors**
+*   These are normal on Android/Termux and can be safely ignored.
+*   OpenClaw will function without systemd.
+
+**Installation fails on dependencies**
+*   Some dependencies may fail to install initially. Install them manually:
+  ```bash
+  pkg install -y python git proot-distro
+  npm install -g openclaw@latest
+  ```
+*   The llama.cpp compilation takes 15-30 minutes - let it complete.
+
+**"E: unable to locate package termux-git" errors**
+*   Install Termux from F-Droid and update repositories: `pkg update && pkg upgrade`
+*   Use `pkg install git` (the Termux package name is `git`, not `termux-git`)
+
+**"E: unable to locate package termux-gui" errors**
+*   Run `pkg install x11-repo` then retry `pkg install termux-gui`
+*   If it still fails, continue without termux-gui (overlay features disabled)
+
+**Gateway not accessible from other devices**
+*   Ensure `gateway.bind` is set to `lan` in your openclaw.json
+*   Check your phone's IP address: `ip addr show wlan0`
+*   Access via: `http://<phone-ip>:18789`
+
+## 📜 License
+
+MIT License.