text
Copy
* `pairing` (default)
* `allowlist` (requires at least one sender ID in `allowFrom`)
* `open` (requires `allowFrom` to include `"*"`)
* `disabled`

`dmPolicy: "open"` with `allowFrom: ["*"]` lets any Telegram account that finds or guesses the bot username command the bot. Use it only for intentionally public bots with tightly restricted tools; one-owner bots should use `allowlist` with numeric user IDs.

`channels.telegram.allowFrom` accepts numeric Telegram user IDs. `telegram:` / `tg:` prefixes are accepted and normalized.
In multi-account configs, a restrictive top-level `channels.telegram.allowFrom` is treated as a safety boundary: account-level `allowFrom: ["*"]` entries do not make that account public unless the effective account allowlist still contains an explicit wildcard after merging.
`dmPolicy: "allowlist"` with empty `allowFrom` blocks all DMs and is rejected by config validation.
Setup asks for numeric user IDs only.
If you upgraded and your config contains `@username` allowlist entries, run `openclaw doctor --fix` to resolve them (best-effort; requires a Telegram bot token).
If you previously relied on pairing-store allowlist files, `openclaw doctor --fix` can recover entries into `channels.telegram.allowFrom` in allowlist flows (for example when `dmPolicy: "allowlist"` has no explicit IDs yet).

For one-owner bots, prefer `dmPolicy: "allowlist"` with explicit numeric `allowFrom` IDs to keep access policy durable in config (instead of depending on previous pairing approvals).

Common confusion: DM pairing approval does not mean "this sender is authorized everywhere".
Pairing grants DM access. If no command owner exists yet, the first approved pairing also sets `commands.ownerAllowFrom` so owner-only commands and exec approvals have an explicit operator account.
Group sender authorization still comes from explicit config allowlists.
If you want "I am authorized once and both DMs and group commands work", put your numeric Telegram user ID in `channels.telegram.allowFrom`; for owner-only commands, make sure `commands.ownerAllowFrom` contains `telegram:<your user id>`.

### Finding your Telegram user ID

Safer (no third-party bot):

1. DM your bot.
2. Run `openclaw logs --follow`.
3. Read `from.id`.

Official Bot API method:

```bash}
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```

Third-party method (less private): `@userinfobot` or `@getidsbot`.

text
Copy
1. **Which groups are allowed** (`channels.telegram.groups`)
   * no `groups` config:
     * with `groupPolicy: "open"`: any group can pass group-ID checks
     * with `groupPolicy: "allowlist"` (default): groups are blocked until you add `groups` entries (or `"*"`)
   * `groups` configured: acts as allowlist (explicit IDs or `"*"`)

2. **Which senders are allowed in groups** (`channels.telegram.groupPolicy`)
   * `open`
   * `allowlist` (default)
   * `disabled`

`groupAllowFrom` is used for group sender filtering. If not set, Telegram falls back to `allowFrom`.
`groupAllowFrom` entries should be numeric Telegram user IDs (`telegram:` / `tg:` prefixes are normalized).
Do not put Telegram group or supergroup chat IDs in `groupAllowFrom`. Negative chat IDs belong under `channels.telegram.groups`.
Non-numeric entries are ignored for sender authorization.
Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals.
Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`.
If `groupAllowFrom` is unset, Telegram falls back to config `allowFrom`, not the pairing store.
Practical pattern for one-owner bots: set your user ID in `channels.telegram.allowFrom`, leave `groupAllowFrom` unset, and allow the target groups under `channels.telegram.groups`.
Runtime note: if `channels.telegram` is completely missing, runtime defaults to fail-closed `groupPolicy="allowlist"` unless `channels.defaults.groupPolicy` is explicitly set.

Example: allow any member in one specific group:

```json5}
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}
```

Example: allow only specific users inside one specific group:

```json5}
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}
```

<Warning>
  Common mistake: `groupAllowFrom` is not a Telegram group allowlist.

  * Put negative Telegram group or supergroup chat IDs like `-1001234567890` under `channels.telegram.groups`.
  * Put Telegram user IDs like `8734062810` under `groupAllowFrom` when you want to limit which people inside an allowed group can trigger the bot.
  * Use `groupAllowFrom: ["*"]` only when you want any member of an allowed group to be able to talk to the bot.
</Warning>

text
Copy
Mention can come from:

* native `@botusername` mention, or
* mention patterns in:
  * `agents.list[].groupChat.mentionPatterns`
  * `messages.groupChat.mentionPatterns`

Session-level command toggles:

* `/activation always`
* `/activation mention`

These update session state only. Use config for persistence.

Persistent config example:

```json5}
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}
```

Getting the group chat ID:

* forward a group message to `@userinfobot` / `@getidsbot`
* or read `chat.id` from `openclaw logs --follow`
* or inspect Bot API `getUpdates`