OpenClaw Gateway: Setup, Token Configuration and Essential Commands

🎯 What is OpenClaw Gateway?

The OpenClaw Gateway is a background process that acts as a bridge between your front-end interface (mobile app, Telegram bot, web UI) and the OpenClaw agent running on your machine. Without the Gateway, messages from your phone or chat app have no way to reach the agent loop — and the agent has no way to send responses back.

This guide covers everything you need to get the OpenClaw Gateway running: the default startup command, token generation for authentication, the full command reference, and fixes for the most common errors

And if you want to skip the CLI entirely, Atomic Bot handles Gateway configuration automatically — but understanding what's happening under the hood is useful either way.

🚀 OpenClaw Gateway Quick Start

The Gateway listens for incoming connections on a local port and routes them to the agent process. The default port is 18789, and the simplest way to start it is with the openclaw gateway start command:

openclaw gateway start

That single command launches the Gateway on the openclaw gateway default port 18789, binds it to localhost, and begins listening for authenticated connections. If port 18789 is already in use by another process, the Gateway will fail to start — you'll need to either free the port or specify a different one:

openclaw gateway start --port 18790

Once the Gateway is running, you should see output confirming the port and the connection status. At this point, the Gateway is ready to accept connections from Telegram, WhatsApp, or any other configured channel — provided the authentication token matches.

🔑 OpenClaw Gateway Token — How to Generate & Configure

The gateway token is the single most common source of connection failures. Every client that connects to the Gateway must present a valid token, and if that token is missing, expired, or doesn't match the one the Gateway expects, the connection gets rejected immediately. Most "pairing required" and "auth failed" errors trace back to a token problem.

Generate Token via CLI

The fastest way to create a fresh token is through the built-in doctor command. Running openclaw doctor --generate-gateway-token produces a new token and writes it directly to your config:

openclaw doctor --generate-gateway-token

The command outputs the token to your terminal and simultaneously saves it to ~/.openclaw/config.json under the gateway.token field. Copy this token — you'll need it for any client that connects to the Gateway.

If you'd prefer to generate a token without touching the config file, you can also use the openclaw gateway token command directly:

openclaw gateway token --generate

This prints the token but does not write it anywhere. You'll need to copy it and configure it manually.

Where to Find & Set the Token

There are three places where the openclaw gateway auth token lives, and all three need to agree for connections to work.

Config file. Open ~/.openclaw/config.json and look for the gateway object. The token field should contain your generated string. If it's empty or missing, the Gateway will reject every connection attempt:

{
  "gateway": {
    "port": 18789,
    "token": "your-generated-token-here"
  }
}

Environment variable. You can also set the token via OPENCLAW_GATEWAY_TOKEN in your shell profile (.zshrc, .bashrc, etc.). The environment variable overrides the config file, so if both are set and they disagree, the environment variable wins.

export OPENCLAW_GATEWAY_TOKEN="your-generated-token-here"

Control UI. If you use the OpenClaw Control UI, navigate to Settings → Gateway and paste the token there. The openclaw control UI settings gateway token field syncs with the config file, so updating it in one place updates the other. This is the easiest option if you dislike editing JSON by hand.

⚙️ Essential Gateway Commands

Every Gateway operation runs through openclaw gateway followed by a subcommand. Here's the full reference:

A typical workflow after changing configuration: run openclaw gateway restart to pick up the new settings, then openclaw gateway status to confirm everything reconnected. If something looks wrong, openclaw gateway logs will show you exactly where the connection is failing.

The openclaw gateway restart command is the one you'll use most often — any change to the token, port, or channel configuration requires a restart to take effect.

🔧 Troubleshooting Common Gateway Errors

"Pairing Required" Error

The openclaw gateway pairing required error appears when a client tries to connect to a Gateway that hasn't been paired with that specific device. This is different from a token mismatch — pairing is a one-time handshake that registers a device ID with the Gateway.

The openclaw gateway connect failed pairing required message typically means one of two things: either you're connecting from a new device that hasn't been registered, or the Gateway's pairing data was reset (which happens if you delete ~/.openclaw/gateway-state.json).

To fix the openclaw gateway pairing required issue:

1. Open the OpenClaw Control UI or check your terminal for a pairing code
2. Enter the code on the device that's trying to connect
3. The Gateway registers the device and allows future connections without re-pairing

If you're using Atomic Bot, pairing is handled automatically during initial setup — the app registers itself with the Gateway and stores the pairing state internally, so this error never surfaces.

Token Missing or Mismatch

An openclaw gateway token missing error means the Gateway started without a token configured, or the client is connecting without sending one. Check ~/.openclaw/config.json — if the gateway.token field is empty, null, or absent, generate a new token using the doctor command shown above.

An openclaw gateway token mismatch error means both sides have a token, but they don't match. This usually happens after regenerating a token on one end without updating the other. The fix is straightforward: regenerate the token, copy it to the config file (or environment variable), paste it into every client that connects, and restart the Gateway.

Quick checklist for token problems:

1. Run openclaw doctor --generate-gateway-token
2. Confirm the token appears in ~/.openclaw/config.json
3. Update the token in your mobile app / Telegram bot / Control UI
4. Run openclaw gateway restart
5. Run openclaw gateway status to verify the connection

Gateway Won't Restart

If openclaw gateway restart hangs or fails, the most common cause is a zombie process holding the port. The Gateway's stop signal didn't reach the old process, so the new one can't bind to the same port.

First, check whether something is still listening on the port:

lsof -i :18789

If you see a stale openclaw process, kill it manually:

kill -9 <PID>

Then run the openclaw gateway restart command again. If the problem recurs, check openclaw gateway logs for errors — a corrupted gateway-state.json file can also prevent clean restarts. Renaming or deleting that file and restarting usually resolves it, though you'll need to re-pair any connected devices afterward.

✅ Skip All of This with Atomic Bot

Every section above — token generation, port configuration, pairing, troubleshooting zombie processes — is something Atomic Bot handles automatically. The app launches the Gateway as a managed background service, generates and stores the token internally, handles pairing for all connected channels, and restarts the process cleanly when configuration changes. If the Gateway crashes, Atomic Bot detects it and relaunches within seconds.

For anyone who wants OpenClaw's agent capabilities without managing infrastructure, Atomic Bot packages the entire stack — Gateway included — into a native desktop app with a standard installer. Download it at atomicbot.ai and the Gateway is running before you finish reading this sentence.

• Get Atomic Bot for Mac
• Get Atomic Bot for Windows

❓ FAQ

Does the Gateway need to run constantly?

‍Yes. The Gateway is the only path between your chat apps and the OpenClaw agent. If the Gateway stops, messages from Telegram, WhatsApp, or any other channel can't reach the agent, and you won't get responses until it's running again.

Can I run the Gateway on a different machine?

‍Technically yes — you can bind it to 0.0.0.0 instead of localhost and connect from other devices on your network. But this exposes the Gateway beyond your machine, so make sure your token is strong and your network is trusted.

Does Atomic Bot use the same Gateway?Y

es. Atomic Bot runs the same OpenClaw Gateway process under the hood. The difference is that Atomic Bot manages the lifecycle (start, stop, restart, crash recovery) and configuration (token, port, pairing) automatically, so you never interact with it directly.

Why did my token stop working after an update?

‍Some OpenClaw updates regenerate the Gateway state file, which can invalidate existing tokens. After updating, regenerate your token with openclaw doctor --generate-gateway-token and update it on all connected clients.