alfred-proxy/SETUP.md

Alfred Proxy Setup Guide

Quick Start

1. Install Dependencies

cd ~/.openclaw/workspace/alfred-proxy
npm install

2. Create Authentik OAuth Provider

In Authentik admin:

1. Navigate to Applications → Providers → Create

2. Select OAuth2/OpenID Provider

3. Fill in:

   • Name: Alfred Mobile OAuth
   • Authentication flow: default-authentication-flow
   • Authorization flow: default-provider-authorization-explicit-consent
   • Client type: Public
   • Client ID: (will be auto-generated, note this down!)
   • Redirect URIs:

     alfredmobile://oauth/callback
     http://localhost:8080/callback
     

   • Signing Key: Select an existing certificate
   • Scopes: Add openid, profile, email

4. Click Create

5. Copy the Client ID from the provider details page

3. Create Authentik Application

1. Navigate to Applications → Applications → Create

2. Fill in:

   • Name: Alfred Mobile
   • Slug: alfred-mobile
   • Provider: Select Alfred Mobile OAuth (the provider you just created)
   • UI settings: (optional) Add icon, description
   • Policy engine mode: any

3. Click Create

4. Configure the Proxy

cd ~/.openclaw/workspace/alfred-proxy

# Copy example config
cp .env.example .env

# Edit with your Authentik client ID
nano .env

Update .env:

AUTHENTIK_CLIENT_ID=<paste-your-client-id-here>

5. Test Locally (No Auth)

# Disable auth for testing
echo "REQUIRE_AUTH=false" >> .env

# Start proxy
npm run dev

In another terminal:

# Test health check
curl http://localhost:18790/health

# Test WebSocket (requires wscat: npm install -g wscat)
wscat -c ws://localhost:18790

If you see OpenClaw's connect challenge, the proxy is working! ✅

6. Switch OpenClaw to Localhost

openclaw config get gateway.bind  # Should show "lan" currently

# Switch to localhost only
cat >> ~/.openclaw/openclaw.json << 'EOF'
{
  "gateway": {
    "bind": "loopback"
  }
}
EOF

# Or use the gateway tool
openclaw gateway config apply <<< '{"gateway":{"bind":"loopback"}}'

# Restart gateway
systemctl --user restart openclaw-gateway.service

# Verify
openclaw config get gateway.bind  # Should show "loopback"

7. Enable Auth

# Re-enable auth
nano .env  # Set REQUIRE_AUTH=true

# Restart proxy
# (If running npm run dev, Ctrl+C and restart)

8. Install as Systemd Service

cd ~/.openclaw/workspace/alfred-proxy

# Install service
mkdir -p ~/.config/systemd/user
cp alfred-proxy.service ~/.config/systemd/user/

# Create override file with your Client ID
mkdir -p ~/.config/systemd/user/alfred-proxy.service.d
cat > ~/.config/systemd/user/alfred-proxy.service.d/override.conf << EOF
[Service]
Environment="AUTHENTIK_CLIENT_ID=YOUR_CLIENT_ID_HERE"
EOF

# Reload systemd
systemctl --user daemon-reload

# Enable and start
systemctl --user enable alfred-proxy.service
systemctl --user start alfred-proxy.service

# Check status
systemctl --user status alfred-proxy.service

# View logs
journalctl --user -u alfred-proxy.service -f

9. Expose via Network (Optional)

Option A: Expose directly (for testing on local network)

Update .env:

# Listen on all interfaces instead of just localhost
# (only if you understand the security implications)
PROXY_PORT=0.0.0.0:18790

Option B: Expose via HAProxy with SSL (recommended)

See README.md for HAProxy configuration.

10. Test with OAuth Token

Get a test token from Authentik:

# Use Authentik's OAuth2 token endpoint
curl -X POST https://auth.dnspegasus.net/application/o/token/ \
  -d "grant_type=password" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD" \
  -d "client_id=YOUR_CLIENT_ID"

Or use the Authentik admin UI to generate a token.

Test with the token:

wscat -c ws://localhost:18790 -H "Authorization: Bearer YOUR_TOKEN"

Troubleshooting

Proxy won't start

Check Node.js:

node --version  # Should be v24+

Check dependencies:

cd ~/.openclaw/workspace/alfred-proxy
npm install

"ECONNREFUSED" connecting to OpenClaw

Check OpenClaw is running:

systemctl --user status openclaw-gateway.service

Check OpenClaw bind mode:

openclaw config get gateway.bind  # Should be "loopback"

Test OpenClaw directly:

wscat -c ws://127.0.0.1:18789

"Invalid token" error

Verify Authentik URL:

curl https://auth.dnspegasus.net/.well-known/openid-configuration

Test token validation:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://auth.dnspegasus.net/application/o/userinfo/

Check Client ID matches:

• .env has correct AUTHENTIK_CLIENT_ID
• Token was issued for the correct client

Logs show nothing

Check service is running:

systemctl --user is-active alfred-proxy.service

Increase log verbosity: Edit the service to add --debug flag (future enhancement).

Next Steps

1. Configure Android app to use OAuth flow
2. Add HAProxy SSL for production access
3. Set up monitoring for the proxy service
4. Configure firewall rules if exposing externally

Security Checklist

• OpenClaw bound to localhost only
• Proxy validates all OAuth tokens
• OpenClaw token not exposed to clients
• HTTPS/WSS for external access
• Firewall rules in place
• Monitoring and logs configured
• Authentik user management set up
• Test token revocation works