OpenClaw LaunchOpenClaw Launch
← Home

Setup Guide

OpenClaw Gateway Token Setup

The OpenClaw gateway token (openclaw_gateway_token) is the authentication key that protects your OpenClaw instance. This guide covers how to generate a secure token, configure it correctly, and troubleshoot common token-related errors.

What Is the OpenClaw Gateway Token?

The OpenClaw gateway token is a secret string that authenticates all connections to your OpenClaw gateway — whether from the web UI, the browser relay Chrome extension, or API integrations. Without a valid token, no one can access your OpenClaw instance.

You may see it referenced as openclaw_gateway_token, gateway.auth.token, or simply “gateway token” in various OpenClaw documentation and community discussions. They all refer to the same thing: the authentication token in your openclaw.json configuration file.

How to Generate a Secure Token

Your gateway token should be a long, random string that cannot be guessed. Here are several ways to generate one:

Option 1: UUID (Recommended)

# Python
python3 -c "import uuid; print(uuid.uuid4())"
# Output: a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Node.js
node -e "console.log(require('crypto').randomUUID())"

# Linux/macOS
uuidgen

Option 2: Random String

# 32-character random hex string
openssl rand -hex 16

# 48-character base64 string
openssl rand -base64 36
Security tip: Never use simple passwords like “password123” or “admin” as your gateway token. Anyone who knows your token has full access to your AI agent. Use a UUID or random string of 32+ characters.

How to Configure the Token

The gateway token goes in your openclaw.json configuration file, usually located at ~/.openclaw/openclaw.json. Here is the correct format:

{
  "gateway": {
    "auth": {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

Critical: The Token Must Be Inside an Object

This is the most common mistake users make when configuring the OpenClaw gateway token. The auth field must be an object containing a token property:

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

// WRONG - auth as a plain string (WILL NOT WORK)
{
  "gateway": {
    "auth": "your-token-here"
  }
}

// WRONG - auth with type "none" (WILL NOT WORK)
{
  "gateway": {
    "auth": {
      "type": "none"
    }
  }
}

// WRONG - auth as string "none" (WILL NOT WORK)
{
  "gateway": {
    "auth": "none"
  }
}

If you use any of the “WRONG” formats above, the gateway will reject all connections. This is one of the most frequently reported issues in the OpenClaw community.

Where to Use the Token

Once configured, you need to enter the gateway token in several places depending on how you access your OpenClaw instance:

  • Gateway Web UI — When you open the OpenClaw web interface in your browser, you'll be prompted for the token. Paste it exactly as configured.
  • Browser Relay Chrome Extension — The extension has a “Token” field where you paste your gateway token to authenticate the relay connection.
  • API Integrations — If connecting to the gateway programmatically, include the token in the WebSocket handshake.

Complete Gateway Configuration

For remote access (VPS, cloud server, Docker), you need both the token and allowInsecureAuth to bypass device pairing:

{
  "gateway": {
    "port": 18789,
    "controlUi": {
      "allowInsecureAuth": true
    },
    "auth": {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "trustedProxies": ["172.17.0.1"]
  }
}

allowInsecureAuth: true disables device-identity pairing so you can connect from any device with the correct token. This is safe when combined with HTTPS. See our gateway pairing guide for details.

trustedProxies is needed only if you use a reverse proxy (Caddy, Nginx). It must be the exact IP of your proxy — CIDR ranges like 172.17.0.0/16 are not supported.

Troubleshooting Token Issues

Error: “invalid token” or “authentication failed”

  • Double-check the token in your config file: cat ~/.openclaw/openclaw.json | grep -A2 auth
  • Make sure you restarted OpenClaw after changing the config: docker restart openclaw
  • Verify the config is mounted correctly in Docker: docker exec openclaw cat /home/node/.openclaw/openclaw.json
  • Check for invisible characters — copy the token from the config file, not from memory or a chat message

Error: “relay not reachable/authenticated”

This error in the Chrome extension usually means a token mismatch or network issue. See our relay not reachable troubleshooting guide for step-by-step fixes.

Error: “pairing required”

This means allowInsecureAuth is not enabled. The gateway requires device pairing for remote connections. Add "controlUi": { "allowInsecureAuth": true } to your gateway config. See our pairing required troubleshooting guide.

Token Works in Web UI but Not in Chrome Extension

If you can log in to the gateway web UI with the token but the Chrome extension shows “not authenticated,” the most likely causes are:

  • Extra whitespace or newline in the extension's token field — clear and re-paste the token
  • The extension is connecting to a different URL than the web UI — make sure both use the exact same gateway URL
  • Browser extension needs updating — check the Chrome Web Store for updates

How to Rotate (Change) the Gateway Token

If your token may have been exposed, rotate it immediately:

  1. Generate a new token using one of the methods above
  2. Update openclaw.json with the new token
  3. Restart OpenClaw: docker restart openclaw
  4. Update the token in all clients (web UI, Chrome extension, API integrations)

The old token is invalidated immediately on restart. Any clients still using the old token will be disconnected.

Skip the Token Hassle: Use OpenClaw Launch

Managing gateway tokens, JSON config files, and authentication settings is one of the most error-prone parts of self-hosting OpenClaw. OpenClaw Launch handles all of this automatically:

  • Secure gateway token auto-generated on deploy
  • Token displayed in your Dashboard — one click to copy
  • No JSON config editing — visual configurator
  • HTTPS and authentication handled automatically
  • Token rotation available from the Dashboard

Deploy your AI agent in 30 seconds and connect the browser relay without worrying about token format, config files, or authentication errors.

Frequently Asked Questions

What is openclaw_gateway_token?

openclaw_gateway_token is the authentication key used to secure your OpenClaw gateway. It is configured in the openclaw.json file under gateway.auth.token. All connections to the gateway (web UI, browser relay, API) must present this token to authenticate.

Where do I find my OpenClaw gateway token?

The gateway token is stored in your OpenClaw config file, typically at ~/.openclaw/openclaw.json. For Docker deployments, check inside the container: docker exec openclaw cat /home/node/.openclaw/openclaw.json. On OpenClaw Launch, the token is visible in your Dashboard.

How do I change the OpenClaw gateway token format?

The gateway token must always be configured as an object: "auth": { "token": "your-token" }. Never pass it as a plain string ("auth": "your-token"). This is the most common configuration mistake and will cause all connections to fail.

Is the OpenClaw gateway token the same as an API key?

No. The gateway token authenticates access to the OpenClaw gateway web UI and browser relay. Your AI model API key (e.g., OpenRouter API key) is a separate credential configured under models.providers in the config file. They serve different purposes and should be different values.

Related Guides

No Config Files Needed

OpenClaw Launch auto-generates secure tokens and handles authentication. Deploy in 30 seconds.

Deploy with OpenClaw Launch