Telegram 媒体解析器

将 Telegram 消息中的 占位符解析为可下载的文件。

适用场景

当您在 Telegram 消息中（尤其是在回复引用上下文或群组历史记录中）看到 、、、、 或 ，并需要实际查看或分析其内容时。

工作原理

1. 通过 Bot API 临时转发目标消息，以获取文件元数据
2. 从 Telegram 服务器下载该文件
3. 删除转发的副本（清理操作）
4. 返回本地文件路径，供 image 工具或 exec 使用

使用方法

python3 scripts/fetch_media.py 
  --bot-token "$BOT_TOKEN" 
  --chat-id CHAT_ID 
  --message-id MESSAGE_ID 
  [--out /tmp] 
  [--forward-to SELF_CHAT_ID]

参数说明

• --bot-token — Telegram Bot API token（从 OpenClaw 配置中读取：channels.telegram.botToken）
• --chat-id — 消息所在的聊天会话 ID（来自消息上下文，例如 -1001234567890）
• --message-id — 包含媒体内容的消息 ID（来自消息上下文中的 [id:XXXXX]）
• --out — 输出目录（默认值：/tmp）
• --forward-to — 用于临时转发的目标聊天 ID（默认值：与 --chat-id 相同）。建议使用 Bot 所有者的私聊 ID，以避免在群组中显示转发痕迹。

从消息上下文中提取参数

OpenClaw 对 Telegram 消息的格式化示例如下：

[Telegram GroupName id:CHAT_ID topic:N ...] User (USER_ID):  [id:MSG_ID chat:CHAT_ID]

请从此格式中提取 CHAT_ID 和 MSG_ID。

典型工作流程

1. 从消息上下文中提取 chat_id 和 message_id
2. 读取 Bot Token：cat ~/.openclaw/openclaw.json | python3 -c "import sys,json; print(json.load(sys.stdin)['channels']['telegram']['botToken'])"
3. 运行媒体获取脚本
4. 将返回的文件路径传给 image 工具进行视觉分析

支持的媒体类型

图片、文档、视频、动画（GIF）、贴纸、语音消息、视频笔记、音频文件。

限制条件

• Bot 必须是包含目标消息的聊天会话的成员
• 通过 Bot API 无法下载大于 20MB 的文件
• 临时转发的消息可能在被删除前短暂出现在 --forward-to 指定的聊天中
• 为避免在群组聊天中显示转发痕迹，请将 --forward-to 设置为私聊 ID（例如 Bot 所有者的 DM 聊天 ID）