Telegram

• 通过 /setprivacy 禁用隐私模式，或
• 将机器人设为群管理员。

• /setjoingroups 用于允许/拒绝加入群组
• /setprivacy 用于群可见性行为

• direct chats: preview message + editMessageText
• groups/topics: preview message + editMessageText
• direct-chat tool progress: optional native sendMessageDraft status preview when enabled and supported

• channels.telegram.streaming is off | partial | block | progress (default: partial)
• progress keeps one editable status draft for tool progress, clears it at completion, and sends the final answer as a normal message
• streaming.preview.toolProgress controls whether tool/progress updates reuse the same edited preview message (default: true when preview streaming is active)
• streaming.preview.commandText controls command/exec detail inside those tool-progress lines: raw (default, preserves released behavior) or status (tool label only)
• streaming.progress.commentary (default: false) opts into assistant commentary/preamble text in the temporary progress draft
• legacy channels.telegram.streamMode and boolean streaming values are detected; run openclaw doctor --fix to migrate them to channels.telegram.streaming.mode

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "nativeToolProgress": true,
          "nativeToolProgressAllowFrom": ["123456789"]
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

• 短 DM/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原位完成最终编辑
• 分成多条 Telegram 消息的长文本最终回复会尽量复用现有预览作为第一个最终片段，然后只发送剩余片段
• progress 模式下，最终回复会清除状态草稿，并使用普通最终投递，而不是把草稿编辑成答案
• 如果最终编辑在完成文本确认前失败，OpenClaw 会改用普通最终投递并清理过期预览

• /reasoning stream uses a supported channel’s reasoning-preview path; on Telegram, it streams reasoning into the live preview while generating
• the reasoning preview is deleted after final delivery; use /reasoning on when reasoning should remain visible
• final answer is sent without reasoning text

• Markdown 风格文本会被渲染为 Telegram 安全的 HTML。
• 会保留受支持的 Telegram HTML 标签；不受支持的 HTML 会被转义。
• 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会重试为纯文本。

• commands.native: "auto" 为 Telegram 启用原生命令

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git 备份" },
        { command: "generate", description: "创建图像" },
      ],
    },
  },
}

• 名称会被规范化（去除前导 /，转为小写）
• 有效模式：a-z、0-9、_，长度 1..32
• 自定义命令不能覆盖原生命令
• 冲突/重复项会被跳过并记录日志

• 自定义命令只会出现在菜单中；它们不会自动实现行为
• 即使 Telegram 菜单中未显示，插件/技能命令在输入时仍可工作

• setMyCommands failed 且提示 BOT_COMMANDS_TOO_MUCH，表示在裁剪后 Telegram 菜单仍然溢出；请减少插件/技能/自定义命令，或禁用 channels.telegram.commands.native。
• deleteWebhook、deleteMyCommands 或 setMyCommands 失败并提示 404: Not Found，而直接使用 Bot API curl 命令却正常，可能意味着 channels.telegram.apiRoot 被设置成了完整的 /bot<TOKEN> 端点。apiRoot 必须只包含 Bot API 根地址，openclaw doctor --fix 会移除意外附加的 /bot<TOKEN>。
• getMe returned 401 表示 Telegram 拒绝了配置的 bot token。请使用当前的 BotFather token 更新 botToken、tokenFile 或 TELEGRAM_BOT_TOKEN；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
• setMyCommands failed 且出现网络/fetch 错误，通常表示到 api.telegram.org 的出站 DNS/HTTPS 被阻止。

​

设备配对命令（device-pair 插件）

1. /pair 生成设置代码
2. 在 iOS 应用中粘贴代码
3. /pair pending 列出待处理请求（包括角色/范围）
4. 批准请求：
   • /pair approve <requestId> 用于显式批准
   • 当只有一个待处理请求时使用 /pair approve
   • /pair approve latest 用于最近的请求

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

• off
• dm
• group
• all
• allowlist（默认）

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "请选择一个选项：",
  buttons: [
    [
      { text: "是", callback_data: "yes" },
      { text: "否", callback_data: "no" },
    ],
    [{ text: "取消", callback_data: "cancel" }],
  ],
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "打开应用：",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "启动", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, optional mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content or caption, optional presentation inline buttons; button-only edits update reply markup)
• createForumTopic (chatId, name, optional iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker（默认：禁用）

• [[reply_to_current]] 回复触发消息
• [[reply_to:<id>]] 回复特定的 Telegram 消息 ID

• off（默认）
• first
• all

• 话题会话键追加 :topic:<threadId>
• 回复和输入状态会定位到该话题线程
• 话题配置路径： channels.telegram.groups.<chatId>.topics.<threadId>

• 消息发送时省略 message_thread_id（Telegram 会拒绝 sendMessage(...thread_id=1)）
• 输入状态操作仍会包含 message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // 普通话题 → main 代理
            "3": { agentId: "zu" },        // 开发话题 → zu 代理
            "5": { agentId: "coder" }      // 代码审查 → coder 代理
          }
        }
      }
    }
  }
}

​

音频消息

• 默认：音频文件行为
• 在代理回复中使用标签 [[audio_as_voice]] 强制按语音消息发送
• 入站语音消息转写会在代理上下文中被标记为机器生成的、未受信任的文本；提及检测仍使用原始转写，因此带提及门控的语音消息仍可正常工作。

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

​

视频消息

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

​

贴纸

• 静态 WEBP：下载并处理（占位符 <media:sticker>）
• 动画 TGS：跳过
• 视频 WEBM：跳过

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

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

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

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

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

• channels.telegram.reactionNotifications: off | own | all（默认：own）
• channels.telegram.reactionLevel: off | ack | minimal | extensive（默认：minimal）

• own 表示仅用户对机器人发送消息的反应（通过已发送消息缓存尽力判断）。
• 反应事件仍会遵守 Telegram 访问控制（dmPolicy、allowFrom、groupPolicy、groupAllowFrom）；未授权发送者会被丢弃。
• Telegram 不会在反应更新中提供线程 ID。
  • 非论坛群组路由到群组聊天会话
  • 论坛群组路由到群组普通话题会话（:topic:1），而不是精确的原始话题

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• 代理身份表情回退（agents.list[].identity.emoji，否则为 ”👀”）

• Telegram 期望使用 Unicode 表情符号（例如 ”👀”）。
• 使用 "" 可为某个渠道或账号禁用该反应。

• 群组迁移事件（migrate_to_chat_id），用于更新 channels.telegram.groups
• /config set 和 /config unset（需要启用命令）

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

• channels.telegram.textChunkLimit default is 4000.
• channels.telegram.chunkMode="newline" prefers paragraph boundaries (blank lines) before length splitting.
• channels.telegram.mediaMaxMb (default 100) caps inbound and outbound Telegram media size.
• channels.telegram.mediaGroupFlushMs (default 500) controls how long Telegram albums/media groups are buffered before OpenClaw dispatches them as one inbound message. Increase it if album parts arrive late; decrease it to reduce album reply latency.
• channels.telegram.timeoutSeconds overrides Telegram API client timeout (if unset, grammY default applies). Bot clients clamp configured values below the 60-second outbound text/typing request guard so grammY does not abort visible reply delivery before OpenClaw’s transport guard and fallback can run. Long polling still uses a 45-second getUpdates request guard so idle polls are not abandoned indefinitely.
• channels.telegram.pollingStallThresholdMs defaults to 120000; tune between 30000 and 600000 only for false-positive polling-stall restarts.
• group context history uses channels.telegram.historyLimit or messages.groupChat.historyLimit (default 50); 0 disables.
• reply/quote/forward supplemental context is normalized into one selected conversation context window when the gateway has observed the parent messages; the observed-message cache lives in OpenClaw SQLite plugin state, and openclaw doctor --fix imports legacy sidecars. Telegram only includes one shallow reply_to_message in updates, so chains older than the cache are limited to Telegram’s current update payload.
• Telegram allowlists primarily gate who can trigger the agent, not a full supplemental-context redaction boundary.
• DM history controls:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 配置适用于 Telegram 发送辅助工具（CLI/工具/动作）在处理可恢复的出站 API 错误时使用。入站最终回复投递也会对 Telegram 预连接失败使用有界的安全发送重试，但不会重试可能导致可见消息重复的歧义性发送后网络封包。

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

• --poll-duration-seconds（5-600）
• --poll-anonymous
• --poll-public
• 用于论坛话题的 --thread-id（或使用 :topic: 目标）

• --presentation 配合 buttons blocks，用于内联键盘，当 channels.telegram.capabilities.inlineButtons 允许时可用
• --pin 或 --delivery '{"pin":true}'，在机器人可以在该聊天中置顶时请求置顶投递
• --force-document 将出站图片、GIF 和视频作为文档发送，而不是压缩后的照片、动图媒体或视频上传

• channels.telegram.actions.sendMessage=false 会禁用出站 Telegram 消息，包括投票
• channels.telegram.actions.poll=false 会禁用 Telegram 投票创建，但保留普通发送可用

• channels.telegram.execApprovals.enabled（当至少有一个审批者可解析时自动启用）
• channels.telegram.execApprovals.approvers（回退到 commands.ownerAllowFrom 中的数字所有者 ID）
• channels.telegram.execApprovals.target: dm（默认）| channel | both
• agentFilter、sessionFilter

• 如果 requireMention=false，Telegram 隐私模式必须允许完整可见性。
  • BotFather：/setprivacy -> 禁用
  • 然后从群组中移除机器人并重新添加
• 当配置期望接收未提及的群组消息时，openclaw channels status 会发出警告。
• openclaw channels status --probe 可以检查显式的数字群组 ID；通配符 "*" 不能进行成员探测。
• 快速会话测试：/activation always。

• 当存在 channels.telegram.groups 时，群组必须被列出（或包含 "*"）
• 验证机器人是否已加入该群组
• 查看日志：openclaw logs --follow 获取跳过原因

• 授权你的发送者身份（配对和/或数字 allowFrom）
• 即使群组策略为 open，命令授权仍然适用
• setMyCommands failed 且返回 BOT_COMMANDS_TOO_MUCH 表示原生菜单条目过多；请减少插件/技能/自定义命令，或禁用原生菜单
• deleteMyCommands / setMyCommands 启动调用以及 sendChatAction 输入状态调用都有上限，并会在请求超时后通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 api.telegram.org 的 DNS/HTTPS 可达性有问题

• getMe returned 401 表示所配置的机器人令牌发生了 Telegram 身份验证失败。
• 在 BotFather 中重新复制或重新生成机器人令牌，然后更新 channels.telegram.botToken、channels.telegram.tokenFile、channels.telegram.accounts.<id>.botToken，或默认账号的 TELEGRAM_BOT_TOKEN。
• 启动期间的 deleteWebhook 401 Unauthorized 也属于身份验证失败；把它当作“不存在 webhook”只会把同样的坏令牌失败推迟到后续 API 调用。

• Node 22+ + 自定义 fetch/proxy 在 AbortSignal 类型不匹配时可能触发立即中止行为。
• 某些主机会优先将 api.telegram.org 解析到 IPv6；损坏的 IPv6 出站可能导致间歇性的 Telegram API 失败。
• 如果日志包含 TypeError: fetch failed 或 Network request for 'getUpdates' failed!，OpenClaw 现在会把这些错误作为可恢复的网络错误重试。
• 在轮询启动期间，OpenClaw 会为 grammY 复用成功的启动 getMe 探测，因此运行器在第一次 getUpdates 之前不需要第二次 getMe。
• 如果在轮询启动期间 deleteWebhook 因瞬态网络错误失败，OpenClaw 会继续进入长轮询，而不是再次发起一次轮询前控制面调用。若 webhook 仍然处于活动状态，则会以 getUpdates 冲突的形式显现；随后 OpenClaw 会重建 Telegram 传输并重试 webhook 清理。
• 如果 Telegram 套接字按一个较短的固定周期回收，请检查是否设置了较低的 channels.telegram.timeoutSeconds；机器人客户端会将低于出站和 getUpdates 请求保护阈值的配置值进行钳制，但旧版本在该值低于这些阈值时，可能会让每次轮询或回复都中止。
• 如果日志包含 Polling stall detected，OpenClaw 会默认在 120 秒内没有完成长轮询存活信号时重启轮询并重建 Telegram 传输。
• 当正在运行的轮询账号在启动宽限期后尚未完成 getUpdates、正在运行的 webhook 账号在启动宽限期后尚未完成 setWebhook，或者最近一次成功的轮询传输活动已过期时，openclaw channels status --probe 和 openclaw doctor 会发出警告。
• 仅当长时间运行的 getUpdates 调用是健康的，但你的主机仍然报告了错误的轮询停滞重启时，才增加 channels.telegram.pollingStallThresholdMs。持续性的停滞通常表明主机与 api.telegram.org 之间存在代理、DNS、IPv6 或 TLS 出站问题。
• Telegram 也会尊重 Bot API 传输的进程代理环境变量，包括 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 及其小写变体。NO_PROXY / no_proxy 仍可绕过 api.telegram.org。
• 如果 OpenClaw 在服务环境中通过 OPENCLAW_PROXY_URL 配置了托管代理，且未设置标准代理环境变量，Telegram 也会使用该 URL 进行 Bot API 传输。
• 在直连出站/TLS 不稳定的 VPS 主机上，请通过 channels.telegram.proxy 路由 Telegram API 调用：

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ 默认 autoSelectFamily=true（WSL2 例外）。Telegram 的 DNS 结果顺序会优先遵循 OPENCLAW_TELEGRAM_DNS_RESULT_ORDER，然后是 channels.telegram.network.dnsResultOrder，再然后是进程默认值（例如 NODE_OPTIONS=--dns-result-order=ipv4first）；如果都不适用，Node 22+ 会回退到 ipv4first。
• 如果你的主机是 WSL2，或者明确在仅 IPv4 的行为下表现更好，请强制选择地址族：

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544 基准测试范围的地址（198.18.0.0/15）默认已经允许用于 Telegram 媒体下载。如果可信的 fake-IP 或透明代理在媒体下载期间将 api.telegram.org 重写为其他私有/内部/特殊用途地址，则可以选择启用仅 Telegram 绕过：

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 该按需启用选项也可在账号级别使用： channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork。
• 如果你的代理将 Telegram 媒体主机解析到 198.18.x.x，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准范围。

• 环境变量覆盖（临时）：
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• 验证 DNS 结果：

dig +short api.telegram.org A
dig +short api.telegram.org AAAA