Understanding Telegram Pairing in OpenClaw

Without pairing or an allowlist, your OpenClaw instance would execute agent tasks for random strangers. Pairing ensures that only trusted users are given a session.

The Pairing Flow

If your DM_POLICY is set to strict or pairing, a new user messaging your bot will receive a generic welcome message or a prompt asking for a pairing code.

To grant them access, you (the admin with CLI access to the OpenClaw Gateway) must generate a pairing code.

1. Generating a Code

SSH into your VPS and navigate to your OpenClaw directory. Run the CLI tool to generate a new pairing ticket:

[SUCCESS] Generated pairing code: 849-291
This code expires in 15 minutes.
Send this code to the user via a secure channel.

2. Redeeming the Code

Provide the 849-291 code to the user. They must send it to the Telegram bot as a message.

User to Bot:

/pair 849-291

If successful, the bot will reply confirming the pairing, and a secure session is established.

Code Expiry & Security

• Short-Lived: Pairing codes expire quickly (usually 15 minutes). If the user misses the window, you must generate a new one.
• Single-Use: Once a code is successfully redeemed by a Telegram user ID, it cannot be used again by anyone else.
• Session Revocation: If you need to kick a user out, you can revoke their session via the Gateway dashboard or the CLI:

When to use Pairing vs Allowlist

• Pairing is best for dynamic teams or client onboarding, where you don’t know their Telegram User ID beforehand. You generate a code on demand.
• Allowlisting is best for static setups (like your own personal bot). You hardcode your Telegram User ID into the .env file, bypassing the need to pair entirely.

If you’re setting up a bot just for yourself, skip pairing and use an Allowlist. Read the Telegram Allowlist guide for more details.