Telegram

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

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

• 直接聊天：预览消息 + editMessageText
• 群组/话题：预览消息 + editMessageText

• channels.telegram.streaming 为 off | partial | block | progress（默认：partial）
• progress 会保留一个可编辑的 Status 草稿，并使用工具进度更新它，直到最终送达
• streaming.preview.toolProgress 控制工具/进度更新是否复用同一条已编辑预览消息（默认：预览流式传输启用时为 true）
• streaming.preview.commandText 控制这些工具进度行中的命令/exec 详情：raw（默认，保留已发布行为）或 status（仅工具标签）
• 会检测旧版 channels.telegram.streamMode 和布尔型 streaming 值；运行 openclaw doctor --fix 将它们迁移到 channels.telegram.streaming.mode

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

• 简短私信/群组/topic 预览：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑，除非预览出现后发送过一条可见的非预览消息
• 预览之后跟随可见的非预览输出：OpenClaw 会将完成后的回复作为新的最终消息发送，并清理较旧的预览，因此最终回答会出现在中间输出之后
• 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间

• /reasoning stream 会在生成期间将推理发送到实时预览
• 最终交付后会删除推理预览；当推理应保持可见时，使用 /reasoning on
• 最终回答发送时不包含推理文本

• 类 Markdown 文本会渲染为 Telegram 安全的 HTML。
• 原始模型 HTML 会被转义，以减少 Telegram 解析失败。
• 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。

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

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

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

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

• setMyCommands failed 带 BOT_COMMANDS_TOO_MUCH 表示 Telegram 菜单在裁剪后仍溢出；减少插件/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 令牌。使用当前 BotFather 令牌更新 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: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

• sendMessage（to、content、可选 mediaUrl、replyToMessageId、messageThreadId）
• react（chatId、messageId、emoji）
• deleteMessage（chatId、messageId）
• editMessage（chatId、messageId、content）
• createForumTopic（chatId、name、可选 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 会话键会追加 :topic:<threadId>
• 回复和正在输入目标指向 topic 线程
• topic 配置路径： 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" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

​

音频消息

• 默认：音频文件行为
• 在智能体回复中添加标签 [[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

• ~/.openclaw/telegram/sticker-cache.json

{
  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 会话（:topic:1），而不是确切的来源 topic

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

• Telegram 期望使用 unicode emoji（例如 ”👀”）。
• 使用 "" 可为某个渠道或账户禁用回应。

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

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

• channels.telegram.textChunkLimit 默认值为 4000。
• channels.telegram.chunkMode="newline" 在按长度拆分前会优先选择段落边界（空行）。
• channels.telegram.mediaMaxMb（默认 100）限制入站和出站 Telegram 媒体大小。
• channels.telegram.mediaGroupFlushMs（默认 500）控制 Telegram 相册/媒体组在 OpenClaw 将其作为一条入站消息分发前的缓冲时长。如果相册部分到达较晚，请增大该值；如果要降低相册回复延迟，请减小该值。
• channels.telegram.timeoutSeconds 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。机器人客户端会将配置值限制在低于 60 秒出站文本/typing 请求守卫的范围内，避免 grammY 在 OpenClaw 的传输守卫和回退运行前中止可见回复投递。长轮询仍使用 45 秒的 getUpdates 请求守卫，因此空闲轮询不会被无限期遗弃。
• channels.telegram.pollingStallThresholdMs 默认值为 120000；仅在误报轮询停滞重启时，在 30000 到 600000 之间调节。
• 群组上下文历史使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（默认 50）；0 表示禁用。
• 回复/引用/转发的补充上下文目前按接收内容传递。
• Telegram 允许列表主要用于控制谁可以触发智能体，而不是完整的补充上下文删减边界。
• 私信历史控制：
  • 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
• 用于论坛 topic 的 --thread-id（或使用 :topic: 目标）

• 当 channels.telegram.capabilities.inlineButtons 允许时，将 --presentation 与 buttons 块配合用于内联键盘
• 当机器人可以在该聊天中置顶时，使用 --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 中的数字 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 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单
• deleteMyCommands / setMyCommands 启动调用和 sendChatAction 输入状态调用都有边界限制，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/抓取错误通常表示到 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_PROXY_URL 配置了 OpenClaw 托管代理，并且不存在标准代理环境，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

• 默认已允许 Telegram 媒体下载使用 RFC 2544 基准测试范围应答（198.18.0.0/15）。如果可信的 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