媒体与附件

### 照片相册 {#photo-albums}

在一次 `message` 工具调用中发送多个图像附件。OpenClaw 会将连续的照片分组为 Telegram 相册，每个相册最多包含 10 张图片，并保持原始顺序。包含多张照片的自动回复使用相同的分组方式。单张照片，包括最后剩余的一张，会单独发送。

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Trip photos",
  attachments: [
    { type: "image", media: "https://example.com/photo-1.jpg" },
    { type: "image", media: "https://example.com/photo-2.jpg" },
  ],
}

说明文字会放在第一张照片上。超出说明文字限制的文本会作为单独消息跟在相册之后。以文档形式发送的照片、其他媒体类型以及包含内联按钮的消息会保持单独发送，以保留其现有控制和投递行为。

### 音频消息 {#audio-messages}

Telegram 区分语音留言和音频文件。默认：音频文件行为；在代理回复中标记 `[[audio_as_voice]]` 可强制以语音留言方式发送。入站语音留言的转录内容在代理上下文中被标记为机器生成、不可信的文本，但提及检测仍使用原始转录内容，因此受提及门控的语音消息仍可正常工作。

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

### 视频消息 {#video-messages}

Telegram 区分视频文件和视频留言。视频留言不支持说明文字；提供的消息文本会单独发送。

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

### 位置和场所 {#locations-and-venues}

使用现有的 `send` 动作，并附带一个独立的 `location` 对象。坐标会发送原生定位图钉；同时添加 `name` 和 `address` 会发送原生场所卡片。位置发送不能与消息文本或媒体组合。

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  location: {
    latitude: 48.858844,
    longitude: 2.294351,
    accuracy: 12,
    name: "Eiffel Tower",
    address: "Champ de Mars, Paris",
  },
}

### 贴纸 {#stickers}

入站：静态 WEBP 会被下载并处理（占位符 `<media:sticker>`）。当贴纸媒体不可用时，包括动画 TGS 和视频 WEBM，OpenClaw 会使用贴纸的表情符号作为消息文本。如果没有可用的表情符号，则使用 `<media:sticker>`。缓存的描述优先于此回退方式。

贴纸上下文字段：`Sticker.emoji`、`Sticker.setName`、`Sticker.fileId`、`Sticker.fileUniqueId`、`Sticker.cachedDescription`。描述会缓存在 OpenClaw SQLite 插件状态中，以减少重复的视觉调用。

贴纸描述会使用已配置的 `agents.defaults.imageModel`，优先于共享的自动图像模型选择，包括提供商的 MiniMax 图像路由。贴纸描述只使用一个选定的模型，如果该模型失败，则不会尝试已配置的回退列表。失败的描述不会被缓存；通用媒体分析仍可以单独运行，并使用其正常的回退处理。

启用贴纸动作：

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

发送：

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

搜索缓存的贴纸：

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}