# Webchat Https Proxy

> HTTPS/WSS reverse proxy for OpenClaw WebChat Control UI. Serves the Control UI over HTTPS with TLS cert management, proxies WebSocket connections to the gateway, and forwards /transcribe requests to the local faster-whisper endpoint. Runs as a user systemd service. Pure infrastructure — no voice-specific UI logic. Keywords: HTTPS proxy, WSS, TLS, reverse proxy, Control UI, systemd service, self-signed certificate, WebSocket proxy.

- Skill: `dvcrn/webchat-https-proxy` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add dvcrn/webchat-https-proxy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/webchat-https-proxy/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/webchat-https-proxy

---


# 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
bash scripts/deploy.sh
```

Or expose on LAN:
```bash
VOICE_HOST=10.0.0.42 VOICE_HTTPS_PORT=8443 bash scripts/deploy.sh
```

This script is idempotent.

## Quick verify

```bash
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
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>`.