WebChat Voice Proxy

Set up a reboot-safe voice stack for OpenClaw WebChat (including the current polished mic/stop/hourglass UI states):

• HTTPS Control UI on port 8443
• /transcribe proxy to local faster-whisper service
• WebSocket passthrough to gateway (ws://127.0.0.1:18789)
• Voice button script injection into Control UI
• Real-time VU meter: button shadow/scale reacts to voice level
• Push-to-Talk: hold mic button to record, release to send (default mode)
• Toggle mode: click to start, click to stop (switch via double-click on mic button)
• Keyboard shortcuts: Ctrl+Space Push-to-Talk, Ctrl+Shift+M start/stop continuous recording
• Localized UI: auto-detects browser language (English, German, Chinese built-in), customizable

Prerequisites (required)

This skill requires a local faster-whisper HTTP service.

Expected default:

• URL: http://127.0.0.1:18790/transcribe
• systemd user service: openclaw-transcribe.service

Verify before deployment:

systemctl --user is-active openclaw-transcribe.service
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18790/transcribe -X POST -H 'Content-Type: application/octet-stream' --data-binary 'x'

If this dependency is missing, set up faster-whisper first (model load + HTTP endpoint), then run this skill.

Related skills:

• faster-whisper-local-service (backend prerequisite)
• webchat-voice-full-stack (meta-installer that deploys both backend + proxy)

Workflow

1. Ensure transcription service exists and is running (openclaw-transcribe.service).
2. Deploy voice-input.js to Control UI assets and inject script tag into index.html.
3. Configure gateway allowed origin for external HTTPS UI.
4. Run HTTPS+WSS proxy as persistent user systemd service (openclaw-voice-https.service).
5. Verify pairing/token/origin errors and resolve in order.

Security Notes

• Localhost by default: The HTTPS proxy binds to 127.0.0.1 only. It is not reachable from other devices on your network unless you explicitly set VOICE_HOST to a LAN IP.
• LAN exposure: Setting VOICE_HOST= exposes the proxy (and by extension the gateway WebSocket and transcription endpoint) to all devices on that network. Only do this on trusted networks.
• Persistence: This skill installs a user systemd service (openclaw-voice-https.service) that starts automatically on boot, and a gateway hook that re-injects the UI script after updates. Use uninstall.sh to fully revert.
• Self-signed TLS: The auto-generated certificate is not trusted by browsers. You will see a certificate warning on first access.

Deploy

Run (localhost only — default, most secure):

bash scripts/deploy.sh

Or expose on LAN (required to access from other devices):

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

When run interactively without VOICE_LANG, the script will ask you to choose a UI language (auto, en, de, zh). Set VOICE_LANG=auto to skip the prompt.

This script is idempotent.

Quick verify

Run:

bash scripts/status.sh

Expected:

• both services active
• injection present
• https:200

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 --token .
• Mic breaks after reboot → cert paths must be persistent (not /tmp).
• No transcription result → check local faster-whisper endpoint first.

See references/troubleshooting.md for exact commands.

What this skill modifies

Before installing, be aware of all system changes deploy.sh makes: