OpenClaw Gateway

What the Gateway Does

When you run OpenClaw, the binary starts two things: the agent runtime (which calls models and runs skills) and the gateway (the HTTP server on port 18789 by default). Everything that talks to the outside world — your browser, a Telegram webhook, the Discord WebSocket, a Hermes-style pairing request — goes through the gateway first.

• Serves the built-in chat web UI at /
• Issues device-pairing codes for new clients
• Validates auth tokens on every request
• Forwards channel webhooks (Telegram, Discord, WhatsApp, etc.) to the agent
• Streams agent responses back over WebSocket / SSE

Pairing Mode: How Devices Authorize

Pairing mode is OpenClaw's preferred auth flow. Instead of typing a long token, you open the web UI on a new device, get a 6-digit code, and approve it from an already-paired device. This is the same UX pattern as Apple TV / Hermes pairing codes.

Enable it in openclaw.json:

{
  "gateway": {
    "auth": {
      "token": "YOUR_LONG_RANDOM_TOKEN"
    },
    "controlUi": {
      "mode": "pairing"
    }
  }
}

When a user opens the gateway URL for the first time, they see a code. They approve it from an existing session (or the CLI), and the gateway issues a device-scoped token. See the pairing troubleshooting guide if the pairing screen doesn't appear.

Token-Based Auth

For headless / API access, the gateway accepts a static bearer token. Set it once, keep it secret, and pass it in the Authorization header on every request. You can also issue per-channel tokens that scope access to a single chat platform.

# Test token auth
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-gateway.example.com/api/health

For device pairing flows that don't require a separate web auth round-trip, set gateway.controlUi.allowInsecureAuth: true — this is what we use on OpenClaw Launch managed hosting.

Trusted Proxies

If you run the gateway behind a reverse proxy (Caddy, Nginx, Cloudflare), it needs to know which upstream IPs are trustworthy so it can read the real client IP from the X-Forwarded-For header. Set the exact IPs — CIDR notation is not supported:

{
  "gateway": {
    "trustedProxies": ["172.17.0.1", "10.0.0.1"]
  }
}

The most common mistake here is using 172.17.0.0/16 — that fails silently and the gateway treats your proxy as untrusted.

Channels and the Gateway

Every channel plugin (Telegram, Discord, WhatsApp, WeChat) registers a webhook or WebSocket against the gateway. The gateway authenticates the inbound message, calls the agent runtime, and writes the response back to the channel.

To enable a channel, the gateway needs both halves wired up:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "...",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  }
}

Both channels.X.enabled AND plugins.entries.X.enabled must be set, or the channel will silently fail to register.

Exposing the Gateway on a VPS

In production, you don't want the gateway open to the public internet on a raw port. Put it behind Caddy (or any reverse proxy) with HTTPS, and only expose the proxy to the world:

# Caddyfile
gateway.example.com {
  reverse_proxy localhost:18789
}

Caddy handles TLS via Let's Encrypt automatically. Pair this with trustedProxies: ["127.0.0.1"] in openclaw.json so the gateway trusts Caddy's X-Forwarded-For header.

Stopping and Restarting the Gateway

The gateway watches ~/.openclaw/openclaw.json and a few paths under /app. Most config edits hot-reload — channels.*, agents.*, and models.* apply within a second. Editing plugins.* or gateway.auth.* requires a restart:

# Soft restart, preserves sessions
openclaw gateway restart --safe

# Hard stop / start
openclaw gateway stop && openclaw gateway start

See the gateway stop guide for the full lifecycle reference.

Skip the Setup — Use Managed Hosting