Secure Your OpenClaw Web UI with SSL in 20 Minutes

Set up HTTPS for OpenClaw's gateway using Tailscale Serve or reverse proxy. Stop exposing your AI assistant on plain HTTP.
·
5 min read
·
Mark
·
Security

Problem: Your OpenClaw Gateway is Running on Plain HTTP

You've deployed OpenClaw but accessing http://your-server:18789 triggers browser warnings, blocks WebCrypto features, and exposes your gateway auth tokens in plaintext.

You'll learn:

  • Why SSL matters for OpenClaw's Control UI
  • Three production-ready HTTPS methods (Tailscale, reverse proxy, SSH tunnel)
  • How to verify your setup blocks token leaks

Time: 20 min | Level: Intermediate

Why This Happens

OpenClaw's Control UI uses WebCrypto for device pairing and identity verification. Browsers block WebCrypto on non-HTTPS connections (except localhost), causing authentication failures. Additionally, plain HTTP exposes your gateway tokens to network sniffing.

Common symptoms:

  • "Device identity required" errors in the Control UI
  • Browser blocks WebCrypto APIs on LAN/WAN access
  • Gateway tokens visible in URL parameters over HTTP

Solution

Choose the method that fits your deployment:

MethodBest ForComplexity
Tailscale ServeRemote VPS, private accessLow
Reverse ProxyProduction deployments, custom domainsMedium
SSH TunnelQuick testing, developmentLow

Step 1: Check Your Current Setup

First, verify OpenClaw is running and note your configuration:

# Check gateway status
openclaw status

# View current binding mode
grep -A 5 '"gateway"' ~/.openclaw/openclaw.json

Expected: Gateway should show as running on port 18789.

Tailscale provides automatic HTTPS with zero certificate management.

Prerequisites:

  • Tailscale installed on your OpenClaw host
  • HTTPS enabled for your tailnet (enable here)

Configuration:

Edit ~/.openclaw/openclaw.json:

{
  "gateway": {
    "bind": "loopback",
    "tailscale": {
      "mode": "serve"
    },
    "auth": {
      "mode": "token",
      "token": "your-long-random-token"
    }
  }
}

Or use CLI flags:

openclaw gateway --tailscale serve

Why this works: Tailscale Serve creates an HTTPS proxy while keeping the gateway bound to localhost. The proxy injects identity headers for authentication.

Access your gateway:

# Get your Tailscale hostname
tailscale status

# Access via browser
# https://your-machine.your-tailnet.ts.net/

If it fails:

  • Error: "Tailscale not logged in": Run tailscale up
  • Error: "HTTPS not enabled": Enable HTTPS in your Tailscale admin console
  • Device pairing required: Approve the device: openclaw devices approve <device-id>

Step 2B: SSL via Reverse Proxy (Nginx/Caddy/HAProxy)

For custom domains or production deployments, use a battle-tested reverse proxy.

Option 1: Caddy (Automatic SSL)

Create /etc/caddy/Caddyfile:

openclaw.yourdomain.com {
    reverse_proxy localhost:18789 {
        # Preserve WebSocket connections
        header_up X-Forwarded-For {remote_host}
    }
}

Start Caddy:

sudo systemctl restart caddy

Why this works: Caddy automatically obtains Let's Encrypt certificates and handles renewals.

Option 2: Nginx with Let's Encrypt

Install Certbot:

sudo apt install certbot python3-certbot-nginx

Create /etc/nginx/sites-available/openclaw:

upstream openclaw {
    server 127.0.0.1:18789;
}

server {
    listen 80;
    server_name openclaw.yourdomain.com;
    
    location / {
        return 301 https://$server_name$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name openclaw.yourdomain.com;
    
    # Certbot will populate these
    ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://openclaw;
        proxy_http_version 1.1;
        
        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Preserve client IP
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable and obtain certificate:

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo certbot --nginx -d openclaw.yourdomain.com
sudo systemctl reload nginx

Configure OpenClaw for reverse proxy:

Edit ~/.openclaw/openclaw.json:

{
  "gateway": {
    "bind": "loopback",
    "trustedProxies": ["127.0.0.1"],
    "auth": {
      "mode": "password",
      "password": "${OPENCLAW_GATEWAY_PASSWORD}"
    }
  }
}

Set password via environment variable:

echo "export OPENCLAW_GATEWAY_PASSWORD='your-secure-password'" >> ~/.bashrc
source ~/.bashrc

If it fails:

  • 502 Bad Gateway: Check OpenClaw is running: openclaw status
  • WebSocket upgrade failed: Verify proxy_set_header Upgrade is set
  • Certificate errors: Ensure DNS points to your server before running Certbot

Step 2C: SSL via SSH Tunnel (Development/Testing)

For quick testing without full SSL setup, use an SSH tunnel:

# From your local machine
ssh -L 8443:127.0.0.1:18789 user@openclaw-server

# Access via browser
# https://localhost:8443/

Why this works: SSH provides encryption without requiring certificates. The tunnel exposes the remote gateway on your local machine.

Limitation: Only works while SSH connection is active. Not suitable for production or 24/7 access.

Step 3: Verify SSL Configuration

Test your HTTPS setup:

# Check certificate (Tailscale/reverse proxy)
curl -v https://your-openclaw-url/ 2>&1 | grep -A 5 "SSL certificate"

# Test WebSocket upgrade
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  https://your-openclaw-url/

You should see:

  • Valid SSL certificate chain
  • HTTP 101 Switching Protocols for WebSocket upgrade
  • No plain HTTP redirects

Test the Control UI:

  1. Open https://your-openclaw-url/ in a browser
  2. Enter your gateway token or password
  3. Verify device pairing prompt appears (if first connection)
  4. Check browser console shows no WebCrypto errors

Step 4: Harden Your Configuration

Once SSL works, lock down access:

Disable insecure fallbacks:

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": false,
      "dangerouslyDisableDeviceAuth": false
    }
  }
}

Run security audit:

openclaw security audit --deep

Fix any warnings:

openclaw security audit --fix

Expected output: No high-priority warnings, all credentials secured.

Verification Checklist

Use this to confirm your setup is production-ready:

  • HTTPS works without certificate warnings
  • WebSocket connections upgrade successfully
  • Gateway tokens not visible in browser network tab
  • Device pairing required on new devices
  • openclaw security audit shows no critical issues
  • Firewall blocks direct access to port 18789

What You Learned

  • WebCrypto requires HTTPS for OpenClaw's Control UI
  • Tailscale Serve provides zero-config SSL for tailnets
  • Reverse proxies enable custom domains and production deployments
  • SSL protects gateway tokens from network sniffing

Security note: SSL alone doesn't secure OpenClaw. Always use strong authentication (long tokens or passwords) and run openclaw security audit regularly.

Common Issues

"Device identity required" error persists

Cause: Browser unable to generate device identity over HTTP.

Fix: Ensure you're accessing via HTTPS, or enable allowInsecureAuth for testing only:

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

Certificate warnings on Tailscale

Cause: HTTPS not enabled for your tailnet.

Fix: Visit Tailscale admin → Enable HTTPS

WebSocket connection fails

Cause: Proxy not forwarding WebSocket upgrade headers.

Fix: Add WebSocket support to your proxy config (see Step 2B examples).

Tested on OpenClaw 2026.2.3, Ubuntu 24.04, macOS 14.x Security review: February 2026