OpenClaw Gateway Token: Complete Setup, Security & Troubleshooting Guide (2026)

What Is the OpenClaw Gateway Token?

The OpenClaw gateway token is a secret authentication string stored in your openclaw.json configuration file. Think of it like a password for your AI agent's brain — every client that wants to talk to the OpenClaw gateway must present this exact token.

You'll see it referenced in different places as OPENCLAW_GATEWAY_TOKEN (environment variable), gateway.auth.token (config path), or "gateway token" (community shorthand). They all mean the same thing: the authentication credential in your OpenClaw configuration.

Without authentication, anyone who discovers your gateway's IP address and port (default 18789) could read all your AI conversations and memory files, send commands through your agent, access your connected services (email, calendar, APIs), and run shell commands on your server (if sandbox is disabled). The gateway token prevents all of this. No valid token = no access. Period.

OpenClaw supports three authentication modes. Token auth uses a pre-shared secret string and is best for VPS, Docker, remote access, and API integrations. Password auth uses a user-entered password on each login and is best for local/personal installs with the web UI. Pairing auth uses a one-time device approval code and is best for local installs and iOS app pairing.

For most deployments — especially Docker, VPS, or any remote setup — token auth is the recommended approach. It's the most compatible with automated systems and the Chrome browser relay.

If you omit mode and set only a token, OpenClaw defaults to token auth. If both token and password are set without an explicit mode, the gateway will refuse to start until you specify which one wins — a deliberate safety measure.

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secret-token-here"
    }
  }
}

How to Generate a Secure Gateway Token

Your gateway token should be a long, random, unguessable string. Here are the best methods, ranked by security.

Method 1: OpenClaw's Built-in Generator (Recommended) — This generates a cryptographically random token and optionally writes it to your config. It's the easiest and safest approach.

Method 2: UUID — UUIDs give you 122 bits of randomness — more than sufficient.

Method 3: Random Hex or Base64 — Use openssl to generate random strings of any length.

What NOT to use: password123 (dictionary attack in seconds), admin (first thing attackers try), my-openclaw-token (guessable pattern), test (development leftovers), or any short string under 16 characters (brute-forceable).

Security rule: Your token should be at least 32 characters of random data. If a human can memorize it, it's probably too weak.

# Method 1: OpenClaw built-in
openclaw doctor --generate-gateway-token

# Method 2: UUID
python3 -c "import uuid; print(uuid.uuid4())"
node -e "console.log(require('crypto').randomUUID())"
uuidgen

# Method 3: Random hex (128 bits) or base64 (216 bits)
openssl rand -hex 16
openssl rand -base64 36

Step-by-Step: Configuring the Gateway Token

Step 1: Generate Your Token — Generate a UUID token and save it somewhere safe. You'll need it for clients.

Step 2: Add the Token to openclaw.json — Open your config file (usually ~/.openclaw/openclaw.json) and add the gateway auth section. Or use the CLI with openclaw config set.

Step 3: Restart the Gateway — Use openclaw gateway restart, docker restart openclaw, or stop and start the process manually.

Step 4: Verify the Token Works — Run openclaw gateway health with the --url and --token flags. If you see Reachable: yes and RPC: ok, your token is configured correctly.

Step 5: Connect Your Clients — Enter the same token in the Web UI (paste at login prompt), Browser Relay Chrome Extension (paste in Token field), and iOS App (enter during pairing if using token auth mode).

# Step 1: Generate
TOKEN=$(uuidgen)
echo "Your token: $TOKEN"

# Step 2: Add to config (CLI method)
openclaw config set gateway.auth.token "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Step 3: Restart
openclaw gateway restart

# Step 4: Verify
openclaw gateway health --url ws://127.0.0.1:18789 --token "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
openclaw gateway probe

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

The #1 Mistake: Wrong JSON Structure

This is responsible for roughly 60% of all gateway token issues in the OpenClaw community. The auth field must be an object containing a token property.

Common wrong variations include: setting auth as a plain string instead of an object, putting the token at the wrong nesting level (directly under gateway instead of under gateway.auth), using "type" instead of "mode", and setting auth to the string "none" instead of an object.

OpenClaw uses strict schema validation. If the config doesn't match the expected structure exactly, the gateway refuses to start entirely. You won't even get a helpful error — just a validation failure. Run openclaw doctor to diagnose.

// ✅ CORRECT — auth is an object with a token property
{
  "gateway": {
    "auth": {
      "token": "your-token-here"
    }
  }
}

// ❌ WRONG — auth as a plain string
{ "gateway": { "auth": "your-token-here" } }

// ❌ WRONG — token at the wrong nesting level
{ "gateway": { "token": "your-token-here" } }

// ❌ WRONG — using "type" instead of "mode"
{ "gateway": { "auth": { "type": "token", "token": "your-token-here" } } }

Docker-Specific Configuration

Running OpenClaw in Docker adds an extra layer to token management. The config file must be mounted into the container correctly, and the token must match between your host config and what the container sees.

You can set the token in two places. The config file (gateway.auth.token in openclaw.json) has lower priority. The environment variable (OPENCLAW_GATEWAY_TOKEN) has higher priority and overrides the config. The CLI flag (--token on gateway run) has the highest priority as a runtime override.

Best practice for Docker: Set the token in openclaw.json (mounted volume) and use the environment variable only as an override for temporary testing. This avoids the common Docker gotcha where a config volume mount doesn't contain the env var's value.

A frequent issue reported on Reddit: users set a token in the environment variable AND in the mounted config file, but they're different values. The gateway uses the environment variable (higher priority), but the user is entering the config file token in the web UI. Result: "invalid token" errors that seem impossible. Fix: Use one token source. Pick either the config file or the environment variable, not both.

# docker-compose.yml
version: "3.8"
services:
  openclaw:
    image: openclawai/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw-config:/home/node/.openclaw
      - ./workspace:/home/node/clawd
    environment:
      - OPENCLAW_GATEWAY_TOKEN=a1b2c3d4-e5f6-7890-abcd-ef1234567890
    restart: unless-stopped

# Verify Docker token configuration
docker exec openclaw cat /home/node/.openclaw/openclaw.json | grep -A3 auth
docker exec openclaw env | grep OPENCLAW_GATEWAY
docker exec openclaw openclaw gateway health

VPS and Remote Access Configuration

When running OpenClaw on a VPS (Contabo, Hetzner, DigitalOcean, etc.), you need additional configuration beyond just the token to enable remote access.

By default, OpenClaw enforces device-identity pairing for web UI connections. This is great for local installs but makes remote access impossible without pairing first. Setting allowInsecureAuth: true tells the gateway to accept any client that provides the correct token, without device pairing.

Is this safe? Yes — as long as your token is strong (32+ random characters), you use HTTPS (Caddy, Nginx, or Tailscale), and you don't expose port 18789 directly to the internet without a firewall.

Note: trustedProxies must be an exact IP — CIDR ranges like 172.17.0.0/16 are not supported.

// ~/.openclaw/openclaw.json — complete remote access config
{
  "gateway": {
    "mode": "remote",
    "port": 18789,
    "bind": "lan",
    "auth": {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

# Securing remote access with Caddy (auto HTTPS)
# Caddyfile:
# openclaw.yourdomain.com {
#     reverse_proxy localhost:18789
# }
sudo apt install -y caddy
sudo systemctl start caddy

Using the Token with the Chrome Browser Relay

The OpenClaw Browser Relay Chrome extension lets your AI agent control a browser tab. It connects to your gateway using the same token.

Setup steps: Install the OpenClaw Browser Relay from the Chrome Web Store, click the extension icon and go to Settings, enter your gateway URL (ws://your-server-ip:18789 or wss:// for HTTPS), paste your gateway token in the Token field, and click Connect.

Common relay issues include: "relay not reachable" (verify gateway URL and port are accessible), "not authenticated" (clear and re-paste the token, watch for invisible whitespace), works in Web UI but not relay (ensure both point to the exact same gateway address), and connection drops repeatedly (check server firewall allows WebSocket upgrades).

Pro tip: When pasting the token, use Ctrl+A to select all in the token field first, then paste. This prevents accidental concatenation with leftover text.

Token Rotation: How to Change Your Token Safely

If your token may have been exposed — leaked in a screenshot, committed to git, shared in a support ticket — rotate it immediately.

The old token is invalidated instantly on restart. Any active connections using the old token are disconnected immediately. After rotation, update ALL clients immediately: Web UI (re-enter token on next login), Chrome extension (update token in settings), iOS app (re-pair with new token), and any API integrations (update token in code).

For high-security deployments, automate rotation on a schedule using the script below.

# Step-by-step token rotation
NEW_TOKEN=$(uuidgen)
echo "New token: $NEW_TOKEN"
openclaw config set gateway.auth.token "$NEW_TOKEN"
openclaw gateway restart
# Or for Docker: docker restart openclaw

#!/bin/bash
# rotate-gateway-token.sh — automated rotation script
NEW_TOKEN=$(openssl rand -hex 32)
openclaw config set gateway.auth.token "$NEW_TOKEN"
openclaw gateway restart

echo "OpenClaw gateway token rotated at $(date). New token: $NEW_TOKEN" | \
  mail -s "OpenClaw Token Rotation" [email protected]

SecretRef: Advanced Token Management

For production deployments, OpenClaw supports SecretRef — storing your token in environment variables or files instead of plaintext in openclaw.json.

Why use SecretRef? No plaintext secrets in config (safer for version control), Docker secrets compatible (mount as /run/secrets/gateway-token), environment-variable injection (works with CI/CD pipelines, Kubernetes, Railway), and service install compatibility (gateway install validates that the SecretRef resolves but doesn't persist the resolved value).

If the SecretRef can't be resolved (missing env var, missing file), the gateway fails closed — it refuses to start rather than falling back to no auth. This is a security feature, not a bug. Check openclaw doctor for resolution failures.

// SecretRef from environment variable
{
  "gateway": {
    "auth": {
      "token": { "$env": "OPENCLAW_GATEWAY_TOKEN" }
    }
  }
}

// SecretRef from file
{
  "gateway": {
    "auth": {
      "token": { "$file": "/run/secrets/gateway-token" }
    }
  }
}

Complete Troubleshooting Guide

Error: "invalid token" or "authentication failed" — The token you're presenting doesn't match what the gateway expects. Check what the gateway has in the config file, check for environment variable overrides, and for Docker check inside the container. Common culprits: trailing newline, invisible Unicode characters, copying from a chat message that added formatting.

Error: "pairing required" (WebSocket close 1008) — allowInsecureAuth is not enabled for remote connections. Add controlUi.allowInsecureAuth: true to your gateway config and restart.

Error: "device token mismatch" — The gateway was paired with a different device identity. This happens when you reinstall the browser, clear cookies, or connect from a new machine. Fix: Re-enter the correct gateway token from your config file.

Gateway refuses to start — Invalid JSON in openclaw.json, usually a missing comma, extra bracket, or the wrong auth structure. Run openclaw doctor to diagnose, or openclaw doctor --fix to auto-fix common issues.

Token works locally but not remotely — Check this: Is the gateway bound to 0.0.0.0 (not just 127.0.0.1)? Set gateway.bind to "lan". Is the firewall allowing port 18789? Run sudo ufw allow 18789/tcp. Is allowInsecureAuth enabled? Are you using the correct protocol (ws:// for HTTP, wss:// for HTTPS)?

Railway / Render / Cloud platform issues — Cloud platforms sometimes don't reload environment variables without a full redeploy (not just a restart). If you changed OPENCLAW_GATEWAY_TOKEN, trigger a full redeploy.

# Debugging "invalid token" errors
cat ~/.openclaw/openclaw.json | python3 -m json.tool | grep -A2 token
echo $OPENCLAW_GATEWAY_TOKEN

# For Docker
docker exec openclaw cat /home/node/.openclaw/openclaw.json | grep -A2 token
docker exec openclaw env | grep OPENCLAW_GATEWAY

# Validate config
openclaw doctor
openclaw doctor --fix
python3 -m json.tool < ~/.openclaw/openclaw.json

Security Best Practices Checklist

Here's a quick-reference checklist for production-grade gateway token security.

• Token length: 32+ random characters (UUID or openssl rand -hex 32)
• HTTPS: Use Caddy, Nginx, or Tailscale — never send tokens over plain HTTP remotely
• No plaintext in git: Use SecretRef ($env or $file) for version-controlled configs
• Firewall: Restrict port 18789 to known IPs or use Tailscale
• Single token source: Don't set the token in both env var and config file with different values
• Rotation plan: Rotate tokens if exposed, or quarterly for high-security setups
• Backup your token: Store it in a password manager — losing it means reconfiguring all clients
• Monitor access: Check gateway logs for failed auth attempts (openclaw gateway call logs.tail)
• Separate credentials: Gateway token ≠ API model key ≠ channel bot token

Using the OpenClaw CLI for Token Management

The CLI provides several helpful commands for token-related operations.

When you install OpenClaw as a system service (openclaw gateway install), the CLI stores auth metadata. If you later change the token in the config but don't reinstall the service, the CLI detects this "auth drift" and warns you. Fix: Run openclaw gateway install --force to sync the service with the current config.

# Generate a new token
openclaw doctor --generate-gateway-token

# View current config
openclaw config get gateway.auth

# Set token via CLI
openclaw config set gateway.auth.token "new-token-here"

# Test gateway connectivity
openclaw gateway health --token "your-token"

# Full diagnostic probe
openclaw gateway probe --json

# Check service status including auth drift
openclaw gateway status --require-rpc

Managed Hosting: Skip the Token Hassle

If configuring JSON files and debugging token mismatches isn't your idea of a good time, managed OpenClaw hosting handles all of this automatically.

DoneClaw (doneclaw.com) auto-generates tokens on deploy, visible in your dashboard with one-click copy. No JSON editing required. HTTPS and auth configured out of the box. Hostinger VPS with OpenClaw makes the token available in the Docker Manager panel under Projects. OpenClaw Launch offers a visual configurator with token rotation from the dashboard.

For self-hosters who want full control but less hassle, the openclaw onboard wizard handles token generation as part of the interactive setup flow.

Conclusion

The OpenClaw gateway token is simple in concept — a shared secret that authenticates access to your AI agent — but the details matter. Get the JSON structure right, use a cryptographically random token of at least 32 characters, stick to one token source (config file or environment variable, not both), enable allowInsecureAuth for remote access, and use HTTPS in production. If you hit authentication errors, the troubleshooting section above covers every common scenario. For the easiest path, managed hosting like DoneClaw handles token generation, HTTPS, and auth configuration automatically — so you can focus on building with your AI agent instead of debugging JSON brackets.

Frequently asked questions