Telegram

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

• /setjoingroups — 允许/拒绝添加到群组
• /setprivacy — 群组可见性行为

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

• 在尝试精简后，setMyCommands failed 仍出现 BOT_COMMANDS_TOO_MUCH，表示菜单仍然超出限制；请减少插件/技能/自定义命令，或禁用 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 伴随网络/获取错误时，通常表示到 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,
}

​

位置和地点

{
  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: "挥手的猫",
  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 可将其禁用。
• 当 Gateway 网关已观察到父消息时，回复/引用/转发的补充上下文会被规范化到一个选定的对话上下文窗口中；已观察消息的缓存位于 OpenClaw SQLite 插件状态中，openclaw doctor --fix 用于导入旧版边车文件。Telegram 每次更新仅包含一个浅层 reply_to_message，因此早于缓存的链只能使用该载荷。
• Telegram 允许列表主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
• 私信历史记录：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 中的数字所有者 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 的传输回退机制重试一次。持续出现网络/提取错误通常表示无法通过 DNS/HTTPS 访问 api.telegram.org。

• getMe returned 401 表示已配置的机器人令牌未通过 Telegram 身份验证。请在 BotFather 中重新复制或生成令牌，然后更新 channels.telegram.botToken、tokenFile、accounts.<id>.botToken 或 TELEGRAM_BOT_TOKEN（默认账户）。
• 启动期间出现 deleteWebhook 401 Unauthorized 也表示身份验证失败；将其视为“没有 Webhook”只会把同一错误令牌导致的失败推迟到后续 API 调用。

• 使用自定义 fetch/代理时，如果 AbortSignal 类型不匹配，Node 22+ 可能会触发立即中止行为。
• 某些主机会优先将 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。
• 日志中的 Polling stall detected 表示默认情况下，长轮询活跃性连续 120 秒未完成后，OpenClaw 会重启轮询并重建传输。
• 当正在运行的轮询账户在启动宽限期后尚未完成 getUpdates、正在运行的 Webhook 账户在启动宽限期后尚未完成 setWebhook，或上次成功的轮询传输活动已过期时，openclaw channels status --probe 和 openclaw doctor 会发出警告。
• 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

• 默认情况下，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，请先保持危险标志关闭——该范围默认已允许。

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