OpenClaw Telegram Setup

All Telegram-specific settings live in your `openclaw.json` file under the `channels.telegram` key. Here's a full configuration example with all available options:

`{ "channels": { "telegram": { "token": "YOUR_BOT_TOKEN", "dmPolicy": "pairing", "streaming": true, "webhookUrl": "https://yourdomain.com/webhook", "groups": [ { "id": "-1001234567890", "mentionOnly": true } ] } } }`

Each field controls a distinct aspect of how OpenClaw interacts with Telegram. Understanding what each does lets you tune the behavior for your specific needs - whether that's a private single-user assistant, a family bot, or a team workspace.

The configuration file uses standard JSON. Syntax errors (missing commas, unclosed braces) will prevent OpenClaw from starting, and error messages won't always point directly to the problem line. A JSON linter like `python3 -m json.tool openclaw.json` can validate the file before you restart the service.

Changes to openclaw.json take effect after restarting OpenClaw. On systemd: `systemctl restart openclaw`. The service reads the configuration file once at startup, so you need a full restart for changes to apply - not just a signal or a SIGHUP.

The `dmPolicy` setting is the most security-critical configuration option in the Telegram block. It controls which Telegram users can send direct messages to your OpenClaw bot and receive responses.

`"pairing"` (recommended): Only Telegram accounts that have completed the pairing handshake can interact with your bot. Pairing is a one-time process where you initiate contact with your bot and confirm ownership. After pairing, your Telegram account is added to an authorized list. Anyone else who messages your bot receives no response - not an error message, just silence. This prevents accidental or intentional misuse of your assistant by anyone who discovers your bot's username.

`"open"`: Any Telegram user can message your bot and receive responses. This is useful if you're building a public-facing tool intentionally, but it's a serious security risk for a private AI assistant. Open mode means anyone can use your AI credits, interact with your assistant, and potentially extract information from your memory context through clever questioning.

`"allowlist"`: A middle ground - specify a list of Telegram user IDs that are allowed without going through the pairing process. Useful for teams where you want multiple people to have access without each doing a formal pairing. Add user IDs under an `allowedUsers` array in the telegram config.

If you've accidentally set dmPolicy to open and your bot has been publicly accessible, rotate your bot token via BotFather immediately, then fix the configuration before generating a new token.

OpenClaw supports two ways to receive messages from Telegram: webhooks (push) and polling (pull). The right choice depends on your server environment.

Webhooks are the correct choice for any server with a public IP and domain. Telegram's API pushes new messages to your registered webhook URL the instant they arrive. Latency is typically under 1 second. No repeated API calls when nothing is happening. The webhook requires HTTPS with a valid certificate - self-signed certificates are rejected by Telegram's servers. To register a webhook, make a GET request to `https://api.telegram.org/botTOKEN/setWebhook?url=https://yourdomain.com/webhook`.

Polling works without a public domain. OpenClaw repeatedly calls Telegram's `getUpdates` API to check for new messages. The poll interval is configurable - shorter intervals mean faster message delivery but more API calls. The default is typically 5-10 seconds. Polling works fine on local machines, behind NAT, or on servers without domain names. It's less efficient but more universally compatible.

Configure webhook mode by setting `webhookUrl` in your config. If no webhookUrl is set, OpenClaw defaults to polling. You can also explicitly set the mode: `"mode": "webhook"` or `"mode": "polling"`.

For cloud-hosted instances like PlugAndClaw, webhooks are always used. The server has a public IP, Caddy provides HTTPS, and webhook registration happens automatically during provisioning. The result is sub-second message delivery without any ongoing API polling overhead.

The `streaming` setting controls whether your assistant's responses appear word-by-word in Telegram or all at once when generation is complete.

With `"streaming": true`, OpenClaw sends an initial message as soon as generation starts, then repeatedly edits that message as new tokens arrive. You see words appearing in real time, similar to how Claude.ai and ChatGPT display responses in their web interfaces. For long responses, this makes the interaction feel dramatically more responsive - you're reading while the assistant is still writing rather than staring at a loading state.

With `"streaming": false`, OpenClaw waits for the complete response before sending a single Telegram message. This works better in some edge cases - if you're processing the response programmatically, or if you're in a group where partial responses would be distracting. The downside is that for responses that take 10-30 seconds to generate, you get no feedback during that time.

Streaming requires that Telegram message editing works correctly for your bot. It does in standard DM conversations. In some broadcast channels or specific group configurations, message editing may be restricted, in which case you should set streaming to false.

The streaming setting can be overridden per-conversation by telling your assistant: 'Turn off streaming for this session.' Your assistant writes this preference to your session context and adjusts accordingly.

PlugAndClaw enables streaming by default. If you prefer the all-at-once delivery, you can change the setting via SSH access to your server or ask your assistant to toggle it.

OpenClaw can participate in Telegram group chats in addition to direct messages. Group configuration lives in the `groups` array in your Telegram config.

Each group entry needs the group's chat ID (a negative number like `-1001234567890`) and behavior settings. To find a group's chat ID: add your bot to the group, send a message, then call `https://api.telegram.org/botTOKEN/getUpdates` and look for the `chat.id` in the response.

`mentionOnly: true` makes your assistant respond only when explicitly @mentioned in the group. This is polite behavior for groups where the bot isn't the primary focus - it won't interject into every conversation, just the ones directed at it.

`mentionOnly: false` makes your assistant respond to every message in the group. Useful for dedicated AI workspace groups where all messages are intended for the assistant, but disruptive in general-purpose group chats.

Group behavior can also be modified via your AGENTS.md file. Adding instructions like 'In group chats, be concise and stay on topic. Don't respond to casual conversation unless directly addressed.' tunes how your assistant participates without changing the raw config.

For teams using PlugAndClaw: one server instance can be added to multiple groups. Each group can have different mentionOnly settings. All group messages and DMs go to the same OpenClaw instance with the same memory and configuration - your assistant maintains context across all conversation surfaces.

None of this configuration is necessary if you're using PlugAndClaw for a single-user private assistant. The default DM-only configuration handles the vast majority of use cases. Group setup is there when you need it, preconfigured when you don't.