# OpenClaw Android Node

**An Android app that turns any Android device into an OpenClaw node, enabling remote control and automation.**

---

## Overview

This Android application connects to an OpenClaw gateway as a node, allowing the AI assistant to:
- Capture screenshots
- Perform touch gestures (tap, swipe, scroll)
- Launch apps
- Read notifications
- Execute shell commands
- Access sensors and device info

## Architecture

```
┌─────────────────┐      WebSocket       ┌─────────────────┐
│  OpenClaw       │◄───────────────────►│  Android Node   │
│  Gateway        │   (TLS/HTTPS)        │  (This App)     │
└─────────────────┘                      └─────────────────┘
                                                  │
                              ┌─────────────────────┼─────────────────────┐
                              ▼                     ▼                     ▼
                       ┌────────────┐        ┌────────────┐        ┌────────────┐
                       │ Screenshot │        │ Touch      │        │ Shell      │
                       │ Service    │        │ Controller │        │ Executor   │
                       └────────────┘        └────────────┘        └────────────┘
```

## Features

### Core Features

1. **WebSocket Node Protocol**
   - Connect to OpenClaw gateway via WebSocket
   - Heartbeat/keepalive
   - Command queueing
   - Auto-reconnect

2. **Screenshot Capture**
   - Real-time screen capture via MediaProjection API
   - Configurable quality/ FPS
   - Streaming or on-demand

3. **Touch Control**
   - Tap, double-tap
   - Swipe (any direction)
   - Long press
   - Pinch zoom (stretch goal)
   - Via AccessibilityService or shell injection

4. **App Control**
   - Launch apps by package name
   - List installed apps
   - Get foreground app info

5. **Shell Execution**
   - Execute ADB-like shell commands
   - Limited to app's own permissions

6. **Notification Mirroring**
   - Read notifications
   - Forward to gateway

7. **Device Info**
   - Battery status
   - Storage info
   - Network info
   - Sensors

### Advanced Features (Future)

- VNC server mode
- Image analysis for UI automation
- Tasker integration
- QR code pairing

---

## 📋 PENDING FEATURES (To Be Implemented)

### Permission System
- [ ] **Allowlist actions** - Actions permitted without user interaction (screenshot, touch, app launch, etc.)
- [ ] **Confirmation actions** - Sensitive actions requiring user confirmation (camera, microphone)
- [ ] **Remember choice** - Option to save preference permanently or ask every time
- [ ] **Per-action settings** - Granular control over each sensitive action

### Media Capabilities
- [ ] **Camera access** - Capture photos, record video
- [ ] **Microphone access** - Record audio
- [ ] **Audio playback** - Play audio files on device speaker

### Chat Interface
- [ ] **Text chat** - In-app chat with AI assistant
- [ ] **File upload** - Send files/images to gateway
- [ ] **Voice messages** - Record and send audio messages
- [ ] **Real-time calls** (Future) - Voice/video call capability

### Background Service
- [ ] **Persistent connection** - Keep WebSocket connected to gateway
- [ ] **No root required** - Work within Android's permission system
- [ ] **Battery optimization** - Handle Doze mode properly

### Donation System
- [ ] **PayPal** - PayPal.me or donation link
- [ ] **Cryptocurrency** - BTC and ETH addresses
- [ ] **Credit card** - Stripe or similar integration
- [ ] **In-app UI** - Clean donation menu in app

> ⚠️ **TODO**: Implement donation menu details - research PayPal SDK, crypto QR codes, Stripe integration

## Technical Stack

- **Language**: Kotlin
- **Min SDK**: 26 (Android 8.0)
- **Target SDK**: 34 (Android 14)
- **Architecture**: MVVM + Clean Architecture
- **DI**: Hilt
- **Networking**: OkHttp + OkWebSocket
- **Async**: Kotlin Coroutines + Flow
- **UI**: Jetpack Compose (minimal - mainly for settings)

## Project Structure

```
app/
├── src/main/
│   ├── java/com/openclaw/node/
│   │   ├── OpenClawApp.kt           # Application class
│   │   ├── di/                       # Dependency injection
│   │   ├── data/
│   │   │   ├── repository/          # Data layer
│   │   │   └── remote/
│   │   │       ├── NodeClient.kt    # WebSocket client
│   │   │       └── Commands.kt      # Command definitions
│   │   ├── domain/
│   │   │   ├── model/               # Domain models
│   │   │   └── usecase/             # Business logic
│   │   ├── service/
│   │   │   ├── NodeService.kt       # Foreground service
│   │   │   ├── ScreenshotService.kt
│   │   │   └── TouchService.kt
│   │   └── ui/
│   │       ├── MainActivity.kt
│   │       ├── settings/            # Settings screen
│   │       └── pair/                # QR code pairing
│   └── res/
└── build.gradle.kts
```

## OpenClaw Node Protocol

### Connection

```
ws://gateway:port/node/{node_id}?token={auth_token}
```

### Commands (Gateway → Node)

```json
{
  "type": "screenshot",
  "id": "uuid",
  "params": { "quality": 80 }
}
```

```json
{
  "type": "tap",
  "id": "uuid", 
  "params": { "x": 500, "y": 300 }
}
```

```json
{
  "type": "swipe",
  "id": "uuid",
  "params": { "x1": 100, "y1": 500, "x2": 100, "y2": 100, "duration": 300 }
}
```

```json
{
  "type": "launch_app",
  "id": "uuid",
  "params": { "package": "com.instagram.android" }
}
```

```json
{
  "type": "shell",
  "id": "uuid",
  "params": { "command": "ls -la /sdcard/" }
}
```

```json
{
  "type": "device_info",
  "id": "uuid"
}
```

### Responses (Node → Gateway)

```json
{
  "id": "uuid",
  "type": "response",
  "success": true,
  "data": { ... }
}
```

```json
{
  "id": "uuid", 
  "type": "error",
  "error": "Permission denied"
}
```

### Events (Node → Gateway)

```json
{
  "type": "notification",
  "data": {
    "app": "com.whatsapp",
    "title": "John Doe",
    "text": "Hello!"
  }
}
```

```json
{
  "type": "battery",
  "data": { "level": 45, "charging": true }
}
```

## Permissions Required

```xml
<!-- Network -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Screenshot (API 21+) -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />

<!-- Touch (Accessibility) -->
<uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE" />

<!-- Notifications -->
<uses-permission android:name="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE" />

<!-- Shell -->
<uses-permission android:name="android.permission.DEBUG" />
```

## Security

1. **Token-based authentication** - Node must provide valid token
2. **TLS encryption** - WSS (WebSocket Secure)
3. **Permission prompts** - User must grant all permissions
4. **IP allowlist** (optional) - Only connect from known gateways

## Setup Flow

1. Install app from APK / Play Store
2. Enter gateway URL and token (or scan QR)
3. Grant required permissions:
   - Accessibility (for touch)
   - Notification access
   - Overlay (for screenshot)
4. Connect and start using!

## Build

```bash
./gradlew assembleDebug
```

## License

MIT
