Telegram 通道

状态：通过 grammY 为 Bot DMs 和群组提供生产环境支持。默认使用长轮询；Webhook 可选。

快速设置（入门）

使用 @BotFather 创建 Bot 并复制 token。
设置 token：
- 环境变量：TELEGRAM_BOT_TOKEN=...
- 或配置：channels.telegram.botToken: "..."。
- 如果两者都设置，配置优先（环境变量回退仅适用于默认账户）。
启动网关。
DM 访问默认使用配对；首次联系时批准配对代码。

最小配置：

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing"
    }
  }
}

是什么

由网关拥有的 Telegram Bot API 通道。
确定性路由：回复返回 Telegram；模型从不选择通道。
DM 共享智能体的主会话；群组保持隔离（agent:<agentId>:telegram:group:<chatId>）。

设置（快速路径）

1) 创建 Bot token（BotFather）

打开 Telegram 与 @BotFather 对话。
运行 /newbot，然后按照提示操作（名称 + 以 bot 结尾的用户名）。
复制 token 并安全存储。

可选 BotFather 设置：

/setjoingroups — 允许/拒绝将 Bot 添加到群组。
/setprivacy — 控制 Bot 是否可以看到所有群组消息。

2) 配置 token（环境变量或配置）

示例：

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  }
}

环境变量选项：TELEGRAM_BOT_TOKEN=...（适用于默认账户）。如果环境变量和配置都设置，配置优先。

多账户支持：使用 channels.telegram.accounts 配合每账户 token 和可选 name。见网关配置了解共享模式。

启动网关。当 token 可用时（配置优先，环境变量回退）Telegram 启动，且 channels.telegram.enabled 不为 false。
DM 访问默认使用配对。首次联系 Bot 时批准代码。
对于群组：添加 Bot，决定隐私/管理员行为（见下文），然后设置 channels.telegram.groups 来控制提及门控 + 允许列表。

Token + 隐私 + 权限（Telegram 端）

Token 创建（BotFather）

/newbot 创建 Bot 并返回 token（保密）。
如果 token 泄露，通过 @BotFather 撤销/重新生成并更新配置。

群组消息可见性（隐私模式）

Telegram Bot 默认使用隐私模式，限制它们接收哪些群组消息。如果您的 Bot 必须看到所有群组消息，有两个选项：

通过 /setprivacy 禁用隐私模式，或
将 Bot 添加为群组管理员（管理员 Bot 接收所有消息）。

注意： 当您切换隐私模式时，Telegram 要求移除 + 重新添加 Bot 才能使更改生效。

群组权限（管理员权限）

管理员状态在群组内（Telegram UI）设置。管理员 Bot 始终接收所有群组消息，因此如果您需要完整可见性，请使用管理员。

工作原理（行为）

入站消息被规范化到共享通道信封中，包含回复上下文和媒体占位符。
群组回复默认需要提及（原生 @提及或 agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns 中的模式）。
多智能体覆盖：在 agents.list[].groupChat.mentionPatterns 上设置每智能体模式。
回复始终路由回同一个 Telegram 聊天。
长轮询使用 grammY 运行程序进行每聊天排序；整体并发性由 agents.defaults.maxConcurrent 限制。
Telegram Bot API 不支持已读回执；没有 sendReadReceipts 选项。

格式化（Telegram HTML）

出站 Telegram 文本使用 parse_mode: "HTML"（Telegram 支持的标签子集）。
Markdown-ish 输入渲染为Telegram 安全的 HTML（粗体/斜体/删除线/代码/链接）；块元素被展平为带有换行符/项目符号的文本。
模型的原始 HTML 被转义以避免 Telegram 解析错误。
如果 Telegram 拒绝 HTML 有效载荷，OpenClaw 会将同一条消息作为纯文本重试。

命令（原生 + 自定义）

OpenClaw 在启动时向 Telegram 的 Bot 菜单注册原生命令（如 /status、/reset、/model）。您可以通过配置添加自定义命令到菜单：

json5

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

故障排除

日志中的 setMyMyCommands failed 通常意味着出站 HTTPS/DNS 被阻止到 api.telegram.org。
如果看到 sendMessage 或 sendChatAction 失败，检查 IPv6 路由和 DNS。

更多帮助：通道故障排除。

注意：

自定义命令只是菜单条目；除非您在其他地方处理，否则 OpenClaw 不会实现它们。
命令名称被标准化（去除前导 /，小写），必须匹配 a-z、0-9、_（1-32 字符）。
自定义命令不能覆盖原生命令。冲突被忽略并记录。
如果 commands.native 被禁用，只有自定义命令被注册（如果没有则清除）。

限制

出站文本被分块为 channels.telegram.textChunkLimit（默认 4000）。
可选换行分块：设置 channels.telegram.chunkMode="newline" 在长度分块之前按空行（段落边界）拆分。
媒体下载/上传由 channels.telegram.mediaMaxMb 限制（默认 5）。
Telegram Bot API 请求在 channels.telegram.timeoutSeconds 后超时（默认 500 via grammY）。设置得更低以避免长时间挂起。
群组历史上下文使用 channels.telegram.historyLimit（或 channels.telegram.accounts.*.historyLimit），回退到 messages.groupChat.historyLimit。设置为 0 禁用（默认 50）。
DM 历史可以通过 channels.telegram.dmHistoryLimit 限制（用户轮）。每用户覆盖：channels.telegram.dms["<user_id>"].historyLimit。

群组激活模式

默认情况下，Bot 只在群组中回复提及（@botname 或 agents.list[].groupChat.mentionPatterns 中的模式）。要更改此行为：

通过配置（推荐）

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }  // 始终在此群组中回复
      }
    }
  }
}

重要： 设置 channels.telegram.groups 创建允许列表 - 只接受列出的群组（或 "*"）。论坛话题继承其父群组配置（allowFrom、requireMention、skills、prompts），除非您添加每话题覆盖 channels.telegram.groups.<groupId>.topics.<topicId>。

要允许所有群组并始终回复：

json5

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }  // 所有群组，始终回复
      }
    }
  }
}

要保持所有群组的仅提及（默认行为）：

json5

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }  // 或完全省略 groups
      }
    }
  }
}

通过命令（会话级别）

在群组中发送：

/activation always - 回复所有消息
/activation mention - 需要提及（默认）

注意： 命令仅更新会话状态。要跨重启保持持久行为，请使用配置。

获取群组聊天 ID

将群组中的任何消息转发到 Telegram 上的 @userinfobot 或 @getidsbot 查看聊天 ID（负数如 -1001234567890）。

提示： 对于您自己的用户 ID，向 Bot 发送 DM，它会回复您的用户 ID（配对消息），或者一旦命令启用使用 /whoami。

隐私注意： @userinfobot 是第三方 Bot。如果愿意，将 Bot 添加到群组，发送消息，并使用 openclaw logs --follow 读取 chat.id，或使用 Bot API getUpdates。

配置写入

默认情况下，Telegram 允许通过通道事件或 /config set|unset 触发的配置更新。

这发生在：

群组升级为超级群组且 Telegram 发出 migrate_to_chat_id 时（聊天 ID 更改）。OpenClaw 可以自动迁移 channels.telegram.groups。
您在 Telegram 聊天中运行 /config set 或 /config unset（需要 commands.config: true）。

禁用：

json5

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

话题（论坛超级群组）

Telegram 论坛话题包括每条消息的 message_thread_id。OpenClaw：

追加 :topic:<threadId> 到 Telegram 群组会话密钥，使每个话题隔离。
发送输入指示器和回复时使用 message_thread_id，使响应停留在话题中。
通用话题（线程 ID 1）是特殊的：消息发送省略 message_thread_id（Telegram 拒绝它），但输入指示器仍包含它。
在模板上下文中暴露 MessageThreadId + IsForum 用于路由/模板化。
话题特定配置在 channels.telegram.groups.<chatId>.topics.<threadId> 下可用（skills、allowlists、自动回复、系统提示、禁用）。
话题配置继承群组设置（requireMention、allowlists、skills、prompts），除非每话题覆盖。

私有聊天在某些边缘情况下可以包含 message_thread_id。OpenClaw 保持 DM 会话密钥不变，但仍在线程 ID 存在时用于回复/草稿流。

内联按钮

Telegram 支持带回调按钮的内联键盘。

json5

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

每账户配置：

json5

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

范围：

off — 内联按钮禁用
dm — 仅 DM（阻止群组目标）
group — 仅群组（阻止 DM 目标）
all — DM + 群组
allowlist — DM + 群组，但仅允许列表中的发送者（allowFrom/groupAllowFrom，与控制命令相同的规则）

默认：allowlist。旧版：capabilities: ["inlineButtons"] = inlineButtons: "all"。

发送按钮

使用带 buttons 参数的消息工具：

json5

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

当用户点击按钮时，回调数据作为格式为的消息发送回智能体： callback_data: value

配置选项

Telegram 能力可以在两个级别配置（上面显示的对象形式；仍支持旧版字符串数组）：

channels.telegram.capabilities：应用于所有 Telegram 账户的全局默认能力配置，除非被覆盖。
channels.telegram.accounts.<account>.capabilities：每账户能力，覆盖该特定账户的全局默认值。

当所有 Telegram Bot/账户应该行为相同时使用全局设置。当不同 Bot 需要不同行为时使用每账户配置（例如，一个账户只处理 DM，另一个允许在群组中）。

访问控制（DM + 群组）

DM 访问

默认：channels.telegram.dmPolicy = "pairing"。未知发送者收到配对代码；消息在被批准之前被忽略（代码 1 小时后过期）。
批准：
- openclaw pairing list telegram
- openclaw pairing approve telegram <CODE>
配对是用于 Telegram DM 的默认令牌交换。详情：配对
channels.telegram.allowFrom 接受数字用户 ID（推荐）或 @username 条目。它不是 Bot 用户名；使用人类发送者的 ID。向导接受 @username 并在可能时将其解析为数字 ID。

查找您的 Telegram 用户 ID

更安全（无第三方 Bot）：

启动网关并向您的 Bot 发送 DM。
运行 openclaw logs --follow 并查找 from.id。

备用（官方 Bot API）：

向您的 Bot 发送 DM。
使用您的 Bot token 获取更新并读取 message.from.id：
bash
```
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```

第三方（较少隐私）：

向 @userinfobot 或 @getidsbot 发送 DM 并使用返回的用户 ID。

群组访问

两个独立控制：

1. 哪些群组被允许（通过 channels.telegram.groups 的群组允许列表）：

没有 groups 配置 = 允许所有群组
有 groups 配置 = 只允许列出的群组或 "*"
示例："groups": { "-1001234567890": {}, "*": {} } 允许所有群组

2. 哪些发送者被允许（通过 channels.telegram.groupPolicy 的发送者过滤）：

"open" = 允许列表中的所有发送者在允许的群组中可以留言
"allowlist" = 只有 channels.telegram.groupAllowFrom 中的发送者可以留言
"disabled" = 完全不接受群组消息默认是 groupPolicy: "allowlist"（阻止，除非您添加 groupAllowFrom）。

大多数用户想要：groupPolicy: "allowlist" + groupAllowFrom + channels.telegram.groups 中列出的特定群组

长轮询 vs Webhook

默认：长轮询（不需要公共 URL）。
Webhook 模式：设置 channels.telegram.webhookUrl（可选 channels.telegram.webhookSecret + channels.telegram.webhookPath）。
- 本地监听器绑定到 0.0.0.0:8787 并默认服务 POST /telegram-webhook。
- 如果您的公共 URL 不同，使用反向代理并将 channels.telegram.webhookUrl 指向公共端点。

回复线程

Telegram 通过标签支持可选的线程回复：

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

由 channels.telegram.replyToMode 控制：

first（默认）、all、off。

音频消息（语音 vs 文件）

Telegram 区分语音便签（圆形气泡）和音频文件（元数据卡片）。 OpenClaw 默认使用音频文件以保持向后兼容性。

要在智能体回复中强制语音便签气泡，在回复中任何位置包含此标签：

[[audio_as_voice]] — 将音频作为语音便签而非文件发送。

标签从传递的文本中剥离。其他通道忽略此标签。

对于消息工具发送，设置 asVoice: true 与语音兼容的音频 media URL（media 存在时 message 可选）：

json5

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

贴纸

OpenClaw 支持接收和发送 Telegram 贴纸，具有智能缓存。

接收贴纸

当用户发送贴纸时，OpenClaw 根据贴纸类型处理：

静态贴纸（WEBP）： 下载并通过视觉处理。贴纸在消息内容中显示为 <media:sticker> 占位符。
动态贴纸（TGS）： 跳过（Lottie 格式不支持处理）。
视频贴纸（WEBM）： 跳过（视频格式不支持处理）。

模板上下文字段在接收贴纸时可用：

Sticker — 对象，包含：
- emoji — 与贴纸关联的表情符号
- setName — 贴纸集名称
- fileId — Telegram 文件 ID（发送相同的贴纸）
- fileUniqueId — 稳定 ID 用于缓存查找
- cachedDescription — 可用时的缓存视觉描述

贴纸缓存

贴纸通过 AI 的视觉功能处理以生成描述。由于相同的贴纸经常重复发送，OpenClaw 缓存这些描述以避免冗余 API 调用。

工作原理：

首次遇到： 贴纸图像发送到 AI 进行视觉分析。AI 生成描述（例如，"一只热情挥手的卡通猫"）。
缓存存储： 描述与贴纸的文件 ID、表情符号和集名称一起保存。
后续遇到： 当再次看到相同的贴纸时，直接使用缓存描述。图像不会发送到 AI。

缓存位置： ~/.openclaw/telegram/sticker-cache.json

缓存条目格式：

json

{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "一只热情挥手的卡通猫",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}

好处：

通过避免对相同贴纸的重复视觉调用来降低 API 成本
缓存的贴纸响应时间更快（无视觉处理延迟）
基于缓存描述启用贴纸搜索功能

缓存随着贴纸的接收自动填充。不需要手动缓存管理。

发送贴纸

智能体可以使用 sticker 和 sticker-search 操作发送和搜索贴纸。这些默认禁用，必须在配置中启用：

json5

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

发送贴纸：

json5

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

参数：

fileId（必需）— 贴纸的 Telegram 文件 ID。接收贴纸时从 Sticker.fileId 获取，或从 sticker-search 结果获取。
replyTo（可选）— 要回复的消息 ID。
threadId（可选）— 消息线程 ID 用于论坛话题。

搜索贴纸：

智能体可以通过描述、表情符号或集名称搜索缓存的贴纸：

json5

{
  "action": "sticker-search",
  "channel": "telegram",
  "query": "挥手 猫",
  "limit": 5
}

从缓存返回匹配的贴纸：

json5

{
  "ok": true,
  "count": 2,
  "stickers": [
    {
      "fileId": "CAACAgIAAxkBAAI...",
      "emoji": "👋",
      "description": "一只热情挥手的卡通猫",
      "setName": "CoolCats"
    }
  ]
}

搜索在描述文本、表情符号字符和集名称上使用模糊匹配。

带线程的示例：

json5

{
  "action": "sticker",
  "channel": "telegram",
  "to": "-1001234567890",
  "fileId": "CAACAgIAAxkBAAI...",
  "replyTo": 42,
  "threadId": 123
}

流式传输（草稿）

Telegram 可以在智能体生成回复时流式传输草稿气泡。 OpenClaw 使用 Bot API sendMessageDraft（不是真实消息），然后将最终回复作为普通消息发送。

要求（Telegram Bot API 9.3+）：

启用了话题的私有聊天（Bot 的论坛话题模式）。
入站消息必须包含 message_thread_id（私有话题线程）。
流式传输对群组/超级群组/频道被忽略。

配置：

channels.telegram.streamMode: "off" | "partial" | "block"（默认：partial）
- partial：用最新的流式文本更新草稿气泡。
- block：用更大的块更新草稿气泡（分块）。
- off：禁用草稿流式传输。
可选（仅用于 streamMode: "block"）：
- channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }
  - 默认：minChars: 200，maxChars: 800，breakPreference: "paragraph"（钳制到 channels.telegram.textChunkLimit）。

注意：草稿流式传输与块流式传输（通道消息）分开。块流式传输默认关闭，如果您想要早期 Telegram 消息而不是草稿更新，需要 channels.telegram.blockStreaming: true。

推理流（Telegram only）：

/reasoning stream 将推理流式传输到草稿气泡，同时回复正在生成，然后发送最终答案而不带推理。
如果 channels.telegram.streamMode 是 off，推理流被禁用。更多上下文：流式传输 + 分块。

重试策略

出站 Telegram API 调用在瞬态网络/429 错误上重试，使用指数退避和抖动。通过 channels.telegram.retry 配置。见重试策略。

智能体工具（消息 + 反应）

工具：telegram 带 sendMessage 操作（to、content，可选 mediaUrl、replyToMessageId、messageThreadId）。
工具：telegram 带 react 操作（chatId、messageId、emoji）。
工具：telegram 带 deleteMessage 操作（chatId、messageId）。
反应移除语义：见/tools/reactions。
工具门控：channels.telegram.actions.reactions、channels.telegram.actions.sendMessage、channels.telegram.actions.deleteMessage（默认：启用），以及 channels.telegram.actions.sticker（默认：禁用）。

反应通知

反应如何工作： Telegram 反应作为单独的 message_reaction 事件到达，而不是消息有效载荷中的属性。当用户添加反应时，OpenClaw：

从 Telegram API 接收 message_reaction 更新
将其转换为系统事件，格式为："Telegram reaction added: {emoji} by {user} on msg {id}"
使用与 regular 消息相同的会话密钥将系统事件加入队列
当下一个消息到达该对话时，系统事件被排出并前置到智能体的上下文

智能体将反应视为对话历史中的系统通知，而不是消息元数据。

配置：

channels.telegram.reactionNotifications触发通知：控制哪些反应
- "off" — 忽略所有反应
- "own" — 当用户对 Bot 消息做出反应时通知（尽力而为；内存中）（默认）
- "all" — 通知所有反应
channels.telegram.reactionLevel：控制智能体的反应能力
- "off" — 智能体不能对消息做出反应
- "ack" — Bot 发送确认反应（👀 在处理时）（默认）
- "minimal" — 智能体可以谨慎反应（指南：每 5-10 次交换 1 次）
- "extensive" — 智能体可以在适当时自由反应

论坛群组： 论坛群组中的反应包含 message_thread_id 并使用像 agent:main:telegram:group:{chatId}:topic:{threadId} 这样的会话密钥。这确保反应和同一话题中的消息保持在一起。

示例配置：

json5

{
  channels: {
    telegram: {
      reactionNotifications: "all",  // 查看所有反应
      reactionLevel: "minimal"        // 智能体可以谨慎反应
    }
  }
}

要求：

Telegram Bot 必须明确在 allowed_updates 中请求 message_reaction（OpenClaw 自动配置）
对于 Webhook 模式，反应包含在 Webhook allowed_updates 中
对于轮询模式，反应包含在 getUpdates allowed_updates 中

传递目标（CLI/cron）

使用聊天 ID（123456789）或用户名（@name）作为目标。
示例：openclaw message send --channel telegram --target 123456789 --message "hi"。

故障排除

Bot 不回复群组中的非提及消息：

如果您设置 channels.telegram.groups.*.requireMention=false，Telegram 的 Bot API 隐私模式必须禁用。
- BotFather：/setprivacy → 禁用（然后移除 + 重新添加 Bot 到群组）
openclaw channels status 在配置期望未提及的群组消息时显示警告。
openclaw channels status --probe 可以额外检查显式数字群组 ID 的成员资格（它无法审核通配符 "*" 规则）。
快速测试：/activation always（仅会话；使用配置持久化）

Bot 根本看不到群组消息：

如果设置了 channels.telegram.groups，群组必须被列出或使用 "*"
检查 @BotFather 中的隐私设置 → "Group Privacy" 应该关闭
验证 Bot 实际上是成员（不仅仅是管理员但没有读取权限）
检查网关日志：openclaw logs --follow（查找"skipping group message"）

Bot 回复提及但不回复 /activation always：

/activation 命令更新会话状态但不持久化到配置
对于持久行为，将群组添加到 channels.telegram.groups 并设置 requireMention: false

命令如 /status 不起作用：

确保您的 Telegram 用户 ID 已获得授权（通过配对或 channels.telegram.allowFrom）
命令即使在 groupPolicy: "open" 的群组中也需要授权

Node 22+ 上长轮询立即中止（通常带有代理/自定义获取）：

Node 22+ 对 AbortSignal 实例更严格；外来信号可能立即中止 fetch 调用。
升级到规范化中止信号的 OpenClaw 构建，或在可以升级之前在 Node 20 上运行网关。

Bot 启动，然后静默停止响应（或日志 HttpError: Network request ... failed）：

某些主机首先将 api.telegram.org 解析为 IPv6。如果您的服务器没有有效的 IPv6 出站，grammy 可能会卡在纯 IPv6 请求上。
通过启用 IPv6 出站或强制 api.telegram.org 的 IPv4 解析（例如，使用 IPv4 A 记录的 /etc/hosts 条目，或在操作系统 DNS 堆栈中优先 IPv4）修复，然后重启网关。
快速检查：dig +short api.telegram.org A 和 dig +short api.telegram.org AAAA 确认 DNS 返回什么。

配置参考（Telegram）

完整配置：配置

提供商选项：

channels.telegram.enabled：启用/禁用通道启动。
channels.telegram.botToken：Bot token（BotFather）。
channels.telegram.tokenFile：从文件路径读取 token。
channels.telegram.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
channels.telegram.allowFrom：DM 允许列表（id/用户名）。open 需要 "*"。
channels.telegram.groupPolicy：open | allowlist | disabled（默认：allowlist）。
channels.telegram.groupAllowFrom：群组发送者允许列表（id/用户名）。
channels.telegram.groups：每群组默认 + 允许列表（使用 "*" 表示全局默认）。
- channels.telegram.groups.<id>.requireMention：提及门控默认。
- channels.telegram.groups.<id>.skills：技能过滤器（省略 = 所有技能，空 = 无）。
- channels.telegram.groups.<id>.allowFrom：每群组发送者允许列表覆盖。
- channels.telegram.groups.<id>.systemPrompt：群组的额外系统提示。
- channels.telegram.groups.<id>.enabled：在 false 时禁用群组。
- channels.telegram.groups.<id>.topics.<threadId>.*：每话题覆盖（与群组相同的字段）。
- channels.telegram.groups.<id>.topics.<threadId>.requireMention：每话题提及门控覆盖。
channels.telegram.capabilities.inlineButtons：off | dm | group | all | allowlist（默认：allowlist）。
channels.telegram.accounts.<account>.capabilities.inlineButtons：每账户覆盖。
channels.telegram.replyToMode：off | first | all（默认：first）。
channels.telegram.textChunkLimit：出站分块大小（字符）。
channels.telegram.chunkMode：length（默认）或 newline 在长度分块之前按空行（段落边界）拆分。
channels.telegram.linkPreview：切换出站消息的链接预览（默认：true）。
channels.telegram.streamMode：off | partial | block（草稿流式传输）。
channels.telegram.mediaMaxMb：入站/出站媒体限制（MB）。
channels.telegram.retry：出站 Telegram API 调用的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。
channels.telegram.network.autoSelectFamily：覆盖 Node autoSelectFamily（true=启用，false=禁用）。在 Node 22 上默认禁用以避免 Happy Eyeballs 超时。
channels.telegram.proxy：Bot API 调用的代理 URL（SOCKS/HTTP）。
channels.telegram.webhookUrl：启用 Webhook 模式。
channels.telegram.webhookSecret：Webhook secret（可选）。
channels.telegram.webhookPath：本地 Webhook 路径（默认 /telegram-webhook）。
channels.telegram.actions.reactions：门控 Telegram 工具反应。
channels.telegram.actions.sendMessage：门控 Telegram 工具消息发送。
channels.telegram.actions.deleteMessage：门控 Telegram 工具消息删除。
channels.telegram.actions.sticker：门控 Telegram 贴纸操作 — 发送和搜索（默认：false）。
channels.telegram.reactionNotifications：off | own | all — 控制哪些反应触发系统事件（默认：未设置时 own）。
channels.telegram.reactionLevel：off | ack | minimal | extensive — 控制智能体的反应能力（默认：未设置时 minimal）。

Telegram 通道 ​

快速设置（入门） ​

是什么 ​

设置（快速路径） ​

1) 创建 Bot token（BotFather） ​

2) 配置 token（环境变量或配置） ​

Token + 隐私 + 权限（Telegram 端） ​

Token 创建（BotFather） ​

群组消息可见性（隐私模式） ​

群组权限（管理员权限） ​

工作原理（行为） ​

格式化（Telegram HTML） ​

命令（原生 + 自定义） ​

故障排除 ​

限制 ​

群组激活模式 ​

通过配置（推荐） ​

通过命令（会话级别） ​

获取群组聊天 ID ​

配置写入 ​

话题（论坛超级群组） ​

内联按钮 ​

发送按钮 ​

配置选项 ​

访问控制（DM + 群组） ​

DM 访问 ​

查找您的 Telegram 用户 ID ​

群组访问 ​

长轮询 vs Webhook ​

回复线程 ​

音频消息（语音 vs 文件） ​

贴纸 ​

接收贴纸 ​

贴纸缓存 ​

发送贴纸 ​

流式传输（草稿） ​

重试策略 ​

智能体工具（消息 + 反应） ​

反应通知 ​

传递目标（CLI/cron） ​

故障排除 ​

配置参考（Telegram） ​

相关命令 ​

Telegram 通道

快速设置（入门）

是什么

设置（快速路径）

1) 创建 Bot token（BotFather）

2) 配置 token（环境变量或配置）

Token + 隐私 + 权限（Telegram 端）

Token 创建（BotFather）

群组消息可见性（隐私模式）

群组权限（管理员权限）

工作原理（行为）

格式化（Telegram HTML）

命令（原生 + 自定义）

故障排除

限制

群组激活模式

通过配置（推荐）

通过命令（会话级别）

获取群组聊天 ID

配置写入

话题（论坛超级群组）

内联按钮

发送按钮

配置选项

访问控制（DM + 群组）

DM 访问

查找您的 Telegram 用户 ID

群组访问

长轮询 vs Webhook

回复线程

音频消息（语音 vs 文件）

贴纸

接收贴纸

贴纸缓存

发送贴纸

流式传输（草稿）

重试策略

智能体工具（消息 + 反应）

反应通知

传递目标（CLI/cron）

故障排除

配置参考（Telegram）

相关命令