The vocabulary you need

A Telegram account operated by software rather than a person. Bots have usernames ending in bot (e.g. @YourAssistantBot). They can receive messages, send replies, join groups, and be given admin permissions. Unlike regular accounts, bots cannot initiate conversations: someone must message the bot first. OpenClaw connects to Telegram by operating as a bot: your Telegram messages go to the bot, the bot passes them to OpenClaw, OpenClaw replies, and the bot delivers the reply back.

Telegram's official bot for creating and managing other bots. You talk to BotFather inside Telegram to create your bot and get its token. The setup is conversational: BotFather asks for a name, then a username, then issues you a token. BotFather can also set your bot's description, profile picture, commands list, and privacy mode. It is itself a Telegram bot that manages all other bots. Verify the handle is exactly @BotFather with no variations: there are impersonators.

A long string of characters that authenticates your bot to the Telegram API. Looks like 123456789:ABCDefGHIjklmNOPqrsTUVwxyz: a numeric bot ID, a colon, and a random string. It is a secret: anyone who has your bot token can operate your bot and read its messages. BotFather issues it when you create the bot. Store it securely; paste it into OpenClaw's config as botToken. If it is ever compromised, regenerate it in BotFather with /revoke.

Telegram's interface for bots to send and receive messages programmatically. A set of HTTP endpoints: your bot sends requests to api.telegram.org, and Telegram responds. The Bot API handles everything from sending text to managing group memberships. OpenClaw uses the Bot API under the hood via a library called grammY. You will not interact with the Bot API directly during normal setup, but understanding that it exists explains why the bot token matters and why some Telegram settings (like privacy mode) affect what OpenClaw can see.

A Telegram setting that controls which group messages a bot receives. With privacy mode on (the default), a bot only receives messages that mention it directly or are commands. With privacy mode off, the bot receives all messages in the group. Managed in BotFather with /setprivacy. If you want OpenClaw to respond to all messages in a group without being mentioned each time, you need to disable privacy mode. After changing it, remove and re-add the bot to each group for the change to take effect.

A unique numeric identifier for any Telegram chat: a direct message, a group, or a channel. Group and channel IDs are typically large negative numbers (e.g. -1001234567890). Direct message chat IDs are the same as the user's numeric ID. You need the chat ID to configure OpenClaw's group allowlists. Find it by forwarding a message from the group to @userinfobot, or by checking OpenClaw's logs with openclaw logs --follow and reading the chat.id field when a message arrives.

A unique numeric identifier for a Telegram user account. Not the same as a username: usernames can be changed, user IDs cannot. OpenClaw's allowlists use numeric user IDs to control who can interact with the bot. Your own user ID can be found by messaging your bot and reading from.id in OpenClaw's logs, or by using getUpdates via the Bot API. The onboarding wizard accepts @username and resolves it to a numeric ID automatically.

A method by which OpenClaw repeatedly asks Telegram "any new messages?" and Telegram holds the connection open until something arrives, then responds. OpenClaw immediately asks again. The result is near-real-time message delivery without requiring a public URL. Long polling is OpenClaw's default mode for Telegram. It is simpler to set up than webhooks because it works behind a firewall, does not need a domain name or TLS certificate, and requires no inbound ports to be open.

An alternative delivery method where Telegram pushes messages to a URL you specify, rather than OpenClaw pulling them. Requires a publicly reachable HTTPS endpoint: a domain name pointing to your server, with a valid TLS certificate. Webhooks are slightly more efficient at scale but significantly more complex to set up. For most personal OpenClaw setups, long polling is the right choice. Webhooks become relevant if you are running OpenClaw on a server with a public IP and want to reduce load.

The JavaScript/TypeScript library that OpenClaw uses internally to talk to the Telegram Bot API. You do not interact with grammY directly; it is a dependency that handles the mechanics of polling, parsing incoming messages, and sending replies. It is mentioned in the OpenClaw documentation to identify the underlying Telegram client. If you see a grammY-related error in the logs, the issue is in the Telegram communication layer, usually a bad token or a network problem.

The OpenClaw process that runs continuously on your machine or server, connecting your chat apps to your AI. The gateway handles all channel connections (Telegram, WhatsApp, Discord), routes incoming messages to the right agent, and sends replies back. It is a single process that serves all channels simultaneously. You start it with openclaw gateway and it runs until you stop it. Everything else in OpenClaw (sessions, agents, config) is managed through or by the gateway.

In OpenClaw, a connected messaging platform: Telegram, WhatsApp, Discord, iMessage. Each channel has its own section in the config file (channels.telegram, channels.whatsapp, etc.) and its own connection mechanism. Telegram is configured by pasting a bot token; WhatsApp is paired by scanning a QR code. The gateway can run multiple channels simultaneously. Messages coming in through a channel are routed back out through the same channel: a Telegram message gets a Telegram reply.

A JSON5 file (JSON with comments and trailing commas allowed) that controls how OpenClaw behaves. Contains your bot token, access control settings, model preferences, and anything else you configure. OpenClaw reads this file when the gateway starts. Changes to the config require a gateway restart to take effect. The file lives in your OpenClaw data directory. Keep it out of version control if it contains secrets: the bot token is a secret.

A named value set in the operating system's environment that a programme can read. OpenClaw reads TELEGRAM_BOT_TOKEN as a fallback if the token is not in the config file. Setting an environment variable avoids pasting secrets into a config file, which is useful in certain deployment contexts. On a VPS, you might set it in a systemd service file. Locally, you might set it in a shell profile. Config file values take precedence over environment variables when both are set.

A superset of JSON (JavaScript Object Notation) that allows comments, trailing commas, and unquoted keys. OpenClaw's config file is JSON5. It looks like JSON but is more forgiving: you can add a // comment to explain a setting, leave a trailing comma after the last item in a list, and quote keys only when necessary. If you are used to editing standard JSON, JSON5 is the same with fewer frustrations. If the gateway fails to start with a config parse error, a missing comma or stray character is usually the cause.

The OpenClaw setting that controls who can send direct messages to your bot and have them processed. Set under channels.telegram.dmPolicy. Four options: pairing (default, requires approval per user), allowlist (only specified user IDs are admitted), open (anyone can message the bot), and disabled (no DMs processed). For a personal bot, pairing is the most practical starting point: it prompts you to approve the first message from any new user.

OpenClaw's default mechanism for approving new Telegram users. When someone sends a DM to your bot for the first time, OpenClaw generates a pairing code and holds the message. You approve it with openclaw pairing approve telegram <CODE>. Once approved, that user's messages are processed. Pairing codes expire after one hour. Pairing keeps the bot private without requiring you to look up user IDs in advance. It is the recommended mode for personal setups.

A config setting listing the numeric Telegram user IDs that are allowed to interact with your bot in DM. Used when dmPolicy is set to allowlist. Each entry is a numeric ID (not a username). The onboarding wizard will resolve @username to an ID if you provide one. An empty allowFrom with dmPolicy: "allowlist" is invalid and blocks all DMs. The special value "*" combined with dmPolicy: "open" allows anyone.

The OpenClaw setting that controls access within Telegram groups (as opposed to DMs). Separate from dmPolicy. Options: allowlist (default, only listed users in listed groups are processed), open (any group member in allowed groups), disabled. Which groups are allowed is controlled by channels.telegram.groups: you specify group chat IDs. A group not listed is blocked by default. This separation means you can have open DMs and restricted group access, or vice versa.

A per-group setting that controls whether the bot must be mentioned by name before it responds to a group message. When true (the default), someone must type @YourBotUsername in the message for OpenClaw to respond. When false, the bot responds to every message in the group. Useful in groups where you want the bot to be always-on rather than invoked explicitly. Set it to false carefully in busy groups: the bot will respond to every message.

A user whose messages OpenClaw will process. The term appears in OpenClaw's config and logs to describe users who have passed the active access control check (pairing approval or allowlist membership). An unauthorized sender's message arrives at the gateway but is not passed to the AI. The bot may or may not send a response to an unauthorized sender depending on your configuration.

Starts the OpenClaw gateway process. Reads your config file, connects to all configured channels (including Telegram), and begins listening for messages. Runs in the foreground by default. Run with --install-daemon during onboarding to install it as a background service that starts automatically. Once running, the gateway is what your Telegram messages are talking to.

Lists pending pairing requests for the Telegram channel: users who have sent a DM to your bot and are waiting for approval. Shows each request with a code. Run this after someone messages your bot to see if there is a pending request to approve. If the list is empty and you expected a request, check that the bot token is correct and the gateway is running.

Approves a pending Telegram pairing request using the code from pairing list. Once approved, the user's messages will be processed and any held messages delivered to the AI. Codes expire after one hour, so approve promptly. If you approve a code after it has expired, the user will need to send another message to generate a new one.

Streams the gateway's live log output to your terminal. Useful for debugging: you can see incoming messages, their chat.id and from.id fields (useful for finding IDs to add to allowlists), routing decisions, and any errors. The most direct way to understand what the gateway is doing and why a message is or is not being processed.

A diagnostic command that checks your OpenClaw configuration for common problems and attempts to fix them. Useful after upgrades: if a previous version stored allowlist entries as @username strings and the current version requires numeric IDs, doctor --fix will resolve them. Requires a valid Telegram bot token to look up user IDs. Run it if something is unexpectedly broken after an update.