OpenClaw Telegram集成教程

Telegram 集成是内置功能，使用 grammY 框架与 Telegram Bot API 交互。支持直接消息、群组聊天、内联按钮、贴纸、表情反应、流式回复等丰富功能。

创建 Telegram Bot

1. 与 @BotFather 对话

1. 在 Telegram 中搜索 @BotFather
2. 发送命令 /newbot
3. 按提示设置机器人名称和用户名
4. 获取 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

重要

妥善保管 Bot Token，任何拥有该令牌的人都可以控制您的机器人。

2. 配置机器人设置

通过 @BotFather 配置额外选项：

# 允许机器人加入群组/setjoingroups# 设置隐私模式（群组消息访问权限）/setprivacy# 选择 Disable - 机器人可以接收所有群组消息

OpenClaw 配置

基础配置

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN    }  }}

复制

环境变量

"hljs-keyword">export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

复制

访问控制

直接消息策略

控制谁可以与机器人发起私聊：

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      dmPolicy: "pairing"  // 默认值    }  }}

dmPolicy 选项：

• "pairing"（推荐）：用户需配对审批
• "allowlist"：仅允许指定用户
• "open"：接受所有私聊
• "disabled"：禁用私聊

配对工作流

当用户首次向机器人发送消息时：

# 1. 用户发送消息给机器人# 2. 机器人回复配对码# 3. 管理员查看待审批请求openclaw pairing list# 4. 批准用户（使用 Telegram 用户 ID）openclaw pairing approve telegram:123456789# 或使用配对码openclaw pairing approve --code ABC123# 撤销配对openclaw pairing revoke telegram:123456789

复制

允许列表配置

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      dmPolicy: "allowlist",      allowFrom: [        123456789,        // 用户 ID        "@username",      // 用户名        987654321      ]    }  }}

群组支持

群组策略

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      groupPolicy: "allowlist",  // 默认为 "open"      groups: {        "-1001234567890": { allow: "hljs-keyword">true },  // 群组 ID（超级群组）        "project-team": { allow: "hljs-keyword">true },    // 群组名称        "public-chat": { allow: "hljs-keyword">false }     // 明确拒绝      }    }  }}

复制

获取群组 ID

将机器人添加到群组后，查看 OpenClaw 日志中的群组 ID，或使用以下方法：

• 在群组中发送消息并查看日志
• 使用 Telegram Bot API: getUpdates
• 超级群组 ID 格式：-100xxxxxxxxxx

群组隐私设置

默认情况下，机器人只能看到以 / 开头的命令和 @提及。要让机器人接收所有消息：

# 通过 @BotFather 设置/setprivacy# 选择你的机器人# 选择 Disable

流式回复

Telegram 支持流式输出（逐步更新消息）：

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      streamMode: "partial"  // 默认值    }  }}

复制

streamMode 选项：

• "partial"：实时更新消息（推荐）
• "off"：仅在完成后发送
• "draft"：使用论坛主题显示草稿

论坛主题模式（高级）

使用 Telegram 论坛功能显示流式草稿：

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      streamMode: "draft",      forumTopicId: 123  // 论坛主题 ID    }  }}

内联按钮

控制 AI 助手是否可以创建交互式按钮：

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      capabilities: {        inlineButtons: "allowlist"  // "all" | "allowlist" | "disabled"      },      inlineButtonsAllowlist: [        "confirm_action",        "select_option"      ]    }  }}

复制

贴纸和表情反应

贴纸支持

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      stickers: {        enabled: "hljs-keyword">false,  // 默认禁用        autoCache: "hljs-keyword">true  // 自动缓存贴纸的视觉描述      }    }  }}

复制

表情反应

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      reactionNotifications: "all",  // "all" | "mentions" | "off"      reactionLevel: "minimal"       // "minimal" | "normal" | "expressive"    }  }}

reactionLevel 控制机器人表情反应的频率：

• "minimal"：很少使用反应
• "normal"：适度使用
• "expressive"：频繁使用各种反应

连接模式

Polling 模式（默认）

机器人主动轮询 Telegram 服务器获取更新：

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      mode: "polling",  // 默认值      pollingInterval: 1000  // 毫秒    }  }}

优点：

• ✅ 无需公网 IP
• ✅ 配置简单
• ✅ 适合开发和小规模部署

Webhook 模式（生产推荐）

Telegram 服务器主动推送更新到您的服务器：

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      mode: "webhook",      webhookUrl: "https://your-domain.com/telegram/webhook",      webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET,  // 8-256字符      webhookPath: "/telegram/webhook",  // 默认路径      webhookPort: 3000  // OpenClaw 网关端口    }  }}

设置环境变量：

"hljs-keyword">export TELEGRAM_WEBHOOK_SECRET="your-secure-random-string"

复制

优点：

• ✅ 更低延迟
• ✅ 更高效率
• ✅ 适合大规模部署
• ⚠️ 需要 HTTPS 端点

消息格式和限制

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      textChunkLimit: 4000,     // 单条消息最大字符数      mediaMaxMb: 50,           // 文件大小限制（MB）      parseMode: "MarkdownV2"   // "Markdown" | "MarkdownV2" | "HTML"    }  }}

复制

线程回复

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      replyToMode: "first"  // "off" | "first" | "all"    }  }}

复制

replyToMode 选项：

• "off"：不使用回复功能
• "first"：回复触发消息
• "all"：回复所有相关消息

重试和错误处理

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      retry: {        maxAttempts: 3,        backoff: "exponential",  // "exponential" | "linear" | "fixed"        initialDelay: 1000       // 毫秒      }    }  }}

复制

多账号配置

同时运行多个 Telegram 机器人：

{  channels: {    telegram: {      accounts: {        support: {          enabled: "hljs-keyword">true,          botToken: process.env.TELEGRAM_BOT_TOKEN_SUPPORT,          dmPolicy: "open"        },        internal: {          enabled: "hljs-keyword">true,          botToken: process.env.TELEGRAM_BOT_TOKEN_INTERNAL,          dmPolicy: "allowlist",          allowFrom: [123456789, 987654321]        }      }    }  }}

复制

获取用户 ID

几种方法获取 Telegram 用户 ID：

1. 通过机器人：用户向机器人发送消息，查看 OpenClaw 日志
2. 使用 @userinfobot：转发用户消息给该机器人
3. 使用 @myidbot：获取自己的 ID

故障排查

机器人无响应

• 验证 Bot Token 正确
• 检查 OpenClaw 网关是否运行：openclaw status
• 查看日志：openclaw logs --follow

群组消息收不到

• 确认已将机器人添加到群组
• 检查群组隐私设置（使用 @BotFather 的 /setprivacy）
• 验证群组在 groups 配置中允许

Webhook 失败

• 确认 URL 使用 HTTPS
• 验证 SSL 证书有效
• 检查 webhookSecret 长度在 8-256 字符之间
• 确认端口和路径正确

配对码未生成

• 确认 dmPolicy 设置为 "pairing"
• 检查用户是否已配对：openclaw pairing list

流式回复不工作

• 确认 streamMode 设置为 "partial"
• 检查网络延迟是否过高
• 验证 Telegram API 速率限制

安全建议

安全最佳实践

• 始终使用 pairing 或 allowlist DM 策略
• 定期审查配对用户列表
• 使用环境变量存储 Bot Token，不要硬编码
• 生产环境使用 Webhook 模式并配置强密钥
• 限制群组访问，使用 groupPolicy: "allowlist"
• 禁用不需要的功能（如贴纸、内联按钮）
• 监控日志中的异常访问尝试

高级配置示例

{  channels: {    telegram: {      enabled: "hljs-keyword">true,      botToken: process.env.TELEGRAM_BOT_TOKEN,      mode: "webhook",      webhookUrl: "https://bot.example.com/telegram/webhook",      webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET,            // 访问控制      dmPolicy: "pairing",      groupPolicy: "allowlist",      groups: {        "-1001234567890": { allow: "hljs-keyword">true }      },            // 流式和格式      streamMode: "partial",      parseMode: "MarkdownV2",      textChunkLimit: 4000,            // 功能控制      capabilities: {        inlineButtons: "allowlist"      },      inlineButtonsAllowlist: ["confirm", "cancel"],            // 反应和贴纸      reactionNotifications: "mentions",      reactionLevel: "minimal",      stickers: {        enabled: "hljs-keyword">false      },            // 线程和重试      replyToMode: "first",      retry: {        maxAttempts: 3,        backoff: "exponential"      }    }  }}

最后：多详细信息和完整配置参考（50+ 选项），请访问 官方文档。