8.3 Telegram集成

通过 Telegram Bot API 将 OpenClaw 连接到 Telegram 消息平台，使用 grammY 框架实现。

概述

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

状态

内置支持，生产环境可用。

创建 Telegram Bot

1. 与 @BotFather 对话

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

2. 配置机器人设置

通过 @BotFather 配置额外选项：

# 允许机器人加入群组
/setjoingroups

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

OpenClaw 配置

基础配置

{
  channels: {
    telegram: {
      enabled: true,
      botToken: process.env.TELEGRAM_BOT_TOKEN
    }
  }
}

环境变量

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

访问控制

直接消息策略

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

{
  channels: {
    telegram: {
      enabled: 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: true,
      botToken: process.env.TELEGRAM_BOT_TOKEN,
      dmPolicy: "allowlist",
      allowFrom: [
        123456789,        // 用户 ID
        "@username",      // 用户名
        987654321
      ]
    }
  }
}

群组支持

群组策略

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

获取群组 ID

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

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

群组隐私设置

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

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

流式回复

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

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

streamMode 选项：

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

论坛主题模式（高级）

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

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

内联按钮

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

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

贴纸和表情反应

贴纸支持

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

表情反应

{
  channels: {
    telegram: {
      enabled: 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: true,
      botToken: process.env.TELEGRAM_BOT_TOKEN,
      mode: "polling",  // 默认值
      pollingInterval: 1000  // 毫秒
    }
  }
}

优点：

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

Webhook 模式（生产推荐）

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

{
  channels: {
    telegram: {
      enabled: 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 网关端口
    }
  }
}

设置环境变量：

export TELEGRAM_WEBHOOK_SECRET="your-secure-random-string"

优点：

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

消息格式和限制

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

线程回复

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

replyToMode 选项：

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

重试和错误处理

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

多账号配置

同时运行多个 Telegram 机器人：

{
  channels: {
    telegram: {
      accounts: {
        support: {
          enabled: true,
          botToken: process.env.TELEGRAM_BOT_TOKEN_SUPPORT,
          dmPolicy: "open"
        },
        internal: {
          enabled: 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 速率限制

安全建议

高级配置示例

{
  channels: {
    telegram: {
      enabled: 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: true }
      },
      
      // 流式和格式
      streamMode: "partial",
      parseMode: "MarkdownV2",
      textChunkLimit: 4000,
      
      // 功能控制
      capabilities: {
        inlineButtons: "allowlist"
      },
      inlineButtonsAllowlist: ["confirm", "cancel"],
      
      // 反应和贴纸
      reactionNotifications: "mentions",
      reactionLevel: "minimal",
      stickers: {
        enabled: false
      },
      
      // 线程和重试
      replyToMode: "first",
      retry: {
        maxAttempts: 3,
        backoff: "exponential"
      }
    }
  }
}