aidanpark--openclaw-android/android/README.md

OpenClaw Android App

Standalone APK for running OpenClaw on Android. Thin APK (~5MB) with WebView UI, native PTY terminal, Termux bootstrap runtime, and OTA updates.

Architecture

APK (~5MB)
├── Native: TerminalView (PTY terminal via libtermux.so)
├── WebView: React SPA (setup, dashboard, settings)
├── JsBridge: WebView ↔ Kotlin communication (31 methods, 7 domains)
├── EventBridge: Kotlin → WebView event dispatch
└── OTA: www.zip download + atomic replace

Build

Prerequisites

• JDK 21
• Android SDK (API 28+)
• NDK 28+
• Node.js 22+ (for WebView UI)

Build APK

cd android
./gradlew assembleDebug
# Output: app/build/outputs/apk/debug/app-debug.apk

Build WebView UI

cd android/www
npm install
npm run build        # Output: dist/
npm run build:zip    # Output: www.zip (for OTA)

Project Structure

android/
├── app/src/main/
│   ├── java/com/openclaw/android/
│   │   ├── MainActivity.kt           # WebView + TerminalView container
│   │   ├── OpenClawService.kt        # Foreground Service (START_STICKY)
│   │   ├── BootstrapManager.kt       # Bootstrap download/extract/configure
│   │   ├── JsBridge.kt               # 31 @JavascriptInterface methods
│   │   ├── EventBridge.kt            # Kotlin → WebView CustomEvent
│   │   ├── CommandRunner.kt          # Shell command execution
│   │   ├── EnvironmentBuilder.kt     # Termux environment variables
│   │   ├── UrlResolver.kt            # BuildConfig + config.json URL resolution
│   │   └── TerminalSessionManager.kt # Multi-session terminal management
│   ├── assets/www/                    # Bundled fallback UI (vanilla JS)
│   └── res/                           # Android resources
├── www/                               # React SPA (production WebView UI)
│   ├── src/
│   │   ├── lib/bridge.ts              # JsBridge typed wrapper
│   │   ├── lib/useNativeEvent.ts      # EventBridge React hook
│   │   ├── lib/router.tsx             # Hash-based router
│   │   └── screens/                   # All UI screens
│   └── dist/                          # Build output
├── terminal-emulator/                 # PTY emulator (from ReTerminal)
└── terminal-view/                     # Terminal rendering (from ReTerminal)

Key Design Decisions

Decision	Rationale
targetSdk 28	W^X bypass — allows exec in /data/data/
minSdk 24	apt-android-7 bootstrap requirement
Hash routing	file:// protocol doesn't support History API
No CSS framework	Minimal bundle size for OTA delivery
System font stack	Android WebView, no custom font loading needed

JsBridge API Domains

Domain	Methods	Description
Terminal	7	show/hide, create/switch/close sessions
Setup	3	bootstrap status, start setup
Platform	6	install/uninstall/switch platforms
Tools	5	install/uninstall CLI tools
Commands	2	sync/async shell execution
Updates	2	check/apply OTA updates
System	6	app info, battery, settings, storage

License

GPL v3