OpenClaw Telegram Setup

Create a Telegram Bot With BotFather

Open Telegram, start a chat with the verified @BotFather account, and use /newbot. BotFather asks for a display name and a username, then returns the bot token. Treat that token like a password: anyone who has it can call the Bot API as your bot.

For a supervised Gateway, prefer an environment variable or a secret-backed configuration instead of pasting the token into a repository. Before continuing, note your own numeric Telegram user ID. OpenClaw authorizes users by stable numeric IDs; a username can change and is not the safest long-term identity key.

Add the Telegram Channel to openclaw.json

The following JSON5 example enables Telegram and keeps unknown direct-message senders behind pairing:

{
 channels: {
 telegram: {
 enabled: true,
 botToken: "YOUR_BOT_TOKEN",
 dmPolicy: "pairing",
 groups: {
 "-1001234567890": {
 requireMention: true
 }
 }
 }
 }
}

Replace the placeholders before use. Negative IDs under groups identify Telegram groups or supergroups. Do not place a group chat ID in groupAllowFrom; that field is for the user IDs allowed to trigger the bot inside authorized groups.

Restart or reload the Gateway, then check the connection with:

openclaw channels status --probe
openclaw logs --follow

Run the /pair Command and Complete Pairing

Current OpenClaw documentation does not use a Telegram /pair command for first-time access. Instead, an unknown sender messages the bot, receives a short pairing code, and waits for the Gateway operator to approve it from the CLI:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Pairing codes expire, and pending requests are capped. If this is the first approved sender and no command owner exists, OpenClaw can also bootstrap that sender into commands.ownerAllowFrom. Later pairing approvals grant DM access but do not automatically create more command owners.

Set Up an Allowlist to Restrict Bot Access

For a one-owner bot, an explicit numeric allowlist is easier to audit than a growing pairing store:

{
 channels: {
 telegram: {
 enabled: true,
 botToken: "YOUR_BOT_TOKEN",
 dmPolicy: "allowlist",
 allowFrom: ["123456789"],
 groupPolicy: "allowlist",
 groups: {
 "-1001234567890": {
 requireMention: true,
 allowFrom: ["123456789"]
 }
 }
 }
 }
}

An empty allowFrom with dmPolicy: "allowlist" blocks all DMs and fails validation. Setting dmPolicy: "open" is also not enough by itself: public access requires an explicit wildcard, which should be reserved for intentionally public bots with tightly restricted tools.

Fix 'Telegram Bot Not Working After 2026.3.8'

There is no single official post-2026.3.8 Telegram failure with one universal fix. Treat the version number as a clue, then diagnose the actual layer that broke:

1. Run openclaw status --all and openclaw update status --json to confirm the active install and profile.
2. Run openclaw channels status --probe to test the bot token and transport.
3. Run openclaw doctor --fix to detect migrated or invalid allowlist entries.
4. Inspect openclaw logs --follow for pairing request, blocked, allowlist, or mention-gating messages.
5. Confirm group senders are authorized separately; newer security boundaries do not let DM pairing approvals silently authorize group messages.

If an old config used Telegram usernames in access lists, replace them with numeric IDs where possible. Also verify that the Gateway service sees the same token source as your interactive shell.

Fix 'Pairing Required' Errors on Restart

First determine whether the error concerns a Telegram sender or a Control UI/device identity. For Telegram DMs, list pending channel pairings and approve the current code. For a device error, use openclaw devices list and approve the device request instead.

Repeated Telegram pairing after every restart usually points to inconsistent state directories, different profiles, a non-persistent credentials directory, or a service running under another user. Check openclaw status for the active state path, then ensure ~/.openclaw/credentials/ survives restarts and is writable only by the intended account.

Secure Your Telegram-Exposed OpenClaw Instance

Telegram access controls reduce who can send messages; they do not limit what an approved agent can do on the host. Keep the Gateway on loopback when possible, require Gateway authentication, set session.dmScope: "per-channel-peer" if more than one person can message the bot, and restrict tool permissions for non-main sessions. Run both openclaw security audit and openclaw security audit --deep before exposing a long-running instance.

For related diagnostics, use the OpenClaw gateway error guide. For broader risk controls, continue to the OpenClaw security guide.

In Verdent

Messaging bots are useful for remote requests, while coding work still benefits from an environment designed around repositories, plans, reviews, and verification. Verdent provides an AI development workspace for that software-delivery side of the workflow; it is separate from OpenClaw and is not an Anthropic or OpenClaw feature.

Sources: OpenClaw Telegram documentation, pairing reference, channel configuration, and security guidance.