Fix OpenClaw Telegram Pairing and Approval Errors

Key takeaways

• OpenClaw requires explicit approval for every Telegram chat before your agent responds. This applies to DMs, groups, and channels.
• Run openclaw pairing pending to see waiting requests, then openclaw pairing approve telegram CHAT_ID to approve.
• Set autoApprove: true with an allowFrom list to skip manual approval for your own user ID. Do not enable this without an allowlist.
• If a pairing request doesn't appear, remove and re-add the bot to the group to trigger a fresh request.

Your OpenClaw Telegram bot connects successfully but refuses to respond. The logs show "pairing pending" or "pairing required" instead of processing the message. OpenClaw's pairing system requires you to explicitly approve every chat before the agent interacts with it.

What OpenClaw Telegram pairing does

OpenClaw tracks every chat (DM, group, channel) and requires approval before your agent responds. This is a security feature. If someone adds your bot to a random group, the agent doesn't start responding to strangers without your permission.

The first time someone messages the bot or adds it to a group, OpenClaw creates a pending pairing request. Until you approve it, the bot drops all messages from that chat silently.

This applies to:

• Direct messages from new users
• Group chats the bot is added to
• Channels where the bot is an admin

How to approve OpenClaw Telegram pairing requests

List all pending requests:

openclaw pairing pending

Output looks like:

Pending pairings:
- telegram:-1001234567890 (Group: Project Team)
- telegram:987654321 (User: @alice)

Approve each one:

openclaw pairing approve telegram -1001234567890
openclaw pairing approve telegram 987654321

After approval, the bot responds immediately in that chat. No restart needed.

Check all approved pairings:

openclaw pairing list

OpenClaw Telegram auto-approve for trusted users

If you are the only user and want to skip manual approval every time, configure autoApprove with your allowFrom list:

{
  "channels": {
    "telegram": {
      "accounts": {
        "default": {
          "allowFrom": ["123456789"],
          "autoApprove": true
        }
      }
    }
  }
}

Now pairing requests from your user ID are approved automatically. The bot responds without waiting for manual approval.

Use this carefully. Do not enable autoApprove without an allowFrom list. Without allowFrom, auto-approve accepts pairing requests from anyone, including strangers who add your bot to their groups. The security hardening playbook explains why open pairing is a security risk.

After changing the config:

openclaw gateway restart

Reject unwanted OpenClaw Telegram pairings

If someone adds your bot to a group you don't want it in:

openclaw pairing reject telegram -1001234567890

The bot ignores all messages from that chat going forward. If the bot is removed from the group and added again, a new pairing request is created. You'd need to reject it again.

Troubleshoot OpenClaw Telegram pairing issues

No pairing request appears

If you've added the bot to a group but don't see a pending request:

1. Check that the bot token is correct and the gateway is running (openclaw gateway status)
2. Remove the bot from the group and add it again. This triggers a fresh pairing request.
3. Check the logs for any errors during the add:

openclaw logs --follow

Add the bot while watching. You should see a pairing request line within seconds.

Pairing approved but bot still silent

If you've approved the pairing and the bot still doesn't respond:

1. Check that the chat ID you approved matches the one in the logs. Group IDs change when a group upgrades to a supergroup.
2. Check requireMention settings. In groups, the bot may only respond when it's @mentioned. See the bot not responding guide.
3. Verify allowFrom includes your user ID if configured. See the allowFrom guide.

Pairing keeps resetting

If you approve a pairing and it reverts to pending, check:

1. Gateway restarts: Some configurations reset pairings on restart. Check if ~/.openclaw/data/pairings.json persists between restarts. In Docker, make sure this path is in a mounted volume. See the Docker setup guide.
2. Multiple instances: If two OpenClaw instances share the same data directory, they may overwrite each other's pairings.

DM pairing vs group pairing

DMs and groups have separate pairings. Approving your DM doesn't approve any groups, and vice versa. If the bot works in DMs but not in a group (or the reverse), you'll need a separate approval for each chat.

FAQ

How do I remove an approved OpenClaw Telegram pairing?

OpenClaw doesn't have a dedicated unpair command. Edit ~/.openclaw/data/pairings.json directly and delete the entry for that chat ID. Restart the gateway with openclaw gateway restart after editing.

Does approving an OpenClaw group pairing let everyone in the Telegram group use the bot?

Yes. Group pairing approval means the OpenClaw bot responds to messages in that group. Individual user access within the group is controlled by allowFrom and requireMention settings, not by per-user pairing. See the allowFrom guide for user-level access control.

Can I approve OpenClaw Telegram pairings from Telegram instead of the terminal?

Not by default. OpenClaw's pairing commands (openclaw pairing pending, openclaw pairing approve) run in the terminal via SSH. Some custom setups route pairing notifications to a Telegram admin chat, but this requires additional configuration.

I approved an OpenClaw pairing but the Telegram chat ID changed. What happened?

The Telegram group likely upgraded to a supergroup, which permanently changes the chat ID from -123456789 to -1001234567890. Check for a new pending pairing request with the updated ID using openclaw pairing pending. See the group ID guide for details.

Changelog

• 2026-03-06: Created (split from fix-openclaw-telegram-errors)