OpenClaw 'Gateway Connect Pairing Required' — What It Means and How to Fix It

You'll see "Gateway Connect Pairing Required" when OpenClaw's gateway is running but isn't connected to a channel yet. This guide explains what's happening and how to fix it.

If you deployed via ClawCloud, the wizard handles pairing automatically. If you're still seeing this message after deployment, skip to Troubleshooting below.

What "Gateway Connect Pairing Required" means

OpenClaw runs a gateway process that connects to your messaging channel (Telegram, Discord, or WhatsApp) using a bot token. "Pairing required" means the gateway started successfully but hasn't completed that channel handshake yet.

Two situations cause this:

1. First setup — the bot token hasn't been provided to the gateway yet
2. Lost connection — the bot was disconnected (token revoked, bot deleted, or permissions removed) and the gateway is waiting to be re-linked

The bot exists on your server and the AI model is configured, but no messages can flow until the channel link is established.

How to fix it

For Telegram

Step 1: Confirm your bot token is valid.

Open Telegram BotFather and verify the bot still exists. If you deleted the bot or the token was revoked, you'll need to create a new one and update your config.

Step 2: Check the token in your config.

On a self-hosted instance, open ~/.openclaw/openclaw.json and confirm the Telegram bot token under channels.telegram.token is present and correct.

Step 3: Restart the gateway.

After correcting the token, restart the OpenClaw gateway with systemctl --user restart openclaw-gateway. Check OpenClaw docs for the exact service name on your setup.

For Discord

Step 1: Verify the bot is still in your server.

Go to the Discord Developer Portal, open your application, and check that the bot is still active. If the token was reset, generate a new one.

Step 2: Re-invite the bot if needed.

If the bot was kicked from your server, use the OAuth2 URL generator in the Discord Developer Portal to generate a new invite link and re-add it.

Step 3: Update the token in your config.

If you regenerated the Discord bot token, update it in ~/.openclaw/openclaw.json under channels.discord.token. Then restart the gateway.

How to set up OpenClaw pairing from scratch

If you haven't completed initial setup yet:

1. Create your bot on Telegram BotFather or the Discord Developer Portal
2. Copy the bot token
3. Run openclaw onboard and paste the token when prompted
4. The gateway will complete the channel handshake automatically

Or skip all of this: the ClawCloud deploy wizard handles bot creation guidance, token input, and pairing in a single flow. Your bot is live in under a minute.

Troubleshooting

Message still shows after token is correct

The gateway may not have picked up the config change. Restart it with systemctl --user restart openclaw-gateway. If you're running as the openclaw user, make sure XDG_RUNTIME_DIR is set correctly — see OpenClaw docs for environment details.

Pairing succeeds but bot still doesn't respond

Check DM policy. OpenClaw defaults to pairing mode, which requires manual approval. You need dmPolicy: "open" and allowFrom: ["*"] in the channel config to allow anyone to message the bot. See the guide on unlocking DM access.

Bot was deployed via ClawCloud but shows this error

This shouldn't happen on a fresh ClawCloud deployment — pairing is automatic. If it does appear, contact help@clawcloud.sh with your instance name.