jknapp
6d4ae2e5c3
- OAuth authentication via Authentik - WebSocket connection to OpenClaw gateway - Configurable gateway URL with first-run setup - User preferences sync across devices - Multi-user support with custom assistant names - ElevenLabs TTS integration (local + remote) - FCM push notifications for alarms - Voice input via Google Speech API - No hardcoded secrets or internal IPs in tracked files
192 lines
4.3 KiB
Markdown
192 lines
4.3 KiB
Markdown
# 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:**
|
|
```properties
|
|
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:**
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
# Debug build (uses BuildConfig secrets)
|
|
./gradlew assembleDebug
|
|
|
|
# Release build (requires signing config)
|
|
./gradlew assembleRelease
|
|
```
|
|
|
|
### Install
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|