Telegram（Bot API）
Telegram 是 OpenClaw 最容易设置的渠道之一。通过 grammY 框架支持机器人私信和群组，已可用于生产环境。
快速设置
创建机器人
与 @BotFather 对话创建机器人：
- 发送
/newbot
- 按提示输入名称和用户名（必须以
bot 结尾）
- 复制机器人令牌
确认用户名确实是 @BotFather，避免钓鱼机器人。
配置令牌
通过环境变量或配置文件设置令牌：export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
"dmPolicy": "pairing"
}
}
}
批准首个用户
首次联系机器人时，你会收到配对码：openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
配置选项
基础配置
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
}
}
}
}
{
"channels": {
"telegram": {
"dmPolicy": "pairing"
}
}
}
{
"channels": {
"telegram": {
"groups": {
"*": { "requireMention": true },
"-1001234567890": {
"requireMention": false,
"allowFrom": [123456789],
"skills": ["search", "docs"],
"systemPrompt": "保持回答简短。"
}
}
}
}
}
设置 groups 会创建允许列表 - 只有列出的群组（或 "*"）会被接受。
高级功能
Telegram 可以在生成回复时显示实时草稿更新：{
"channels": {
"telegram": {
"streamMode": "partial"
}
}
}
- 在 @BotFather 中启用线程模式
- 仅限私聊线程
选项：
"off" - 禁用"partial" - 实时更新（默认）"block" - 分块更新
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "allowlist"
}
}
}
}
{
"action": "send",
"channel": "telegram",
"to": "123456789",
"message": "选择一个选项：",
"buttons": [
[
{ "text": "是", "callback_data": "yes" },
{ "text": "否", "callback_data": "no" }
]
]
}
将命令添加到 Telegram 的机器人菜单：{
"channels": {
"telegram": {
"customCommands": [
{ "command": "backup", "description": "Git 备份" },
{ "command": "generate", "description": "创建图片" }
]
}
}
}
自定义命令只是菜单条目。你需要在其他地方实现命令处理逻辑。
群组功能
获取群组 ID
将群组中的任何消息转发给 @userinfobot 或 @getidsbot 查看聊天 ID：
群组 ID 是负数。使用此 ID 在配置中引用群组。
提及门控
默认情况下，机器人只响应群组中的提及：
{
"channels": {
"telegram": {
"groups": {
"-1001234567890": { "requireMention": true }
}
}
}
}
/activation always # 响应所有消息
/activation mention # 需要提及（默认）
论坛话题
Telegram 论坛话题自动获得独立会话：
{
"channels": {
"telegram": {
"groups": {
"-1001234567890": {
"topics": {
"123": {
"requireMention": false,
"skills": ["docs"],
"systemPrompt": "话题专用提示"
}
}
}
}
}
}
}
媒体处理
支持的类型
- 图片（JPEG、PNG、WebP）
- 视频（MP4、WEBM）
- 音频/语音消息
- 文档
- 贴纸（静态 WebP）
贴纸功能
静态贴纸自动处理并通过视觉功能描述。描述会被缓存以提高性能：缓存位置： ~/.openclaw/telegram/sticker-cache.json模板上下文中可用的字段：Sticker.emoji
Sticker.setName
Sticker.fileId
Sticker.cachedDescription
首先在配置中启用：{
"channels": {
"telegram": {
"actions": {
"sticker": true
}
}
}
}
{
"action": "sticker",
"channel": "telegram",
"to": "123456789",
"fileId": "CAACAgIAAxkBAAI..."
}
{
"action": "sticker-search",
"channel": "telegram",
"query": "猫 挥手",
"limit": 5
}
{
"channels": {
"telegram": {
"textChunkLimit": 4000,
"mediaMaxMb": 5,
"timeoutSeconds": 500
}
}
}
隐私和权限
Token 安全
机器人令牌相当于密码。如果泄露，立即通过 @BotFather 撤销并重新生成。
群组权限
Telegram 机器人默认启用隐私模式，限制它们接收的消息：
禁用隐私模式
与 @BotFather 对话：/setprivacy
选择你的机器人
选择 Disable
或设为管理员
将机器人添加为群组管理员可以绕过隐私模式限制。
重新添加机器人
更改隐私模式后，必须将机器人从群组移除并重新添加才能生效。
故障排除
原因： 隐私模式已启用，且机器人不是管理员解决方案：
- 与 @BotFather 使用
/setprivacy 禁用隐私模式
- 从群组移除机器人
- 重新添加机器人
- 或将机器人设为管理员
原因： 无法访问 api.telegram.org解决方案：
- 检查 HTTPS/DNS 连接
- 检查防火墙规则
- 考虑使用代理：
{
"channels": {
"telegram": {
"proxy": "socks5://proxy.example.com:1080"
}
}
}
症状： 机器人启动后停止响应解决方案：{
"channels": {
"telegram": {
"network": {
"autoSelectFamily": false
}
}
}
}
多账户支持
运行多个 Telegram 机器人：
{
"channels": {
"telegram": {
"accounts": {
"main": {
"name": "主机器人",
"botToken": "123:abc",
"dmPolicy": "pairing"
},
"work": {
"name": "工作机器人",
"botToken": "456:def",
"dmPolicy": "allowlist",
"allowFrom": [789012345]
}
}
}
}
}
相关资源
