Initial commit: Alfred Mobile - AI Assistant Android App
- 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
This commit is contained in:
191
README.md
Normal file
191
README.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user