VPS/Remote Deployment: guide & origin/auth improvements for headless server setups

[robotica4us-collab]

Summary

Running Claw3D on a VPS (headless server) connected to a local OpenClaw gateway via reverse proxy or Cloudflare tunnel currently requires several manual config workarounds that aren't documented. This issue proposes a VPS/remote deployment guide and some small code improvements to make the setup smoother.

Problems Encountered

1. WebSocket Origin Rejection

The gateway proxy in server/gateway-proxy.js connects to the upstream gateway with an origin derived from the upstream URL (e.g., http://localhost:18789). The gateway's controlUi.allowedOrigins doesn't include this by default, causing immediate connection failures.

Workaround: Manually add http://localhost:18789 and http://localhost:3000 to allowedOrigins in openclaw.json.

2. Device Auth Blocks Remote Connections

When connecting through a tunnel/proxy, the gateway requires device identity auth (CONTROL_UI_DEVICE_IDENTITY_REQUIRED). There's no way to bootstrap device auth from a remote browser without first disabling it.

Workaround: Set dangerouslyDisableDeviceAuth: true and allowInsecureAuth: true in gateway config — which isn't documented and the naming is (rightly) scary.

3. Tunnel URL Must Be Pre-Configured

Ephemeral tunnel URLs (Cloudflare quick tunnels, ngrok, etc.) change on every restart. Each new URL must be manually added to allowedOrigins before the UI can connect.

4. No VPS/Remote Deployment Documentation

The README and existing docs cover local development but don't address headless server deployments, reverse proxies, or tunnel setups — which is a common use case for always-on AI office environments.

Proposed Solution

Documentation

A REMOTE_DEPLOYMENT.md guide covering:

• VPS prerequisites (Node.js, OpenClaw gateway running)
• Cloudflare tunnel setup (quick tunnel + persistent tunnel)
• Nginx/Caddy reverse proxy configuration
• Gateway config for remote access (origins, auth, trusted proxies)
• Security considerations (when to use device auth vs token auth)

Code Improvements (optional, depending on maintainer preference)

• Auto-include localhost origins in the gateway proxy since it always connects locally
• Document the allowedOrigins wildcard behavior (if supported) or add pattern matching
• Add CLAW3D_ALLOWED_ORIGINS env var for runtime configuration without rebuild

Environment

• Host: Ubuntu VPS (headless, no GUI)
• Tunnel: Cloudflare quick tunnel (cloudflared tunnel --url http://localhost:3000)
• Gateway: OpenClaw running locally on the same VPS, port 18789
• Proxy chain: Browser → Cloudflare → Claw3D (:3000) → WS proxy → Gateway (:18789)

Related

• NEXT_PUBLIC_GATEWAY_URL requires rebuild to take effect — not documented #57 (env var rebuild bug — the runtime config work helps here)
• How to customize the office/company name displayed in the 3D scene? #51 (office title customization — same pattern of env-based runtime config)