WebChat HTTPS Proxy

Standalone HTTPS/WSS reverse proxy for OpenClaw WebChat Control UI:

• Serves the Control UI over HTTPS (default port 8443)
• WebSocket passthrough to gateway (ws://127.0.0.1:18789)
• /transcribe proxy endpoint to local faster-whisper service (with Bearer token auth)
• Self-signed TLS certificate management
• SPA fallback for Control UI routing
• Path traversal protection for static file serving

Deploy

bash scripts/deploy.sh

Or expose on LAN:

VOICE_HOST=10.0.0.42 VOICE_HTTPS_PORT=8443 bash scripts/deploy.sh

This script is idempotent.

Quick verify

bash scripts/status.sh

Security Notes

Network isolation

• Localhost by default: Binds to 127.0.0.1 only. Not reachable from other devices unless VOICE_HOST is explicitly set.
• LAN access opt-in: Setting VOICE_HOST=<LAN-IP> enables trusted LAN access. Requires explicit configuration — never enabled automatically.
• CORS: Single allowed origin only (VOICE_ALLOWED_ORIGIN). Validated at startup — wildcards (*) and malformed origins are rejected.

TLS

• TLS 1.2+ enforced: Minimum protocol version set to TLS 1.2. Legacy SSL/TLS 1.0/1.1 rejected.
• Self-signed TLS: Auto-generated certificate. Browser certificate warning on first access.
• Private key permissions: chmod 600 on TLS key file.

Authentication

• Bearer token auth: /transcribe endpoint validates Bearer token against gateway auth token using constant-time comparison (hmac.compare_digest).
• When no gateway token is configured, auth is skipped (safe for localhost-only).

Input validation

• Upload size limit: 50 MB hard limit on /transcribe proxy requests (HTTP 413).
• Empty body rejection: HTTP 400 for empty requests.
• Response size limit: 10 MB cap on upstream response to prevent memory exhaustion.
• Path traversal protection: Static file serving resolves symlinks (os.path.realpath) and validates the resolved path stays within the Control UI directory.

Error handling

• No exception leaking: Error responses return generic messages, not internal exception details.
• Upstream timeout: 120s timeout on transcription backend requests.

SSRF protection

• Upstream URLs (VOICE_TRANSCRIBE_URL, VOICE_GATEWAY_WS) are validated to point to localhost only. Non-localhost targets are rejected at startup.

No data exfiltration

• No outbound network calls. Proxy only connects to localhost services.
• No telemetry, analytics, or phone-home behavior.

Persistence

• User systemd service starts on boot. Use uninstall.sh to fully revert.

What this skill modifies

What	Path	Action
Gateway config	~/.openclaw/openclaw.json	Adds HTTPS origin to gateway.controlUi.allowedOrigins
Systemd service	~/.config/systemd/user/openclaw-voice-https.service	Creates + enables persistent HTTPS proxy
Runtime file	~/.openclaw/workspace/voice-input/https-server.py	Copies proxy server
TLS certs	~/.openclaw/workspace/voice-input/certs/	Auto-generated self-signed cert on first run

Uninstall

bash scripts/uninstall.sh

Common fixes

• 404 /chat?... → SPA fallback missing in HTTPS proxy.
• origin not allowed → ensure deploy used correct VOICE_HOST and added matching HTTPS origin to gateway.controlUi.allowedOrigins.
• token missing → open URL with ?token=... once.
• pairing required → approve pending device via openclaw devices approve <requestId> --token <gateway-token>.