# 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

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

### Build WebView UI

```bash
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