alfred-mobile/README.md

Alfred Mobile

Android companion app for OpenClaw, providing voice interaction, push notifications, and mobile access to your AI assistant.

Features

• OAuth2 Authentication: Secure login via Authentik
• Voice Interaction: Wake word detection, voice input, TTS responses
• Push Notifications: Receive alerts and alarms
• Per-User Customization: Custom assistant names and voices
• Configurable Gateway: Connect to any OpenClaw instance
• Foreground Service: Persistent connection for real-time messaging

Setup

Prerequisites

• Android Studio Arctic Fox or newer
• Android SDK 26+ (target 34)
• JDK 17
• Firebase project (for push notifications)

Configuration

1. Clone the repository

2. Create secrets.properties in project root:

   GATEWAY_URL=wss://your-gateway-url.com
   AUTHENTIK_URL=https://auth.yourdomain.com
   AUTHENTIK_CLIENT_ID=your-oauth-client-id
   OAUTH_REDIRECT_URI=alfredmobile://oauth
   ELEVENLABS_API_KEY=your-elevenlabs-key (optional)
   ELEVENLABS_VOICE_ID=your-voice-id (optional)
   

3. Add Firebase configuration:

   • Download google-services.json from Firebase Console
   • Place in app/ directory

4. Build:

   ./gradlew assembleDebug
   

First Run

On first launch, the app will prompt for:

1. Gateway URL: Your OpenClaw/alfred-proxy WebSocket URL

   • Example: alfred.yourdomain.com
   • Protocol (wss://) is added automatically
   • Optional checkbox for insecure (ws://) connections

2. OAuth Login: Authenticate via your OAuth provider

3. Permissions: Grant microphone access for voice input

Features

Voice Interaction

• Wake Word: "Alfred" (customizable)
• Voice Input: Hold button or use wake word
• TTS: ElevenLabs integration with customizable voices

Notifications

• Push Notifications: Via FCM
• Alarms: Full-screen alarm activity with dismiss/snooze
• Cross-device Sync: Dismissing on one device dismisses on all

Customization

Settings → Customize:

• Gateway URL: Change server connection
• Assistant Name: Personalize (e.g., "Jarvis", "KITT")
• Voice: Choose from ElevenLabs voices
• Alarm Sound: Custom ringtone
• Wake Word: (coming soon)

Multi-User Support

Each OAuth user gets:

• Separate preferences
• Custom assistant name
• Individual voice selection
• Private conversation history

Architecture

Alfred Mobile App
    ↓ (OAuth JWT)
alfred-proxy (validates & routes)
    ↓ (OpenClaw token)
OpenClaw Gateway
    ↓
Agent Session (per user)

Security

Protected Files (.gitignore)

• secrets.properties - API keys and OAuth config
• app/google-services.json - Firebase config
• *.keystore - Signing keys
• *.jks - Signing keys

Never commit these files!

OAuth Flow

1. App redirects to Authentik
2. User authenticates
3. App receives OAuth code
4. Exchanges code for access token
5. Token used for all gateway requests

Development

Build Variants

# Debug build (uses BuildConfig secrets)
./gradlew assembleDebug

# Release build (requires signing config)
./gradlew assembleRelease

Install

# Via ADB
adb install -r app/build/outputs/apk/debug/app-debug.apk

# Wireless ADB
adb connect <device-ip>:5555
adb install -r app/build/outputs/apk/debug/app-debug.apk

Debugging

# View logs
adb logcat -s Alfred:D GatewayClient:D TTSManager:D

# Clear app data (reset first-run)
adb shell pm clear com.openclaw.alfred

Dependencies

Key libraries:

• Jetpack Compose: UI framework
• Dagger Hilt: Dependency injection
• OkHttp: WebSocket client
• Firebase: Cloud Messaging
• Vosk: Wake word detection
• AppAuth: OAuth2 client

See app/build.gradle.kts for full list.

Contributing

When submitting PRs:

1. Never commit secrets or credentials
2. Test on both tablet and phone form factors
3. Verify OAuth flow on fresh install
4. Check voice/TTS on long responses

Roadmap

• Custom wake word training
• Offline mode with cached responses
• Widget support
• Android Auto integration
• Wear OS companion app

License

MIT

Security Notice

This app handles OAuth tokens and has microphone access. Ensure:

• HTTPS/WSS only for production
• Validate OAuth redirect URIs
• Keep Firebase credentials secure
• Request minimum necessary permissions