# Telegram setup

> Create the Telegram bot token, configure the channel, and approve the first DM

- 网址：https://funcoding.ai/agents/openclaw/channels/telegram/setup/
- 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/channels/telegram/setup

---
Create the bot in BotFather, give OpenClaw its token, approve the first DM, and add the bot to a group.

## Quick setup

**Create the bot token in BotFather**

Both flows end with a token you paste into OpenClaw — pick one:

- **Chat flow**: open Telegram and chat with **@BotFather**. Confirm the handle is exactly `@BotFather`. Run `/newbot`, follow the prompts, and save the token.
- **Web flow**: open [BotFather's web app](https://t.me/BotFather?startapp). It runs in every Telegram client, including [web.telegram.org](https://web.telegram.org). Create the bot in the UI, then copy its token.

**Configure token and DM policy**

    The fastest option is the CLI. It writes the token into your config for you:

```bash
openclaw channels add --channel telegram --token <bot-token>
```

    To edit config by hand instead, put this in `~/.openclaw/openclaw.json`:

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
```

    Env fallback: `TELEGRAM_BOT_TOKEN` (default account only). Named accounts must use `botToken` or `tokenFile`.
    Telegram does **not** use `openclaw channels login telegram`. Set the token in config or env, then start the gateway.

**Verify the channel**

    <a id="restart-the-gateway" />
    With the default [hot reload](https://funcoding.ai/agents/openclaw/gateway/configuration/hot-reload/), the running
    Gateway applies the new channel configuration. Check that Telegram is ready:

```bash
openclaw channels status --probe
```

    If the Gateway is offline, start it with `openclaw gateway start` for a managed
    service, or `openclaw gateway` to run it in this terminal. If you changed the
    service environment, restart the Gateway to load it.

**Approve your first DM**

    Open Telegram and send any message to your bot. That message creates the
    pairing request the next command lists:

```bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```

    Pairing codes expire after 1 hour.

**Add the bot to a group**

Add the bot to your group, then get the two IDs group access needs:

- your Telegram user ID, for `allowFrom` / `groupAllowFrom`
- the Telegram group chat ID, as the key under `channels.telegram.groups`

Get the group chat ID from `openclaw logs --follow`, a forwarded-ID bot, or Bot API `getUpdates`. After the group is allowed, `/whoami@<bot_username>` confirms the user and group IDs.

Negative supergroup IDs starting with `-100` are group chat IDs. They go under `channels.telegram.groups`, not `groupAllowFrom`.

<div class="callout callout-note">

Token resolution is account-aware. `tokenFile` beats `botToken`, and `botToken` beats env. Config always wins over `TELEGRAM_BOT_TOKEN`, which only resolves for the default account. After a successful startup, OpenClaw caches the bot identity for up to 24 hours, so restarts skip an extra `getMe` call. Changing or removing the token clears that cache.

</div>

## Telegram side settings

<details>
<summary>Privacy mode and group visibility</summary>

Telegram bots default to **Privacy Mode**, which limits which group messages they receive.

To see all group messages, either:

- disable privacy mode via `/setprivacy`, or
- make the bot a group admin.

After toggling privacy mode, remove and re-add the bot in each group so Telegram applies the change.

</details>

<details>
<summary>Group permissions</summary>

Admin status is controlled in Telegram group settings. Admin bots receive all group messages, useful for always-on group behavior.

</details>

<details>
<summary>Helpful BotFather toggles</summary>

- `/setjoingroups` — allow/deny group adds
- `/setprivacy` — group visibility behavior

The same settings are available in [BotFather's web app](https://t.me/BotFather?startapp) if you prefer a UI over chat commands.

</details>