OpenClaw Telegram 配置指南

状态

通过 grammY 为机器人生成就绪的 Bot API + 群组。默认长轮询；可选 webhook。

快速设置（初学者）

• 使用 @BotFather 创建机器人（直接链接）。确认 handle 正好是 @BotFather，然后复制令牌。
• 设置令牌：
  • 环境变量: TELEGRAM_BOT_TOKEN=...
  • 或配置: channels.telegram.botToken: "..."
• 如果两者都设置，配置优先（环境回退仅用于默认账号）
• 启动网关
• DM 访问默认是配对；首次联系时批准配对代码

最小配置：

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

设置（快速路径）

1) 创建机器人令牌（BotFather）

• 打开 Telegram 并与 @BotFather（直接链接）聊天。确认 handle 正好是 @BotFather。
• 运行 /newbot，然后按照提示操作（名称 + 以 bot 结尾的用户名）
• 复制令牌并安全存储

可选 BotFather 设置：

• /setjoingroups — 允许/拒绝将机器人添加到群组
• /setprivacy — 控制机器人是否看到所有群组消息

2) 配置令牌（环境变量或配置）

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

环境选项: TELEGRAM_BOT_TOKEN=...（适用于默认账号）

如果环境变量和配置都设置，配置优先。

令牌 + 隐私 + 权限（Telegram 端）

令牌创建（BotFather）

• /newbot 创建机器人并返回令牌（保持秘密）
• 如果令牌泄漏，通过 @BotFather 撤销/重新生成并更新配置

群组消息可见性（隐私模式）

Telegram 机器人默认为隐私模式，限制它们接收的群组消息。

如果您的机器人必须看到所有群组消息，有两个选项：

• 使用 /setprivacy 禁用隐私模式
• 将机器人添加为群组管理员（管理员机器人接收所有消息）

注意: 切换隐私模式时，Telegram 要求将机器人从每个群组中移除并重新添加，更改才能生效。

工作原理（行为）

• 入站消息使用回复上下文和媒体占位符规范化为共享频道信封
• 群组回复默认需要提及（原生 @提及或 agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns）
• 回复始终路由回同一 Telegram 聊天
• 长轮询使用 grammY runner 和每聊天排序；整体并发由 agents.defaults.maxConcurrent 限制
• Telegram Bot API 不支持已读回执；没有 sendReadReceipts 选项

群组激活模式

默认情况下，机器人仅在群组中响应提及（@botname 或 agents.list[].groupChat.mentionPatterns 中的模式）。

通过配置更改（推荐）

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": { "requireMention": false }
      }
    }
  }
}

允许所有群组始终响应：

{
  "channels": {
    "telegram": {
      "groups": {
        "*": { "requireMention": false }
      }
    }
  }
}

通过命令（会话级别）

在群组中发送：

• /activation always - 响应所有消息
• /activation mention - 需要提及（默认）

注意: 命令仅更新会话状态。要持久化行为，使用配置。

访问控制（DM + 群组）

DM 访问

• 默认: channels.telegram.dmPolicy = "pairing"。未知发送者接收配对代码；消息被忽略直到批准（代码在 1 小时后过期）
• 通过以下方式批准：

  openclaw pairing list telegram
  openclaw pairing approve telegram <code>

• channels.telegram.allowFrom 接受数字用户 ID（推荐）或 @username 条目

群组访问

两个独立的控制：

1. 允许哪些群组（通过 channels.telegram.groups 的群组允许列表）
2. 允许哪些发送者（通过 channels.telegram.groupPolicy 的发送者过滤）

默认是 groupPolicy: "allowlist"（除非您在 groupAllowFrom 中添加，否则阻止）。

长轮询 vs Webhook

• 默认: 长轮询（不需要公共 URL）
• Webhook 模式: 设置 channels.telegram.webhookUrl 和 channels.telegram.webhookSecret（可选 channels.telegram.webhookPath）

本地监听器绑定到 0.0.0.0:8787，默认服务 POST /telegram-webhook。

如果您的公共 URL 不同，使用反向代理并将 channels.telegram.webhookUrl 指向公共端点。

限制

• 出站文本分块到 channels.telegram.textChunkLimit（默认 4000）
• 可选换行分块：设置 channels.telegram.chunkMode="newline" 以在空白行（段落边界）处分割
• 媒体下载/上传由 channels.telegram.mediaMaxMb（默认 5）限制
• Telegram Bot API 请求在 channels.telegram.timeoutSeconds（默认 500 通过 grammY）后超时
• 群组历史上下文使用 channels.telegram.historyLimit（或 channels.telegram.accounts.*.historyLimit），回退到 messages.groupChat.historyLimit。设置为 0 以禁用（默认 50）

贴纸支持

OpenClaw 支持接收和发送 Telegram 贴纸。

接收贴纸

• 静态贴纸（WEBP）: 下载并通过视觉处理
• 动画贴纸（TGS）: 跳过（不支持 Lottie 格式处理）
• 视频贴纸（WEBM）: 跳过（不支持视频格式处理）

发送贴纸

代理可以使用 sticker 和 sticker-search 操作发送和搜索贴纸。

{
  "action": "sticker",
  "channel": "telegram",
  "to": "123456789",
  "fileId": "CAACAgIAAxkBAAI..."
}

配置参考

来源: https://docs.openclaw.ai/channels/telegram