# OpenClaw Gateway: Setup, Token Configuration and Essential Commands 31 March 2026 10 min read .webp) ## 🎯 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](/content/site-root.html) 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```json { "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. ```bash 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: | Command | What It Does | |----------------------------------|----------------------------------------------------------------------------------------------------------| | `openclaw gateway start` | Launches the Gateway on the default port (18789). Add `--port` to override. | | `openclaw gateway restart` | Stops the running Gateway process and starts a fresh one. Config changes take effect after restart. | | `openclaw gateway stop` | Shuts down the Gateway. All active client connections are terminated immediately. | | `openclaw gateway status` | Prints current state: running/stopped, port, uptime, connected clients, and token validity. | | `openclaw gateway logs` | Tails the Gateway log file in real time. Add `--lines 100` to control output length. | 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](/content/site-root.html), 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: ```bash lsof -i :18789 ``` If you see a stale `openclaw` process, kill it manually: ```bash kill -9 ``` 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](https://github.com/AtomicBot-ai/atomicbot/releases/download/v1.0.82/Atomic.Bot-1.0.82-arm64.dmg) - [Get Atomic Bot for Windows](https://github.com/AtomicBot-ai/atomicbot/releases/download/v1.0.82/Atomic-Bot-1.0.82-x64-win.exe) ## ❓ 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? Yes. 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.