How to Pair OpenClaw with Telegram

What Is OpenClaw Telegram Pairing?

OpenClaw Telegram pairing is the process of authorizing a Telegram user to chat with your OpenClaw AI agent. When dmPolicy is set to “pairing”, OpenClaw's gateway issues a one-time pairing code the first time a user messages your bot. The user enters that code in the OpenClaw gateway web UI to prove they're authorized — after that, messages flow freely between Telegram and the AI.

dmPolicy: “pairing” is the secure default for Telegram and the only recommended setting. Unlike “open” — which allows anyone on the internet who finds your bot to use it — pairing ensures only people you explicitly approve can interact with your AI agent.

How Telegram Pairing Works

The pairing flow happens automatically once your bot is configured and running:

1. A user opens your Telegram bot and sends any message (or /start).
2. OpenClaw's gateway detects the new user and replies with a short pairing code — a random alphanumeric string like A3X9.
3. The user copies that code and navigates to your OpenClaw gateway web UI (the control panel URL shown on your dashboard).
4. In the gateway UI, the user finds the DM Pairing section and enters the code.
5. Once submitted, the device is paired. All subsequent messages from that Telegram user are routed directly to the AI agent and replied to in real time.

Each Telegram user must pair separately. Pairing is per-device — if a user switches accounts they will need to pair again. There is no expiry on a successful pairing unless you reset credentials manually.

Step 1: Set Up Your Telegram Bot

Before pairing, you need a Telegram bot token. Get one from @BotFather — Telegram's official bot creation tool:

1. Open Telegram and search for @BotFather, then start a chat.
2. Send /newbot. BotFather will ask for a display name, then a unique username (must end in bot, e.g., my_openclaw_bot).
3. BotFather replies with your bot token — a string like 7123456789:AAFkL2.... Copy it somewhere safe.
4. In your OpenClaw config, paste the token under channels.telegram.botToken.

Step 2: Configure dmPolicy to Pairing

With your bot token in your config, set the DM policy. In openclaw.json, your Telegram channel config should look like this:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

Two fields are critical here. First, channels.telegram.dmPolicy must be “pairing”. Second, plugins.entries.telegram.enabled must also be true — the channel config alone is not enough; the plugin must be explicitly enabled or you will see a “plugin not available” error.

Step 3: Start the Gateway and Pair

With your config ready, start the OpenClaw gateway and complete the pairing flow:

1. Start your OpenClaw instance. If using OpenClaw Launch, click Deploy from the configurator. If self-hosting, run docker run with your config mounted.
2. Open the gateway web UI. On OpenClaw Launch this is accessible from your Dashboard page. If self-hosting, the gateway UI runs on the port you configured (default 3000).
3. DM your bot on Telegram. Send any message — even just /start. The bot replies automatically with a pairing code.
4. Enter the pairing code in the gateway web UI under the DM Pairing section, then click Approve.
5. Test the connection. Send another message to your bot on Telegram. It should now respond with AI replies instead of another pairing code.

Common Pairing Errors and Fixes

“Plugin Not Available” Error

This error means the Telegram plugin is not loaded. It happens when channels.telegram.enabled: true is set but plugins.entries.telegram.enabled: true is missing. Both must be present. OpenClaw Launch sets both automatically — if you're self-hosting, double-check your openclaw.json.

Credentials Directory Missing

If pairing seems to succeed but the bot never responds to follow-up messages, the credentials directory may be missing. OpenClaw stores pairing state in ~/.openclaw/credentials/ inside the container. Without this directory, the Telegram plugin silently drops all messages after the initial pairing exchange.

On OpenClaw Launch this is handled automatically. If self-hosting with Docker, make sure you mount a persistent volume at /home/node/.openclaw/credentials/ so pairing state survives container restarts.

“Disconnected 1008” / Gateway Not Reachable

A 1008 disconnect usually means the gateway WebSocket connection dropped. This can happen if the gateway URL is wrong, the container restarted, or the port is not exposed. See the OpenClaw gateway pairing fix guide for a detailed walkthrough of gateway connection errors.

Pairing Code Not Appearing

If the bot doesn't reply with a pairing code when you message it, check these:

• Verify channels.telegram.botToken is correct and not expired. Regenerating a token in BotFather invalidates the old one immediately.
• Confirm the container is running — check your Dashboard page for instance status.
• Make sure dmPolicy is set to “pairing”. If it is unset or missing, some OpenClaw versions default to a different behavior.

Pairing Code Expired

Pairing codes are single-use and expire after a short window. If you wait too long to enter the code in the gateway UI, message the bot again to receive a fresh code.

Skip Pairing with OpenClaw Launch

Setting up pairing manually — mounting credential volumes, editing JSON configs, managing container restarts — takes time and leaves room for mistakes. OpenClaw Launch handles all of it automatically:

• Pairing is configured out of the box. dmPolicy: “pairing” is the default. You never need to touch openclaw.json.
• Credential storage is persistent. Pairing state survives container restarts and upgrades automatically.
• Both plugin flags are set correctly. channels.telegram.enabled and plugins.entries.telegram.enabled are both true from the first deploy.
• Deploy in 10 seconds. Paste your BotFather token, click Deploy, then DM your bot to pair — the whole process takes under a minute.

What's Next?

• OpenClaw Telegram bot guide — Full setup walkthrough including BotFather, model selection, and group chat
• Gateway pairing fix — Fix WebSocket disconnects and gateway connection errors
• Self-hosting guide — Run OpenClaw on your own VPS with Docker
• Compare AI models — Pick the right model for your Telegram bot