8.4 grammY框架 - OpenClaw中文社区

grammY 是一个 TypeScript 优先的 Telegram Bot API 客户端，为 OpenClaw 提供 Telegram 集成支持。

概述

OpenClaw 使用 grammY 框架作为唯一的 Telegram 客户端路径。grammY 是一个功能强大的 TypeScript 优先的 Bot API 客户端，内置长轮询和 Webhook 辅助功能、中间件、错误处理和速率限制器。

为什么选择 grammY

TypeScript 优先：原生 TypeScript 支持，提供完整的类型安全
长轮询和 Webhook：内置两种接收消息的方式
中间件系统：灵活的消息处理管道
错误处理：完善的错误处理机制
速率限制：内置速率限制器，避免触发 API 限制

主要功能实现

单一客户端路径

grammY 现在是唯一的 Telegram 客户端，所有 Telegram 相关功能都通过 grammY 实现。

网关集成

monitorTelegramProvider 构建 grammY Bot 实例，处理以下功能：

提及和允许列表门控
通过 getFile/download 下载媒体文件

代理支持

可选的 channels.telegram.proxy 配置通过 grammY 的 client.baseFetch 使用 undici.ProxyAgent。

Webhook 支持

webhook-set.ts：封装 setWebhook/deleteWebhook
webhook.ts：托管回调，包含健康检查和优雅关闭

会话管理

私信（DM）：使用 agent:: 会话
群组：使用 agent::telegram:group: 会话
回复路由回到相同频道

配置选项

配置项包括：

{
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "groups": { /* 群组配置 */ },
      "allowFrom": ["*"],
      "mediaMaxMb": 20,
      "linkPreview": true,
      "proxy": "http://proxy.example.com:8080",
      "webhookSecret": "secret",
      "webhookUrl": "https://example.com/webhook"
    }
  }
}

主要配置项说明

botToken：Telegram Bot Token（必需）
dmPolicy：私信策略（pairing/open/allowlist/disabled）
groups：群组配置对象
allowFrom：允许的用户列表
mediaMaxMb：媒体文件最大大小（MB）
linkPreview：是否启用链接预览
proxy：代理服务器地址
webhookSecret：Webhook 密钥
webhookUrl：Webhook URL

流式草稿模式

可选的 channels.telegram.streamMode 在私有主题聊天中使用 sendMessageDraft（Bot API 9.3+）。

测试

grammY mock 测试覆盖：

私信和群组提及门控
出站消息发送

待解决问题

如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（如 throttler）
添加结构化媒体测试（贴纸、语音消息等）
使 Webhook 监听端口可配置（当前固定为 8787，除非通过网关连接）

常用命令

# 检查 Telegram 渠道状态
openclaw channels status

# 列出配对请求
openclaw pairing list telegram

# 批准配对
openclaw pairing approve telegram <code>

# 设置 Webhook
openclaw telegram webhook-set

# 删除 Webhook
openclaw telegram webhook-delete

提示

grammY 是 OpenClaw 中 Telegram 集成的核心框架。详细的 Telegram 配置和使用方法请参考 Telegram 集成章节。

概述