夜雨聆风
〖OpenClaw系列〗Telegram 渠道接入
Phase 3 开启：渠道接入实战
AI 大脑已就绪，现在让它连接世界。Phase 3 将覆盖主流通信渠道：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
本文从 Telegram 开始——它拥有完善的 Bot API、活跃的开发者生态，是接入 OpenClaw 的最佳起点。
为什么先从 Telegram 开始
如果你在犹豫该先接哪个渠道，看完这张表就有答案了。
|
|
|
|
|
|
|
|---|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Telegram 的独特优势：零门槛、Bot API 最完善、支持 Markdown 富文本、群组+论坛主题天然适合多话题管理。这些特性让它成为学习渠道接入的最佳第一站——上手快、功能全、踩坑少。
Telegram Bot 创建流程
第一步：注册 Bot
打开 Telegram，搜索 @BotFather，按以下步骤操作：
1. 发送 /newbot2. 输入 Bot 名称（如：OpenClaw助手）3. 输入 Bot 用户名（必须以 bot 结尾，如：myopenclaw_bot）4. 保存返回的 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）关键配置命令：
/setdescription - 设置 Bot 描述/setabouttext - 设置关于文本/setuserpic - 设置头像/setcommands - 设置命令列表第二步：配置命令菜单
向 @BotFather 发送 /setcommands，选择你的 Bot，然后输入：
start - 开始对话help - 获取帮助models - 查看可用模型reset - 重置当前会话status - 查看系统状态这些命令会自动显示在 Telegram 的输入框菜单中。
整个 Bot 创建过程其实就是这 4 步——下次再做新的 Bot，照图按顺序走一遍就行：
OpenClaw Telegram 配置详解
最小可用配置
{ channels: { telegram: { enabled: true, botToken: "${TELEGRAM_BOT_TOKEN}", // 允许所有用户私聊 dmPolicy: "open", allowFrom: ["*"] } }}配置说明：
-
botToken: BotFather 提供的 Token，建议使用环境变量 -
dmPolicy: 私聊策略，open允许所有人，pairing需要配对，allowlist仅允许白名单 -
allowFrom: 允许的用户ID列表，["*"]表示不限制
生产级配置
{ channels: { telegram: { enabled: true, botToken: "${TELEGRAM_BOT_TOKEN}", // ========== 基础策略 ========== dmPolicy: "allowlist", // 白名单模式 allowFrom: [123456789, 987654321], // 允许的用户ID // ========== 群组配置 ========== groupPolicy: "allowlist", // 群组白名单 groupAllowFrom: [-1001234567890], // 允许的群组ID // ========== 消息处理 ========== historyLimit: 50, // 保留历史消息数 textChunkLimit: 4000, // 单条消息最大长度 // ========== 功能开关 ========== actions: { reactions: true, // 启用表情回应 sendMessage: true, // 允许发送消息 deleteMessage: false, // 禁止删除消息 editMessage: true // 允许编辑消息 }, // ========== 连接方式 ========== // 方式1: Long Polling（默认，无需公网IP） // 方式2: Webhook（需要公网HTTPS） webhookUrl: "https://your-domain.com/webhook", webhookSecret: "${TELEGRAM_WEBHOOK_SECRET}" } }}多账号配置
支持同时运行多个 Telegram Bot：
{ channels: { telegram: { enabled: true, // 默认账号 botToken: "${TELEGRAM_BOT_TOKEN_1}", dmPolicy: "allowlist", allowFrom: [123456789], // 额外账号 accounts: { support: { name: "客服助手", botToken: "${TELEGRAM_BOT_TOKEN_2}", dmPolicy: "open", allowFrom: ["*"], agentId: "support" // 绑定到 support Agent }, coding: { name: "编程助手", botToken: "${TELEGRAM_BOT_TOKEN_3}", allowFrom: [111222333], agentId: "coding" // 绑定到 coding Agent } } } }}消息类型支持
文本消息
基础功能，支持 Markdown 格式：
{ channels: { telegram: { markdown: { enabled: true, // Telegram 原生 MarkdownV2 // 支持 **粗体**、__斜体__、`代码`、```代码块``` } } }}媒体消息
{ channels: { telegram: { // 媒体大小限制（MB） mediaMaxMb: 20, // 支持的消息类型 actions: { sticker: true, // 贴纸 sendPoll: true // 投票 } } }}OpenClaw 支持处理的媒体：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
把这 4 类媒体的处理方式做成卡片速览，对照看更直观——文本是默认能力，无需单独配置：
回调按钮
支持内联键盘交互：
{ channels: { telegram: { capabilities: { inlineButtons: "all" // off | dm | group | all } } }}效果：AI 可以发送带按钮的消息，用户点击后触发回调。
群组与频道支持
群组配置
{ channels: { telegram: { groups: { // 特定群组配置 "my_dev_group": { groupId: -1001234567890, requireMention: true, // 需要 @Bot 才响应 agentId: "coding", // 使用 coding Agent skills: ["exec", "read"], // 启用技能 allowFrom: [111222333] // 群内允许的用户 } } } }}论坛主题（Forum Topic）
Telegram 支持论坛式群组，OpenClaw 可以为每个主题绑定不同 Agent：
{ channels: { telegram: { groups: { "forum_group": { groupId: -1009876543210, topics: { "general": { topicId: 1, agentId: "default" }, "coding": { topicId: 2, agentId: "coding", requireMention: false }, "support": { topicId: 3, agentId: "support" } } } } } }}频道支持
频道（Channel）通常用于广播，OpenClaw 可以作为管理员发布内容：
# 将 Bot 添加为频道管理员# 配置 channelId 到 allowFromTelegram 一共有 3 种”群类型”，Bot 在每种里的默认行为不一样——按照下图分清楚再做配置就不会踩坑：
安全策略：Webhook vs Long Polling
Long Polling（推荐开发/内网）
┌─────────────┐ 长连接 ┌─────────────┐│ OpenClaw │ ◄──────────────► │ Telegram ││ (内网/本地) │ 定期拉取更新 │ 服务器 │└─────────────┘ └─────────────┘优点：
-
无需公网IP或域名 -
无需 HTTPS 证书 -
配置简单，开箱即用
缺点：
-
延迟略高（秒级） -
不适用于大规模部署
Webhook（推荐生产环境）
┌─────────────┐ HTTPS ┌─────────────┐│ Telegram │ ─────────────► │ OpenClaw ││ 服务器 │ 推送消息 │ (公网服务器) │└─────────────┘ └─────────────┘配置：
{ channels: { telegram: { // Webhook 公网地址（必须是HTTPS） webhookUrl: "https://api.example.com/telegram-webhook", // 验证密钥（Telegram回传验证） webhookSecret: "${TELEGRAM_WEBHOOK_SECRET}", // 本地监听配置 webhookHost: "0.0.0.0", webhookPort: 8787, webhookPath: "/telegram-webhook" } }}Webhook 安全验证流程：
1. OpenClaw 注册 Webhook 时提供 secret_token2. Telegram 推送消息时，在 X-Telegram-Bot-Api-Secret-Token 头部携带3. OpenClaw 验证 token 匹配后才处理请求自签名证书
如果没有域名，使用 IP + 自签名证书：
{ channels: { telegram: { webhookUrl: "https://1.2.3.4:8443/webhook", webhookCertPath: "/path/to/self-signed.pem" } }}生成自签名证书：
openssl req -newkey rsa:2048 -sha256 -nodes \ -keyout private.key -x509 -days 365 \ -out cert.pem -subj "/C=US/ST=State/L=City/O=Org/CN=1.2.3.4"总结一下两种方式的取舍——开发用 Polling 省事、生产换 Webhook 求性能：
高级功能
执行审批（Exec Approvals）
在 Telegram 中审批敏感操作：
{ channels: { telegram: { execApprovals: { enabled: true, approvers: [123456789], // 审批人用户ID agentFilter: ["coding"], // 仅 coding Agent 需要审批 target: "both" // dm | channel | both } } }}效果：当 AI 需要执行危险操作（如删除文件）时，发送带「批准/拒绝」按钮的消息给审批人。
流式响应
{ channels: { telegram: { // 流式模式 streaming: "block", // off | partial | block | progress // 分块大小 draftChunk: { tokens: 50, // 每50 tokens更新一次 maxEditsPerMinute: 20 } } }}|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
反应通知
{ channels: { telegram: { // 表情回应通知 reactionNotifications: "all", // off | own | all // 反应级别 reactionLevel: "minimal" // off | ack | minimal | extensive } }}踩坑
坑1：Bot 收不到消息
现象：配置完成，但 Bot 不响应
排查：
# 1. 检查 Bot Token 是否正确curl "https://api.telegram.org/bot<TOKEN>/getMe"# 2. 检查 Gateway 日志openclaw logs | grep telegram# 3. 检查 allowFrom 配置# dmPolicy=allowlist 时必须配置 allowFrom解决：
{ channels: { telegram: { // 开发阶段使用 open 模式 dmPolicy: "open", allowFrom: ["*"] } }}坑2：群组中 Bot 不响应
现象：私聊正常，群组中无反应
原因：
-
Bot 未被添加为群组成员 -
requireMention: true但未 @Bot -
groupAllowFrom未包含该群组
解决：
{ channels: { telegram: { // 获取群组ID的方法： // 1. 将 Bot 加入群组 // 2. 发送 /chatid 命令（需开启对应功能） groupAllowFrom: [-1001234567890], groups: { "mygroup": { requireMention: false // 无需@即可响应 } } } }}坑3：Webhook 注册失败
现象：提示 webhook 设置失败
常见原因：
-
URL 不可访问 -
证书无效 -
端口未开放
排查：
# 测试 Webhook 可访问性curl -X POST https://your-domain.com/telegram-webhook \ -H "Content-Type: application/json" \ -d '{"test":"true"}'# 查看 Telegram 返回的错误openclaw logs | grep webhook坑4：消息发送失败（429错误）
现象：频繁出现 Too Many Requests
原因：Telegram Bot API 有频率限制
解决：
{ channels: { telegram: { // 启用重试机制 retry: { maxAttempts: 3, backoffMs: 1000 }, // 限制文本分块频率 blockStreamingCoalesce: { maxEditsPerMinute: 15 } } }}FAQ
Q1: 如何获取用户ID和群组ID？
方法1：使用 @userinfobot
方法2：开启调试日志
# 开启 verbose 日志openclaw logs --level debug# 任何消息都会显示 sender ID 和 chat ID方法3：配置 open 模式临时获取
{ channels: { telegram: { dmPolicy: "open", allowFrom: ["*"] } }}然后查看日志中的 ID。
Q2: 如何实现多语言支持？
{ agents: { list: [ { id: "telegram-cn", systemPrompt: "你用中文回复" }, { id: "telegram-en", systemPrompt: "You reply in English" } ] }, channels: { telegram: { accounts: { cn: { agentId: "telegram-cn" }, en: { agentId: "telegram-en" } } } }}Q3: 如何限制 Bot 只响应特定话题？
{ channels: { telegram: { groups: { "dev_forum": { topics: { "ai_help": { topicId: 5, enabled: true } }, // 其他话题不响应 enabled: false } } } }}Q4: 如何备份和恢复 Bot 配置？
# 导出配置openclaw config export --format json > telegram-config.json# 导入配置openclaw config import telegram-config.json# 或使用环境变量管理export TELEGRAM_BOT_TOKEN="xxx"openclaw start总结
本文详细讲解了 Telegram 渠道接入：
|
|
|
|---|---|
| Bot 创建 |
|
| 基础配置 |
|
| 群组支持 |
|
| 连接方式 |
|
| 安全策略 |
|
| 高级功能 |
|
关键认知：
-
开发用 Long Polling，生产用 Webhook -
严格配置 allowFrom 防止未授权访问 -
利用多账号实现不同场景隔离
下一篇预告
第20篇：WhatsApp 渠道接入
对比 Telegram：
-
WhatsApp Business API 申请流程 -
Meta 开发者平台配置 -
消息模板与会话窗口 -
企业级部署注意事项
本文是系列第19篇，Phase 3 开篇。你的 AI 助手已接入全球最大的加密通信平台。
📌 觉得有用？点个「在看」 👇 👨💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货 ⭐ 收藏这篇文章，作为 Telegram 接入的参考手册