Telegram（Bot API）

状态：通过 grammY 生产就绪，支持机器人 DM + 群组。默认模式是长轮询；Webhook 模式是可选的。

Telegram 的默认 DM 策略是配对。 跨频道诊断和修复手册。 完整频道配置模式和示例。

快速设置

打开 Telegram 并与 **@BotFather** 对话（确认句柄恰好是 `@BotFather`）。 
运行 `/newbot`，按照提示操作，并保存令牌。
 
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
Telegram **不使用** `openclaw channels login telegram`；在配置/环境变量中配置令牌，然后启动网关。
 ```bash openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` 将机器人添加到您的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配您的访问模型。 令牌解析顺序是账户感知的。实际上，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。

Telegram 设置

Telegram 机器人默认**隐私模式**，限制它们收到的群组消息。 
如果机器人必须查看所有群组消息，要么：
- 通过 `/setprivacy` 禁用隐私模式，或
- 使机器人成为群组管理员

- 切换隐私模式时，移除并在每个群组中重新添加机器人，以便 Telegram 应用更改。
 在 Telegram 群组设置中控制机器人权限： 段理员机器人接收所有群组消息，这对于始终在线的群组行为很有用。 机器人可以配置为响应命令： 默认命令：`/start`、`/help` 自定义命令可以通过 BotFather 设置 `channels.telegram.dmPolicy` 控制直接聊天访问： - `pairing`（默认） - 未知发送者需配对 - `allowlist` - 仅允许 `allowFrom` 白名单 - `open` - 允许所有入站 DM（需要 `allowFrom: ["*"]`） - `disabled` - 禁用入站 DM 
群组会话是独立的。
 `channels.telegram.groupPolicy` 控制群组访问： - `open` - 允许所有群组访问 - `allowlist` - 仅允许白名单群组 - `disabled` - 禁用所有群组访问

最小配置

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

白名单模式

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "allowlist",
      allowFrom: ["123456789"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

Webhook 模式

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      mode: "webhook",
      webhookUrl: "https://your-domain.com/telegram",
    },
  },
}

运行时配置

Telegram 机器人默认**隐私模式**，限制它们收到的群组消息。 
如果机器人必须查看所有群组消息，要么：
- 通过 `/setprivacy` 禁用隐私模式，或
- 使机器人成为群组管理员

- 切换隐私模式时，移除并在每个群组中重新添加机器人，以便 Telegram 应用更改。
 在 Telegram 群组设置中控制机器人权限： 段理员机器人接收所有群组消息，这对于始终在线的群组行为很有用。 机器人可以配置为响应命令： 默认命令：`/start`、`/help` 自定义命令可以通过 BotFather 设置 `channels.telegram.dmPolicy` 控制直接聊天访问： - `pairing`（默认） - 未知发送者需配对 - `allowlist` - 仅允许 `allowFrom` 白名单 - `open` - 允许所有入站 DM（需要 `allowFrom: ["*"]`） - `disabled` - 禁用入站 DM 
群组会话是独立的。
 `channels.telegram.groupPolicy` 控制群组访问： - `open` - 允许所有群组访问 - `allowlist` - 仅允许白名单群组 - `disabled` - 禁用所有群组访问

检查状态

查看 Telegram 状态

openclaw channels status telegram

查看配对请求

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

查看日志

openclaw logs --channel telegram

故障排除

常见问题

机器人不响应

  • 确认机器人令牌正确
  • 检查机器人是否被 Telegram 限制（例如：API 错误 429）
  • 运行 openclaw doctor 检查整体状态

消息未送达

  • 网络问题或 Telegram 服务器故障
  • 确认 channels.telegram.dmPolicy 设置允许 DM 访问

机器人被踢出群组

  • 检查 Telegram 群组设置
  • 重新添加机器人到群组

相关链接