OpenClaw Telegram 渠道
即时通讯
简单
通过 grammY Bot API 框架将 OpenClaw 连接到 Telegram。使用 @BotFather 创建 Telegram 机器人，获取 token，几分钟内就能让 AI 助手在 Telegram 上运行。默认使用长轮询模式，可选 Webhook 模式。这是最容易设置的渠道之一，支持内联按钮、贴纸、表情回应和群聊等丰富功能。
快速信息
难度简单
分类即时通讯
支持功能数6 / 6
Telegram 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
支持
消息线程
支持
语音消息
支持
群聊
支持
Telegram 前置条件
- 一个 Telegram 账号
- 通过 @BotFather 获取的 Bot Token（向 @BotFather 发送 /newbot）
- OpenClaw Gateway 已运行并配置
- 服务器安装 Node.js 18+
Telegram 快速设置
1
通过 @BotFather 创建机器人
打开 Telegram，搜索 @BotFather，发送 /newbot。按提示为机器人命名并获取 API token。妥善保存此 token——配置时需要用到。
2
添加 Telegram 渠道配置
在 ~/.openclaw/openclaw.json 中添加 Telegram 渠道配置。将 @BotFather 提供的 bot token 粘贴到 botToken 字段。设置 dmPolicy（pairing、allowlist 或 open）来控制谁可以与你的 AI 助手对话。
3
启动 Gateway 并测试
启动 Gateway 进程。在 Telegram 中搜索你的机器人并发送消息。如果使用默认的 pairing 策略，通过 'openclaw pairing approve telegram <code>' 审批发送者。OpenClaw 应通过 AI 助手自动回复。
Telegram 配置示例
config.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
"dmPolicy": "pairing"
}
}
}Telegram 深入了解
架构概述
OpenClaw 通过 grammY 框架连接到 Telegram——这是一个现代的、TypeScript 优先的 Telegram Bot API 库。机器人默认使用长轮询模式，即定期向 Telegram 服务器查询新的更新。这种方式开箱即用，无需额外配置。
你也可以切换到 Webhook 模式用于生产环境部署。在 Webhook 模式下，Telegram 会主动将更新推送到你的服务器端点，效率更高、延迟更低。
长轮询可在 NAT 和防火墙后正常工作，无需额外配置。Webhook 模式需要一个公开可访问的 HTTPS 端点。
可以通过 TELEGRAM_BOT_TOKEN 环境变量或配置文件 channels.telegram.botToken 字段存储你的 bot token。
通过 @BotFather 创建机器人
BotFather 是 Telegram 官方的机器人创建和管理工具。以下是详细步骤：
1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot 开始创建流程
3. 为机器人选择一个显示名称（如「我的 AI 助手」）
4. 选择一个以 'bot' 结尾的用户名（如 "my_ai_assistant_bot"）
5. BotFather 会返回一个 API token——请妥善保存
创建后，你还可以使用 BotFather 命令进一步自定义：
• /setdescription — 设置机器人简介中显示的描述
• /setabouttext — 设置「关于」部分文字
• /setuserpic — 上传头像
• /setprivacy — 切换群组消息的隐私模式
请保管好你的 bot token。任何拥有该 token 的人都可以控制你的机器人。如果泄露，请在 BotFather 中使用 /revoke 生成新的 token。
私聊策略
DM（私聊）策略控制谁可以与你的 AI 助手进行私聊。OpenClaw 支持四种策略：
• pairing（默认）— 新用户需要通过配对流程。他们发送消息后会收到一个配对码（有效期 1 小时），你在终端通过命令审批或拒绝。审批后即可自由聊天。
• allowlist — 只有在 allowFrom 列表中明确列出的数字用户 ID 才能与机器人对话。其他人会被静默忽略。
• open — 任何向机器人发送消息的人都会得到回复。在生产环境中请谨慎使用。
• disabled — 完全关闭私聊功能。机器人不会回复任何私聊消息。
openclaw.json
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}要查找用户的 Telegram 数字 ID，可以使用 @userinfobot 或在用户发送消息时查看 Gateway 日志。
群聊管理
OpenClaw 支持 Telegram 群聊，并提供灵活的访问控制，通过两个独立机制：
1. 群组白名单 — 决定允许哪些群组。可以是所有群组，或仅限 channels.telegram.groups 中列出的群组。
2. 群组策略 — 控制允许的群组内发送者权限：
• open — 任何群组成员都可以触发机器人
• allowlist — 仅已审批的发送者可以互动
• disabled — 完全忽略群组消息
默认情况下，机器人在群组中需要 @提及 才会回复。你可以更改此行为：
• 使用 /activation always 命令（仅当前会话生效）回复所有消息
• 在配置中设置 requireMention: false 永久开启全部回复
openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "open",
"requireMention": false,
"groups": ["-1001234567890"]
}
}
}对于论坛风格的群组（话题），OpenClaw 使用线程 ID 隔离每个话题，并可以应用每个话题的配置覆盖。
要让机器人在非管理员身份下看到群组中的所有消息，你必须在 BotFather 中通过 /setprivacy 关闭隐私模式，然后将机器人移出群组并重新添加。
消息格式与流式传输
OpenClaw 提供多种消息格式化和传输选项：
格式化：出站消息使用 Telegram 的 HTML 解析器，自动从 Markdown 风格转换。如果 HTML 解析失败，消息会以纯文本重试。
流式传输：草稿气泡在私聊中支持部分回复流式传输。两种模式可选：
• partial（默认）— AI 生成时逐步更新单条消息
• block — 以完整块的方式分段发送
文本默认按 4,000 字符分块（Telegram 限制）。启用 chunkMode: "newline" 可按段落边界分割，而非硬性截断。
openclaw.json
{
"channels": {
"telegram": {
"streamMode": "partial",
"chunkMode": "newline"
}
}
}内联按钮
OpenClaw 支持 Telegram 的交互式内联键盘按钮。启用后，AI 可以在消息下方展示按钮供用户点击。点击按钮会将回调数据以格式化消息的形式发送回代理。
可用模式：
• off — 禁用按钮（默认）
• dm — 仅在私聊中启用
• group — 仅在群聊中启用
• all — 全部启用
• allowlist — 按发送者授权限制
openclaw.json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}贴纸与媒体
OpenClaw 支持处理 Telegram 贴纸和媒体文件：
贴纸：静态贴纸会被下载并通过视觉分析处理，生成的描述会被缓存以避免重复 API 调用。动画和视频贴纸跳过处理。代理可以使用存储的文件 ID 发送贴纸，并通过描述、表情或贴纸包名称搜索缓存的贴纸。
媒体：默认媒体上传/下载限制为 5 MB。机器人支持发送和接收图片、文档、音频文件和视频。
在代理配置中启用 sticker 动作，以允许通过文件 ID 或缓存搜索发送贴纸。
表情回应
OpenClaw 支持 Telegram 的表情回应系统，包括接收和发送表情回应：
收到的回应会生成系统事件，添加到代理上下文中。你可以配置哪些回应触发通知：
• off — 不通知
• own — 仅机器人消息的回应
• all — 聊天中所有回应
机器人也可以发送回应。配置回应能力级别：
• off — 不回应
• ack — 处理时发送确认回应（默认）
• minimal — 基本回应
• extensive — 完整表情范围
openclaw.json
{
"channels": {
"telegram": {
"reactionNotifications": "own",
"reactionLevel": "ack"
}
}
}命令与工具
原生机器人命令（如 /status、/reset）会自动注册到 Telegram 的机器人命令菜单中，方便用户发现。自定义命令可以通过配置添加，但仅作为菜单入口使用。
代理还支持工具操作：
• 向特定聊天发送消息
• 对消息发送表情回应
• 删除消息
• 使用 [[reply_to:<id>]] 标签回复特定消息
在代理回复中使用 [[reply_to_current]] 可直接回复用户的当前消息。
在回复中包含 [[audio_as_voice]] 或在工具调用中设置 asVoice: true 可强制使用语音消息格式。
Webhook 模式
对于生产环境部署，推荐使用 Webhook 模式而非长轮询。在 Webhook 模式下，Telegram 会主动将更新推送到你的服务器，降低延迟和资源消耗。
要启用 Webhook，在配置中设置 webhookUrl 和 webhookSecret。本地端点默认绑定到 0.0.0.0:8787。
openclaw.json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-random-secret-string"
}
}
}从轮询切换到 Webhook 模式时，Gateway 会在启动时自动向 Telegram 注册 Webhook URL。
Webhook 模式需要一个公开可访问的 HTTPS 端点。请确保你的服务器拥有有效的 SSL 证书。
Telegram 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用 Telegram 渠道 |
| botToken | string | "" | 来自 @BotFather 的 Telegram Bot API token。也可使用 TELEGRAM_BOT_TOKEN 环境变量 |
| dmPolicy | string | "pairing" | 控制谁可以私聊机器人。选项：pairing、allowlist、open、disabled |
| allowFrom | number[] | [] | 允许与机器人对话的 Telegram 数字用户 ID（当 dmPolicy 为 allowlist 时） |
| groupPolicy | string | "allowlist" | 群聊策略。选项：disabled、open、allowlist |
| groups | string[] | [] | 允许的群聊 ID 列表。为空且 groupPolicy 非 disabled 时允许所有群组 |
| requireMention | boolean | true | 机器人在群组中是否需要 @提及 才回复 |
| streamMode | string | "partial" | AI 回复的流式模式。选项：partial（逐步更新）、block（分块发送）、off（禁用） |
| chunkMode | string | "split" | 长回复的处理方式。选项：split（硬字符限制）、newline（按段落分割） |
| webhookUrl | string | "" | Webhook 模式的 HTTPS URL。设置后从轮询切换为 Webhook |
| webhookSecret | string | "" | Webhook 验证的密钥 token |
| reactionNotifications | string | "off" | 哪些回应触发通知。选项：off、own、all |
| reactionLevel | string | "ack" | 机器人的回应能力。选项：off、ack、minimal、extensive |
| capabilities.inlineButtons | string | "off" | 内联按钮模式。选项：off、dm、group、all、allowlist |
| configWrites | boolean | true | 超级群组升级时自动迁移聊天 ID。设为 false 可禁用 |
| mediaCap | number | 5 | 媒体文件上传和下载的最大大小（MB） |
| historyLimit | number | 50 | 每个用户/群组会话保留的最大历史消息数 |
| retryPolicy | object | { "maxRetries": 3, "backoff": "exponential" } | API 调用失败时的重试策略，支持指数退避 |
| proxyUrl | string | "" | Telegram API 调用的代理 URL。适用于网络受限环境 |
| forceIPv4 | boolean | false | 强制 api.telegram.org 使用 IPv4 解析。当 IPv6 出口导致静默失败时启用 |
enabled
Type: booleanDefault: true
启用或禁用 Telegram 渠道
botToken
Type: stringDefault: ""
来自 @BotFather 的 Telegram Bot API token。也可使用 TELEGRAM_BOT_TOKEN 环境变量
dmPolicy
Type: stringDefault: "pairing"
控制谁可以私聊机器人。选项：pairing、allowlist、open、disabled
allowFrom
Type: number[]Default: []
允许与机器人对话的 Telegram 数字用户 ID（当 dmPolicy 为 allowlist 时）
groupPolicy
Type: stringDefault: "allowlist"
群聊策略。选项：disabled、open、allowlist
groups
Type: string[]Default: []
允许的群聊 ID 列表。为空且 groupPolicy 非 disabled 时允许所有群组
requireMention
Type: booleanDefault: true
机器人在群组中是否需要 @提及 才回复
streamMode
Type: stringDefault: "partial"
AI 回复的流式模式。选项：partial（逐步更新）、block（分块发送）、off（禁用）
chunkMode
Type: stringDefault: "split"
长回复的处理方式。选项：split（硬字符限制）、newline（按段落分割）
webhookUrl
Type: stringDefault: ""
Webhook 模式的 HTTPS URL。设置后从轮询切换为 Webhook
webhookSecret
Type: stringDefault: ""
Webhook 验证的密钥 token
reactionNotifications
Type: stringDefault: "off"
哪些回应触发通知。选项：off、own、all
reactionLevel
Type: stringDefault: "ack"
机器人的回应能力。选项：off、ack、minimal、extensive
capabilities.inlineButtons
Type: stringDefault: "off"
内联按钮模式。选项：off、dm、group、all、allowlist
configWrites
Type: booleanDefault: true
超级群组升级时自动迁移聊天 ID。设为 false 可禁用
mediaCap
Type: numberDefault: 5
媒体文件上传和下载的最大大小（MB）
historyLimit
Type: numberDefault: 50
每个用户/群组会话保留的最大历史消息数
retryPolicy
Type: objectDefault: { "maxRetries": 3, "backoff": "exponential" }
API 调用失败时的重试策略，支持指数退避
proxyUrl
Type: stringDefault: ""
Telegram API 调用的代理 URL。适用于网络受限环境
forceIPv4
Type: booleanDefault: false
强制 api.telegram.org 使用 IPv4 解析。当 IPv6 出口导致静默失败时启用
Telegram 常见问题
Telegram 故障排查
机器人在群组中不被提及就不回复
Telegram 机器人默认启用隐私模式。启用时，机器人只能接收 @提及 它的消息或以斜杠命令开头的消息。
在 BotFather 中关闭隐私模式：向 @BotFather 发送 /setprivacy，选择你的机器人，然后选择 'Disable'。接着将机器人移出群组并重新添加。同时在 OpenClaw 配置中设置 requireMention: false（如果你希望机器人回复所有消息）。
机器人不回复任何消息
bot token 可能不正确，Gateway 可能未运行，或存在网络连接问题。
通过 Telegram Bot API 直接测试验证 token 是否正确：curl https://api.telegram.org/bot<token>/getMe。检查 Gateway 日志中的连接错误。对于 IPv6 路由问题导致的静默失败，可强制 api.telegram.org 使用 IPv4 解析，或通过 dig 命令验证 DNS 返回可用地址。
Webhook 未收到更新
Webhook URL 不可公开访问，SSL 证书无效，或 Webhook 未正确注册。
验证 Webhook URL 可从互联网访问（用 curl 测试）。确保 SSL 证书有效且非自签名。使用以下命令检查 Webhook 状态：curl https://api.telegram.org/bot<token>/getWebhookInfo。重启 Gateway 以重新注册 Webhook。
消息被截断或分割不正确
Telegram 有 4,000 字符的消息限制。较长的 AI 回复会被自动分块。
将 chunkMode 设为 'newline' 以按段落边界分割，而非硬性字符限制截断。你也可以在配置中调整最大文本分块大小。