Telegram 实现

Telegram 是 OpenClaw 中最完整的通道实现之一，基于 grammy SDK 构建，支持 Markdown 消息、媒体、按钮和分块发送。

源码位置

src/telegram/
├── send.ts              # 消息发送核心
├── bot.ts               # Bot 初始化和连接
├── messages.ts          # 消息处理和解析
├── media.ts             # 媒体处理
├── commands.ts          # Bot 命令注册
├── reactions.ts         # 消息反应
├── threads.ts           # 线程/话题
├── keyboards.ts         # 内联键盘
├── polling.ts           # Long polling
├── webhook.ts           # Webhook 模式
├── formatting.ts        # 文本格式化
├── rate-limit.ts        # 速率限制
├── retry.ts             # 重试逻辑
└── *.test.ts            # 测试文件

发送消息

Source: src/telegram/send.ts

Telegram 发送的核心是 TelegramSendOpts 和重试机制：

// src/telegram/send.ts (simplified)
interface TelegramSendOpts {
  token: string;              // Bot token
  accountId: string;          // Chat ID
  mediaUrl?: string;          // Optional media attachment
  maxBytes?: number;          // Max media size
  textMode: "markdown" | "html";  // Message format
  threadId?: number;          // Reply to thread/topic
  buttons?: InlineButton[];   // Inline keyboard buttons
}

interface TelegramSendResult {
  messageId: number;
  chatId: number;
}

重试机制

// src/telegram/retry.ts (simplified)
function createTelegramRetryRunner() {
  // Retry with exponential backoff
  // Handle rate-limit (429) responses
  // Respect Retry-After headers
}

Telegram API 有严格的速率限制，createTelegramRetryRunner() 封装了指数退避和 429 响应处理。

Caption 分割

当发送带媒体的消息时，Telegram 对 caption 有长度限制（1024 字符）。如果文本超长，会拆分为：

文本分块

Telegram 的单条消息限制为 4096 字符（OpenClaw 使用 4000 作为安全阈值）。长消息通过 Markdown-aware 分块策略拆分：

// Text chunking for Telegram
// textChunkLimit: 4000
// chunkerMode: "markdown"
// Preserves code blocks, links, formatting across chunks

分块时会保持 Markdown 语法完整性：

• 不在代码块中间断开
• 不在链接中间断开
• 保持列表和标题结构

grammy Bot

Source: src/telegram/bot.ts

Bot 初始化和消息监听：

// src/telegram/bot.ts (simplified)
// Uses grammy Bot API library
// Supports both long polling and webhook modes
// Registers command handlers
// Sets up message listeners

支持两种运行模式：

模式	说明	使用场景
Long Polling	主动拉取更新	开发/本地
Webhook	被动接收推送	生产环境

消息格式化

Source: src/telegram/formatting.ts

Telegram 支持 MarkdownV2 和 HTML 两种格式：

// Telegram format conversion
// Markdown → MarkdownV2 (with proper escaping)
// Markdown → HTML (alternative)
// Special character escaping rules

MarkdownV2 有严格的转义规则，所有特殊字符（_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !）在非格式化位置都需要反斜杠转义。

小结

• 基于 grammy SDK，支持 Long Polling 和 Webhook
• 文本分块限制 4000 字符，使用 Markdown-aware 分块
• 重试机制 处理 429 速率限制和网络错误
• Caption 分割策略处理带媒体的长文本
• MarkdownV2 格式化需要严格的字符转义

下一章：Discord 实现