Setting Up OpenClaw at klaw.local

A walkthrough of running OpenClaw locally behind nginx with HTTPS, covering every error hit along the way.

---

Prerequisites

• OpenClaw installed and gateway running

• nginx installed

• sudo access

---

Step 1 — /etc/hosts

Map klaw.local to loopback:

127.0.0.1   klaw.local

---

Step 2 — Self-signed SSL certificate

OpenClaw's Control UI requires HTTPS (or localhost) for WebSocket auth. Plain http://klaw.local gets rejected with:

disconnected (1008): control ui requires HTTPS or localhost (secure context)

Generate a self-signed cert:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/klaw.local.key \
  -out /etc/ssl/certs/klaw.local.crt \
  -subj "/CN=klaw.local"

Browser will show "Not secure" for self-signed certs on .local domains — this is cosmetic and doesn't affect functionality.

---

Step 3 — Nginx config

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

server {
    listen 443 ssl;
    server_name klaw.local;

    ssl_certificate /etc/ssl/certs/klaw.local.crt;
    ssl_certificate_key /etc/ssl/private/klaw.local.key;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400;
        proxy_pass_request_headers on;
    }
}

server {
    listen 80;
    server_name klaw.local;
    return 301 https://\(host\)request_uri;
}

Enable it and remove the default site:

sudo ln -s /etc/nginx/sites-available/klaw /etc/nginx/sites-enabled/klaw
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t && sudo nginx -s reload

Without removing default, nginx intercepts port 80 and serves its default page instead of redirecting.

---

Step 4 — Gateway token

After HTTPS is working, the next error is:

disconnected (1008): unauthorized: gateway token missing

Get your token:

# View existing token
openclaw config get gateway.auth.token

# Or generate a new one
openclaw doctor --generate-gateway-token

# Or get a full tokenized URL
openclaw dashboard --no-open

In the Control UI at https://klaw.local/overview, set:

Field	Value
WebSocket URL	wss://klaw.local
Gateway Token	(paste token here)
Default Session Key	main

Click Connect. The token is stored in localStorage so you won't need to re-enter it.

---

Step 5 — Device pairing

After the token is accepted, you may see:

disconnected (1008): pairing required

List pending devices and approve:

openclaw devices list

openclaw devices approve <request-uuid>

The UUID comes from the Request column in the pending devices table. After approving, click Connect again — health should show Online.

---

Error reference

Error	Cause	Fix
control ui requires HTTPS or localhost	Browser blocks WS auth on plain HTTP	Set up SSL + nginx on 443, use wss://
gateway token missing	Token not set in Control UI	Run openclaw config get gateway.auth.token and paste it in
pairing required	Device not approved	openclaw devices list then openclaw devices approve <uuid>

---

Final config summary

Item	Value
Hosts entry	127.0.0.1 klaw.local
SSL cert	/etc/ssl/certs/klaw.local.crt
SSL key	/etc/ssl/private/klaw.local.key
nginx	port 443 → 127.0.0.1:18789
HTTP redirect	port 80 → 301 HTTPS
Control UI	https://klaw.local/overview
WebSocket URL	wss://klaw.local
Gateway port	18789 (loopback only)