Telegram

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

• /setjoingroups — 允许/禁止被添加到群组
• /setprivacy — 群可见性行为

• channels.telegram.streaming is off | partial | block | progress (default: progress)；set mode: "partial" to stream answer text into the preview instead of a status draft
• short initial answer previews are debounced, then materialized after a bounded delay if the run is still active
• progress keeps one editable status draft for tool progress, shows the stable status label when answer activity arrives before 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 lines: status (default, tool label only) or raw (explicit command text)
• streaming.progress.commentary (default: false) opts into assistant commentary/preamble text in the temporary progress draft
• legacy channels.telegram.streamMode, boolean streaming values, and retired native draft preview keys are detected；run openclaw doctor --fix to migrate them

{
  "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 备份" },
        { command: "generate", description: "创建图像" },
      ],
    },
  },
}

• setMyCommands failed 且在 trim 重试后出现 BOT_COMMANDS_TOO_MUCH，表示菜单仍然超限；减少插件/技能/自定义命令，或禁用 channels.telegram.commands.native。
• deleteWebhook、deleteMyCommands 或 setMyCommands 在直接使用 Bot API curl 命令可工作时却返回 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 内联按钮；仅按钮编辑会更新 reply markup）
• 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,
}

​

位置和场所

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  location: {
    latitude: 48.858844,
    longitude: 2.294351,
    accuracy: 12,
    name: "埃菲尔铁塔",
    address: "战神广场，巴黎",
  },
}

​

贴纸

{
  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
• 代理身份表情兜底（agents.entries.*.identity.emoji，否则为 ”👀”）

• channels.telegram.textChunkLimit 默认 4000；streaming.chunkMode="newline" 优先按段落边界（空行）再按长度拆分。
• channels.telegram.mediaMaxMb（默认 100）限制传入和传出媒体大小。
• 群组上下文历史使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（默认 50）；0 表示禁用。
• 回复/引用/转发的补充上下文会在网关观察到父消息后，规范化到一个已选定的会话上下文窗口中；被观察到的消息缓存保存在 OpenClaw SQLite 插件状态里，openclaw doctor --fix 会导入旧版 sidecar。Telegram 每次更新只包含一个浅层 reply_to_message，因此比缓存更早的链路只能受限于该载荷。
• Telegram allowlist 主要用于限制谁可以触发代理，而不是一个完整的补充上下文脱敏边界。
• DM 历史：channels.telegram.dmHistoryLimit、channels.telegram.dms["<user_id>"].historyLimit。

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 的数字 owner ID）
• channels.telegram.execApprovals.target：dm（默认）| channel | both
• agentFilter、sessionFilter

• 如果 requireMention=false，Telegram 隐私模式必须允许完全可见：BotFather /setprivacy -> Disable，然后将机器人从群组中移除并重新添加。
• 当配置期望接收未提及的群组消息时，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、tokenFile、accounts.<id>.botToken 或 TELEGRAM_BOT_TOKEN（默认账户）。
• 启动期间出现的 deleteWebhook 401 Unauthorized 也属于身份验证失败；将其视为“没有 webhook”只会把同样的坏令牌失败推迟到后续的 API 调用。

• 带有自定义 fetch/proxy 的 Node 22+ 如果 AbortSignal 类型不匹配，可能会触发立即中止行为。
• 某些主机会先将 api.telegram.org 解析到 IPv6；损坏的 IPv6 出站会导致间歇性的 API 失败。
• 带有 TypeError: fetch failed 或 Network request for 'getUpdates' failed! 的日志会作为可恢复的网络错误重试。
• 在轮询启动期间，OpenClaw 会复用成功的启动期 getMe 探测结果给 grammY，因此运行器在第一次 getUpdates 之前不需要第二次 getMe。
• 如果在轮询启动期间 deleteWebhook 因瞬时网络错误而失败，OpenClaw 会继续进入长轮询，而不是再进行一次轮询前的控制平面调用。若 webhook 仍然处于活动状态，随后会在 getUpdates 中表现为冲突；OpenClaw 会重建传输并重试 webhook 清理。
• 日志中的 Polling stall detected 表示 OpenClaw 会在默认 120 秒内没有完成的长轮询存活信号后重启轮询并重建传输。
• openclaw channels status --probe 和 openclaw doctor 会在以下情况发出警告：运行中的轮询账户在启动宽限期后尚未完成 getUpdates、运行中的 webhook 账户在启动宽限期后尚未完成 setWebhook，或者最近一次成功的轮询传输活动已过期。
• 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-only 行为更有效时，强制选择地址族：

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