wehub-resource-sync
95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
# 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
|