Telegram

部署步骤

1. 创建 Telegram Bot

打开 Telegram 并与 @BotFather 对话（请确认用户名确实是 @BotFather）
发送 /newbot 命令
按提示设置机器人名称和用户名（用户名必须以 bot 结尾）
复制并保存 Bot Token（请妥善保管，如泄露需通过 @BotFather 撤销/重新生成）

2. 配置 Bot 设置（可选）

通过 BotFather 配置：

/setdescription - 设置描述
/setabouttext - 设置关于信息
/setuserpic - 设置头像
/setjoingroups - 允许/拒绝将机器人添加到群组
/setprivacy - 控制机器人是否可以看到所有群组消息

3. 配置 302 AI Studio

在 302 AI Studio 客户端的「设置 → Vibe 模式」中填入 Bot Token 后，点击「更新配置」按钮，网关将自动重启，之后即可在 Telegram 中正常对话。

默认使用长轮询模式，无需配置公网地址。私聊默认使用配对模式，首次联系时需要批准配对码。

4. 发送测试消息

在 Telegram 中找到您创建的机器人，发送一条消息进行测试。

5. 配对授权

默认情况下，机器人会回复一个配对码和配对命令。

如果机器人要求运行配对命令（如 openclaw pairing approve telegram <配对码>），请复制该命令，然后回到 302 AI Studio 客户端，将命令发送给 Open Claw，让它执行配对操作。配对码 1 小时后过期。

配对成功后即可正常对话！

私聊策略

策略	说明
`pairing`	配对模式（默认）：未知发送者收到配对码，批准后才能使用
`allowlist`	允许列表模式：只有指定用户 ID 可以使用
`open`	开放模式：所有人都可以使用
`disabled`	禁用私聊

获取用户 ID

有多种方式获取 Telegram 用户 ID：

方式一（推荐）：通过 Gateway 日志

启动 Gateway 网关并私信你的机器人
运行 openclaw logs --follow 并查找 from.id

方式二：通过 Bot API

私信你的机器人
使用你的机器人 token 获取更新并读取 message.from.id：

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

方式三：第三方机器人

私信 @userinfobot 或 @getidsbot 并使用返回的用户 ID

群组设置

如果需要在群组中使用机器人：

将机器人添加到群组
如果需要机器人响应所有消息（而非仅 @提及），请在 BotFather 中使用 /setprivacy 禁用隐私模式，或将机器人设为群组管理员

切换隐私模式后，需要将机器人从群组中移除并重新添加，更改才能生效。

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

Telegram 机器人默认启用隐私模式，这会限制它们接收哪些群组消息。如果你的机器人必须看到所有群组消息，有两个选项：

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

群组激活模式

默认情况下，机器人只响应群组中的提及（@botname）。

通过命令切换（会话级别）

在群组中发送：

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

命令只更新会话状态，重启后会恢复默认行为。

获取群组聊天 ID

将群组中的任何消息转发给 Telegram 上的 @userinfobot 或 @getidsbot 以查看聊天 ID（负数，如 -1001234567890）。

功能支持

功能	状态	说明
私聊	✅ 支持	共享智能体的主会话
群聊	✅ 支持	每个群组保持独立会话
图片	✅ 支持	支持发送和接收
文件	✅ 支持	支持发送和接收
语音	✅ 支持	支持语音备忘录和音频文件
视频	✅ 支持	支持发送和接收
贴纸	✅ 支持	静态贴纸支持视觉处理，动画/视频贴纸跳过
内联按钮	✅ 支持	支持回调按钮
表情反应	✅ 支持	支持接收和发送反应
论坛话题	✅ 支持	每个话题保持独立会话

贴纸功能

接收贴纸

当用户发送贴纸时，OpenClaw 根据贴纸类型处理：

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

OpenClaw 会缓存贴纸描述以避免重复的 API 调用，缓存位置：~/.openclaw/telegram/sticker-cache.json

音频消息

Telegram 区分语音备忘录（圆形气泡）和音频文件（元数据卡片）。OpenClaw 默认使用音频文件。

要在智能体回复中强制使用语音备忘录气泡，在回复中包含标签：[[audio_as_voice]]

内联按钮

Telegram 支持带回调按钮的内联键盘。当用户点击按钮时，回调数据会以 callback_data: value 格式作为消息发送回智能体。

原生命令

OpenClaw 在启动时向 Telegram 的机器人菜单注册原生命令：

命令	功能
`/status`	查看状态
`/reset`	重置会话
`/model`	切换模型
`/activation`	切换群组激活模式

格式化

出站 Telegram 文本使用 parse_mode: "HTML"
类 Markdown 输入被渲染为 Telegram 安全 HTML（粗体/斜体/删除线/代码/链接）
块级元素被扁平化为带换行/项目符号的文本
如果 Telegram 拒绝 HTML 负载，OpenClaw 会以纯文本重试

启动服务

请在 302 AI Studio 客户端的「设置 → Vibe 模式」中完成本渠道的配置。

限制

限制项	默认值	说明
文本分块	4000 字符	出站文本按此长度分块
媒体大小	5 MB	媒体下载/上传限制
历史记录	50 条	群组历史上下文条数

故障排除

机器人不响应

检查 Bot Token 是否正确
确认机器人已启动
检查到 api.telegram.org 的出站 HTTPS/DNS 是否被阻止

群组中无响应

检查 Bot Privacy Mode 设置（BotFather → /setprivacy）
如果需要响应所有消息，禁用隐私模式或将机器人设为管理员
确认是否需要 @提及机器人
使用 /activation always 临时测试

配对码问题

配对码 1 小时后过期
在 302 AI Studio 客户端中批准配对请求

机器人启动后静默停止响应

某些主机首先将 api.telegram.org 解析为 IPv6，如果服务器没有可用的 IPv6 出口可能会卡住
通过启用 IPv6 出口或强制使用 IPv4 解析来修复

setMyCommands failed 错误

通常意味着到 api.telegram.org 的出站 HTTPS/DNS 被阻止
检查网络连接和防火墙设置