企业官网建设流程全解析

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

本指南围绕 OpenClaw（中文社区版）中 Telegram 通道的完整接入与运维展开，覆盖从 BotFather 申请令牌到网关配对放行的全流程，并深入讲解 DM 策略、群组策略、@提及门控、草稿流式输出、论坛话题隔离、webhook 模式等核心配置。读完本文，你将能够独立完成 Telegram 机器人的部署、权限模型设计、消息动作编排与常见故障排查，并理解这些能力背后的源码实现。

通道概览与运行模型

OpenClaw 的 Telegram 通道基于 grammY）。

从运行时行为看，Telegram 通道由gateway 进程持有（owned by the gateway process），路由是确定性的：Telegram 的入站消息必然回复回 Telegram，模型不会自行选择回复通道。入站消息会被归一化为共享的 channel envelope（通道信封），携带回复元数据与媒体占位符。群组会话按群组 ID 隔离；论坛话题（forum topics）会在会话键上追加:topic:<threadId>保持隔离。私聊消息可携带message_thread_id，OpenClaw 使用线程感知的会话键路由，并在回复时保留线程 ID。

值得注意的限制：Telegram Bot API不支持已读回执，因此sendReadReceipts对 Telegram 通道不生效。

快速接入：从 BotFather 到首次配对

第一步：在 BotFather 创建机器人

在 Telegram 中搜索@BotFather（务必确认 handle 精确为@BotFather），运行/newbot，按提示完成创建并保存 token。这一步是唯一需要人工完成的 Telegram 侧前置操作。

第二步：配置 token 与 DM 策略

在 OpenClaw 配置中启用通道并填入 token：

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

环境变量兜底：TELEGRAM_BOT_TOKEN=...（仅对默认账号生效）。

关于 token 的解析优先级，源码中有明确的"账号感知"顺序（见 src/telegram/token.ts）：

1. channels.telegram.accounts.<id>.tokenFile（账号级 token 文件，最高优先级）
2. channels.telegram.accounts.<id>.botToken（账号级 token）
3. channels.telegram.tokenFile（通道级 token 文件，仅默认账号）
4. channels.telegram.botToken（通道级 token，仅默认账号）
5. 环境变量TELEGRAM_BOT_TOKEN（仅默认账号）

也就是说，配置值优先于环境变量，且TELEGRAM_BOT_TOKEN只作用于默认账号；多账号场景必须使用accounts.*配置。若使用tokenFile且文件不存在或读取失败，会记录日志并以none作为 token 来源返回。

第三步：启动 gateway 并完成首次配对

openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram <CODE>

配对码（pairing code）1 小时后过期。Telegram 通道的默认 DM 策略即为pairing（配对制）。

第四步：将机器人加入群组

把机器人添加到群组后，按你的访问模型配置channels.telegram.groups与groupPolicy。

Telegram 侧设置（Bot 与群组）

隐私模式与群组可见性

Telegram 机器人默认开启Privacy Mode（隐私模式），这会限制机器人能接收到的群组消息。若希望机器人看到全部群组消息，二选一：

• 通过/setprivacy关闭隐私模式；
• 将机器人设为群组管理员。

切换隐私模式后，需要在每个群组中先移除再重新添加机器人，Telegram 才会应用变更。

群组权限

管理员状态在 Telegram 群组设置中控制。作为管理员的机器人能收到全部群组消息，适合"常驻群组"（always-on group）的行为模式。

常用的 BotFather 开关

• /setjoingroups：允许/禁止被加入群组
• /setprivacy：控制群组消息可见性

访问控制与激活策略

DM 策略（私聊访问控制）

channels.telegram.dmPolicy控制私聊访问，取值：

channels.telegram.allowFrom接受数值型 Telegram 用户 ID；telegram:/tg:前缀会被接受并归一化。onboarding 向导还支持@username输入并解析为数值 ID。从源码看（src/telegram/targets.ts），内部前缀（如telegram:group:<id>这类会话键遗留形式）也会被循环剥离归一化。

查找自己的 Telegram 用户 ID

推荐的安全方式（不依赖第三方 bot）：

1. 给机器人发一条私聊消息；
2. 运行openclaw logs --follow；
3. 读取日志中的from.id。

官方 Bot API 方式：

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

第三方方式（隐私性较差）：@userinfobot或@getidsbot。

群组策略与群组白名单

群组侧有两个相互独立的控制维度：

1. 允许哪些群组（channels.telegram.groups）
   • 未配置groups：所有群组都允许；
   • 配置了groups：作为白名单生效（显式 ID 或"*"）。
2. 群组内允许哪些发送者（channels.telegram.groupPolicy）
   • open（开放）
   • allowlist（默认，白名单）
   • disabled（关闭）

groupAllowFrom用于群组发送者过滤；若未设置，Telegram 通道会回退使用allowFrom。

示例：允许某个特定群组中的任意成员发言（无需 @提及）：

{ channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, }

@提及行为（mention behavior）

群组回复默认要求 @提及。提及可来自：

• 原生的@botusername提及，或
• agents.list[].groupChat.mentionPatterns与messages.groupChat.mentionPatterns中的提及模式。

会话级命令开关（仅更新会话状态，持久化请用配置）：

• /activation always
• /activation mention

持久化配置示例（全局取消 @提及门控）：

{ channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, }

获取群组 chat ID 的三种方式：把群消息转发给@userinfobot/@getidsbot、从openclaw logs --follow读chat.id、或直接查看 Bot APIgetUpdates返回。

草稿流式输出：Telegram 专属的"打字中"体验

OpenClaw 可以用 Telegram 的**草稿气泡（draft bubbles）**流式发送部分回复（sendMessageDraft）。其实现见 src/telegram/draft-stream.ts：草稿最多4096 字符（TELEGRAM_DRAFT_MAX_CHARS），默认节流间隔300ms，超出上限会停止流式更新以避免持续发送失败请求或截断预览。

启用草稿流式输出需要同时满足：

• channels.telegram.streamMode不为"off"（默认"partial"）；
• 私聊场景；
• 入站更新包含message_thread_id；
• 机器人已启用话题（getMe().has_topics_enabled）。

三种模式：

draftChunk在 block 模式下的默认值（见 src/telegram/draft-chunking.ts）：

• minChars: 200
• maxChars: 800
• breakPreference: "paragraph"

其中maxChars会被channels.telegram.textChunkLimit钳制（clamped）——源码中maxChars = Math.min(maxRequested, textLimit)，breakPreference支持paragraph/newline/sentence，其他取值回退为paragraph。

注意：草稿流式输出仅限私聊，群组/频道不使用草稿气泡。若希望提前发送真实的 Telegram 消息而非草稿更新，使用块流式（channels.telegram.blockStreaming: true）。

Telegram 专属的推理流：

• /reasoning stream：生成过程中将推理内容发送到草稿气泡；
• 最终答案发送时不带推理文本。

格式化与 HTML 回退

出站文本使用 Telegramparse_mode: "HTML"。从源码看（src/telegram/format.ts），OpenClaw 先把模型输出的 Markdown 解析为 IR（中间表示），再渲染为 Telegram 安全的 HTML，映射关系包括：<b>（粗体）、<i>（斜体）、<s>（删除线）、<code>（行内代码）、<pre><code>（代码块）、<tg-spoiler>（剧透）、<blockquote>（引用）。文本中的&、<、>会被转义，链接 href 属性还会转义引号。

• Markdown 风格文本渲染为 Telegram 安全的 HTML；
• 模型输出的原始 HTML 会被转义，减少 Telegram 解析失败；
• 若 Telegram 拒绝解析后的 HTML，OpenClaw自动以纯文本重试。

链接预览默认开启，可用channels.telegram.linkPreview: false关闭。

原生命令、自定义命令与设备配对

命令菜单注册

Telegram 命令菜单在启动时通过setMyCommands注册。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通常意味着到api.telegram.org的出站 DNS/HTTPS 被阻断。

设备配对命令（device-pair 插件）

安装device-pair插件后：

1. /pair生成本机配对码；
2. 在 iOS 应用中粘贴配对码；
3. /pair approve批准最近一次待处理的配对请求。

更多细节见 配对文档。

内联按钮与消息动作

内联按钮作用域

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

按账号覆盖：

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

作用域取值：off、dm、group、all、allowlist（默认）。源码实现（src/telegram/inline-buttons.ts）确认了默认值为allowlist，且遗留数组写法capabilities: ["inlineButtons"]会映射为inlineButtons: "all"。

消息动作示例（携带按钮）：

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

按钮点击回调会作为文本传给 Agent，格式为：callback_data: <value>。

面向 Agent 与自动化的 Telegram 消息动作

核心工具动作：

• sendMessage（to、content、可选mediaUrl、replyToMessageId、messageThreadId）
• react（chatId、messageId、emoji）
• deleteMessage（chatId、messageId）
• editMessage（chatId、messageId、content）

通道消息动作提供友好别名（send、react、delete、edit、sticker、sticker-search）。发送目标支持chatId:topicId、chatId:topic:<topicId>以及纯 chatId/@username 形式（解析逻辑见 src/telegram/targets.ts）。

动作门控配置：

• channels.telegram.actions.sendMessage
• channels.telegram.actions.editMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker（默认：禁用）

关于反应移除语义，参考 Reactions 文档。

回复线程标签

Telegram 支持在生成的输出中使用显式回复线程标签：

• [[reply_to_current]]：回复触发消息；
• [[reply_to:<id>]]：回复指定 Telegram 消息 ID。

channels.telegram.replyToMode控制处理方式：off（默认）、first、all。注意：off会关闭隐式回复线程，但显式[[reply_to_*]]标签仍然生效。

论坛话题与线程行为

论坛超级群组（forum supergroups）：

• 话题会话键追加:topic:<threadId>；
• 回复与"正在输入"状态都指向话题线程；
• 话题配置路径：channels.telegram.groups.<chatId>.topics.<threadId>。

通用话题（General topic，threadId=1）特殊处理：

• 消息发送时省略message_thread_id（Telegram 会拒绝sendMessage(...thread_id=1)）；
• "正在输入"动作仍携带message_thread_id。

话题继承：话题条目继承群组设置，除非被显式覆盖（requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy）。

模板上下文包含：

• MessageThreadId
• IsForum

私聊线程行为：带message_thread_id的私聊仍走 DM 路由，但使用线程感知的会话键与回复目标。

音频、视频与贴纸

音频消息

Telegram 区分语音消息（voice note）与音频文件（audio file）。

• 默认按音频文件行为发送；
• 在 Agent 回复中加标签[[audio_as_voice]]强制以语音消息发送。

消息动作示例：

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

从源码看（src/telegram/voice.ts），OpenClaw 会校验媒体是否为语音兼容格式（通过isVoiceCompatibleAudio判断）；若请求了语音但媒体不兼容，会记录日志并回退为音频文件发送。

视频消息

Telegram 区分视频文件（video file）与视频笔记（video note）。

{ action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, }

视频笔记不支持字幕（caption），提供的消息文本会单独发送。

贴纸

入站贴纸处理：

• 静态 WEBP：下载并处理（占位符<media:sticker>）；
• 动图 TGS：跳过；
• 视频 WEBM：跳过。

贴纸上下文字段：Sticker.emoji、Sticker.setName、Sticker.fileId、Sticker.fileUniqueId、Sticker.cachedDescription。

贴纸缓存文件：~/.openclaw/telegram/sticker-cache.json（源码中路径由STATE_DIR/telegram/sticker-cache.json拼接而来，见 src/telegram/sticker-cache.ts）。贴纸在可能时仅描述一次并缓存，减少重复的视觉模型调用；缓存支持按描述、emoji、贴纸集名的模糊搜索打分排序。

启用贴纸动作：

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

发送贴纸：

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

搜索已缓存贴纸：

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

反应通知（Reaction Notifications）

Telegram 反应以message_reaction更新到达（与消息 payload 分离）。启用后，OpenClaw 会入队系统事件，例如：

• 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 的反应更新不携带线程 ID：
  • 非论坛群组路由到群组会话；
  • 论坛群组路由到群组的通用话题会话（:topic:1），而非精确的原始话题。

allowed_updates（轮询与 webhook）会自动包含message_reaction。

从源码看（src/telegram/reaction-level.ts），四个级别语义明确：

• off：无 ACK、无 Agent 反应；
• ack：仅启用处理中的 ACK 反应（如 👀）；
• minimal：启用 Agent 反应，指导为"稀疏"；
• extensive：启用 Agent 反应，指导为"宽松"。

由 Telegram 事件触发的配置写入

通道配置写入默认开启（configWrites !== false）。Telegram 触发的写入包括：

• 群组迁移事件（migrate_to_chat_id）自动更新channels.telegram.groups；
• /config set与/config unset（需启用对应命令）。

关闭方式：

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

长轮询 vs Webhook

默认是长轮询。长轮询使用 grammY runner，按聊天/线程维度串行处理；runner sink 的整体并发受agents.defaults.maxConcurrent控制。

Webhook 模式

• 设置channels.telegram.webhookUrl；
• 设置channels.telegram.webhookSecret（设置 webhook URL 时必须提供）；
• 可选channels.telegram.webhookPath（默认/telegram-webhook）；
• 可选channels.telegram.webhookHost（默认127.0.0.1）。

webhook 模式的默认本地监听器绑定127.0.0.1:8787。源码实现（src/telegram/webhook.ts）还揭示了几个关键细节：请求体上限 1MB、读取超时 30 秒、回调处理超时 10 秒、健康检查端点/healthz，以及 webhook 注册时通过setWebhook携带secret_token与allowed_updates。若公网端点不同，请在前面放置反向代理，并将webhookUrl指向公网地址。仅当你确实需要外部入站时才设置webhookHost（例如0.0.0.0）。

限制、重试与 CLI 目标

• channels.telegram.textChunkLimit默认4000（字符）；
• channels.telegram.chunkMode="newline"会优先按段落边界（空行）切分，再按长度切分；
• channels.telegram.mediaMaxMb（默认5）限制入站 Telegram 媒体下载/处理大小；
• channels.telegram.timeoutSeconds覆盖 Telegram API 客户端超时（未设置时使用 grammY 默认值）；
• 群组上下文历史用channels.telegram.historyLimit或messages.groupChat.historyLimit（默认50；0表示禁用）；
• 私聊历史控制：channels.telegram.dmHistoryLimit、channels.telegram.dms["<user_id>"].historyLimit；
• 出站 Telegram API 重试策略可通过channels.telegram.retry配置（attempts、minDelayMs、maxDelayMs、jitter）。

CLI 发送目标支持数值 chat ID 或用户名：

openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi"

故障排查速查

机器人不响应非 @提及的群组消息

• 若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通常表示到api.telegram.org的 DNS/HTTPS 不可达。

轮询或网络不稳定

• Node 22+ 搭配自定义 fetch/proxy 时，若 AbortSignal 类型不匹配可能触发立即中止行为；
• 部分主机将api.telegram.org解析为 IPv6 优先，IPv6 出口异常会导致间歇性 Telegram API 故障；
• 验证 DNS 解析：

dig +short api.telegram.org A dig +short api.telegram.org AAAA

更完整的跨通道诊断与修复手册见 通道故障排查。

配置参考汇总（Telegram 专属）

启动与认证：enabled、botToken、tokenFile、accounts.*

访问控制：dmPolicy（pairing | allowlist | open | disabled，默认 pairing）、allowFrom（DM 白名单，数值 ID；open需要"*"）、groupPolicy（open | allowlist | disabled，默认 allowlist）、groupAllowFrom（群组发送者白名单）、groups（按群组默认值 + 白名单，"*"表示全局默认）

群组/话题级字段：

• channels.telegram.groups.<id>.groupPolicy：按群组覆盖 groupPolicy
• 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>.groupPolicy：按话题覆盖 groupPolicy
• channels.telegram.groups.<id>.topics.<threadId>.requireMention：按话题覆盖提及门控

命令与菜单：commands.native、customCommands

按钮能力：capabilities.inlineButtons（off | dm | group | all | allowlist，默认 allowlist）、accounts.<account>.capabilities.inlineButtons

线程与回复：replyToMode（off | first | all，默认off）

流式输出：streamMode（off | partial | block）、draftChunk、blockStreaming

格式化与投递：textChunkLimit（默认 4000）、chunkMode（length默认 /newline）、linkPreview（默认 true）、responsePrefix

媒体与网络：mediaMaxMb（默认 5）、timeoutSeconds、retry（attempts、minDelayMs、maxDelayMs、jitter）、network.autoSelectFamily（Node 22 上默认关闭以避免 Happy Eyeballs 超时）、proxy（SOCKS/HTTP 代理 URL）

Webhook：webhookUrl（需同时设置webhookSecret）、webhookSecret、webhookPath（默认/telegram-webhook）、webhookHost（默认127.0.0.1）

动作门控：actions.sendMessage、actions.editMessage、actions.deleteMessage、actions.reactions、actions.sticker（默认 false）

反应：reactionNotifications（off | own | all，默认own）、reactionLevel（off | ack | minimal | extensive，默认minimal）

写入与历史：configWrites、historyLimit（默认 50）、dmHistoryLimit、dms.*.historyLimit

完整的通道级参数定义可对照 配置参考 - Telegram。

相关文档

• 设备配对（Pairing）：跨设备的配对机制与 Telegram 推荐路径
• 通道路由（Channel routing）：入站消息如何归一化与路由
• 通道故障排查（Troubleshooting）：跨通道诊断与修复手册

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音