Telegram

• disable privacy mode via /setprivacy, or
• make the bot a group admin.

• /setjoingroups — allow/deny group adds
• /setprivacy — group visibility behavior

• channels.telegram.streaming 是 off | partial | block | progress（默认值：partial）
• 简短的初始答案预览会经过防抖处理；如果运行仍处于活动状态，则会在有界延迟后物化
• progress 会为工具进度保留一个可编辑的状态草稿，在答案活动早于工具进度到达时显示稳定的状态标签，在完成时清除它，并将最终答案作为普通消息发送
• streaming.preview.toolProgress 控制工具/进度更新是否复用同一条已编辑的预览消息（预览流式传输启用时默认值：true）
• streaming.preview.commandText 控制这些行中的命令/exec 详情：raw（默认值）或 status（仅工具标签）
• streaming.progress.commentary（默认值：false）选择在临时进度草稿中包含助手的评论/前言文本
• 会检测旧版 channels.telegram.streamMode、布尔型 streaming 值和已退役的原生草稿预览键；运行 openclaw doctor --fix 以迁移它们

{
  "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"
        }
      }
    }
  }
}

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

• setMyCommands failed 带有 BOT_COMMANDS_TOO_MUCH，且修剪重试后仍出现，表示菜单仍然溢出；减少插件/skill/自定义命令，或禁用 channels.telegram.commands.native。
• 当直接 Bot API curl 命令可工作，但 deleteWebhook、deleteMyCommands 或 setMyCommands 失败并显示 404: Not Found 时，通常表示 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

• sendMessage（to、content，可选 mediaUrl、replyToMessageId、messageThreadId）
• react（chatId、messageId、emoji）
• deleteMessage（chatId、messageId）
• editMessage（chatId、messageId、content 或 caption，可选 presentation 内联按钮；仅按钮编辑会更新回复标记）
• createForumTopic（chatId、name，可选 iconColor、iconCustomEmojiId）

• [[reply_to_current]]——回复触发消息
• [[reply_to:<id>]]——回复指定消息 ID

​

音频消息

{
  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,
}

​

贴纸

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

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

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

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

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

• channels.telegram.textChunkLimit 默认为 4000；chunkMode="newline" 会在按长度拆分前优先使用段落边界（空行）。
• channels.telegram.mediaMaxMb（默认 100）限制入站和出站媒体大小。
• channels.telegram.mediaGroupFlushMs（默认 500，范围 10-60000）控制相册/媒体组在 OpenClaw 将其作为一条入站消息分发之前缓冲多久。如果相册部分到达较晚，可增大该值；若要降低相册回复延迟，可减小该值。
• channels.telegram.timeoutSeconds 会覆盖 API 客户端超时（未设置时使用 grammY 默认值）。机器人客户端会将配置值限制在 60 秒出站文本/正在输入请求防护以下，避免 grammY 在 OpenClaw 的传输防护和回退运行之前中止可见回复投递。长轮询仍使用 45 秒 getUpdates 请求防护，因此空闲轮询不会被无限期挂起。
• channels.telegram.pollingStallThresholdMs 默认为 120000；仅在误报轮询停滞重启时，才在 30000 到 600000 之间调优。
• 群组上下文历史使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（默认 50）；0 表示禁用。
• 当 Gateway 网关已观察到父消息时，回复/引用/转发补充上下文会规范化为一个选定的对话上下文窗口；已观察消息缓存位于 OpenClaw SQLite 插件状态中，openclaw doctor --fix 会导入旧版 sidecar。Telegram 每次更新只包含一个浅层 reply_to_message，因此早于缓存的链仅限于该载荷。
• Telegram 允许列表主要控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
• 私信历史：channels.telegram.dmHistoryLimit、channels.telegram.dms["<user_id>"].historyLimit。
• channels.telegram.retry 适用于 Telegram 发送辅助函数（CLI/工具/操作）的可恢复出站 API 错误。入站最终回复投递会对连接前失败使用有界安全发送重试，但不会重试可能重复可见消息的模糊发送后网络信封。

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

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

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

• 当 channels.telegram.groups 存在时，必须列出该群组（或包含 "*"）。
• 验证 Bot 在群组中的成员资格。
• 查看 openclaw logs --follow 中的跳过原因。

• 授权你的发送者身份（配对和/或数字 allowFrom）；即使群组策略是 open，命令授权仍然适用。
• setMyCommands failed 带有 BOT_COMMANDS_TOO_MUCH 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单。
• deleteMyCommands / setMyCommands 启动调用和 sendChatAction 输入状态调用有边界限制，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/抓取错误通常表示无法通过 DNS/HTTPS 访问 api.telegram.org。

• getMe returned 401 是已配置 Bot token 的 Telegram 凭证失败。请在 BotFather 中重新复制或重新生成 token，然后更新 channels.telegram.botToken、tokenFile、accounts.<id>.botToken 或 TELEGRAM_BOT_TOKEN（默认账号）。
• 启动期间的 deleteWebhook 401 Unauthorized 也是凭证失败；把它当作“没有 webhook 存在”只会把同一个错误 token 失败推迟到后续 API 调用。

• Node 22+ 搭配自定义 fetch/proxy 时，如果 AbortSignal 类型不匹配，可能触发立即中止行为。
• 某些主机会先把 api.telegram.org 解析到 IPv6；损坏的 IPv6 出站会导致间歇性 API 失败。
• 带有 TypeError: fetch failed 或 Network request for 'getUpdates' failed! 的日志会作为可恢复的网络错误重试。
• 轮询启动期间，OpenClaw 会为 grammY 复用成功的启动 getMe 探测，因此运行器在第一次 getUpdates 之前不需要第二次 getMe。
• 如果轮询启动期间 deleteWebhook 因瞬时网络错误失败，OpenClaw 会继续进入长轮询，而不是发起另一个预轮询控制平面调用。仍然活跃的 webhook 随后会表现为 getUpdates 冲突；OpenClaw 会重建传输并重试 webhook 清理。
• 如果 Telegram 套接字按较短固定周期回收，请检查是否存在较低的 channels.telegram.timeoutSeconds —— Bot 客户端会把低于出站和 getUpdates 请求保护值的配置值钳制住，但较旧版本在此值低于这些保护值时可能会中止每次轮询或回复。
• 日志中的 Polling stall detected 表示 OpenClaw 在默认 120 秒内没有完成长轮询活性后，会重启轮询并重建传输。
• 当正在运行的轮询账号在启动宽限期后还没有完成 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_PROXY_URL，且不存在标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
• 在直接出站/TLS 不稳定的 VPS 主机上，通过代理路由 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，请先保持危险标志关闭 —— 该范围默认已经允许。

• 临时环境覆盖：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