OpenClaw Telegram 通道实战指南：Bot API 接入、群组策略、草稿流式输出与 webhook 部署-北京尧图网络

人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载本指南围绕 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_idOpenClaw 使用线程感知的会话键路由并在回复时保留线程 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.tschannels.telegram.accounts.id.tokenFile账号级 token 文件最高优先级channels.telegram.accounts.id.botToken账号级 tokenchannels.telegram.tokenFile通道级 token 文件仅默认账号channels.telegram.botToken通道级 token仅默认账号环境变量TELEGRAM_BOT_TOKEN仅默认账号也就是说配置值优先于环境变量且TELEGRAM_BOT_TOKEN只作用于默认账号多账号场景必须使用accounts.*配置。若使用tokenFile且文件不存在或读取失败会记录日志并以none作为 token 来源返回。第三步启动 gateway 并完成首次配对openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram CODE配对码pairing code1 小时后过期。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控制私聊访问取值取值含义pairing默认配对制需通过 pairing 审批allowlist白名单制open开放要求allowFrom包含*disabled关闭私聊channels.telegram.allowFrom接受数值型 Telegram 用户 IDtelegram:/tg:前缀会被接受并归一化。onboarding 向导还支持username输入并解析为数值 ID。从源码看src/telegram/targets.ts内部前缀如telegram:group:id这类会话键遗留形式也会被循环剥离归一化。查找自己的 Telegram 用户 ID推荐的安全方式不依赖第三方 bot给机器人发一条私聊消息运行openclaw logs --follow读取日志中的from.id。官方 Bot API 方式curl https://api.telegram.org/botbot_token/getUpdates第三方方式隐私性较差userinfobot或getidsbot。群组策略与群组白名单群组侧有两个相互独立的控制维度允许哪些群组channels.telegram.groups未配置groups所有群组都允许配置了groups作为白名单生效显式 ID 或*。群组内允许哪些发送者channels.telegram.groupPolicyopen开放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。三种模式模式行为off不进行草稿流式输出partial基于部分文本高频更新草稿block按channels.telegram.draftChunk分块更新草稿draftChunk在 block 模式下的默认值见 src/telegram/draft-chunking.tsminChars: 200maxChars: 800breakPreference: 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.tsOpenClaw 先把模型输出的 Markdown 解析为 IR中间表示再渲染为 Telegram 安全的 HTML映射关系包括b粗体、i斜体、s删除线、code行内代码、precode代码块、tg-spoiler剧透、blockquote引用。文本中的、、会被转义链接 href 属性还会转义引号。Markdown 风格文本渲染为 Telegram 安全的 HTML模型输出的原始 HTML 会被转义减少 Telegram 解析失败若 Telegram 拒绝解析后的 HTMLOpenClaw自动以纯文本重试。链接预览默认开启可用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插件后/pair生成本机配对码在 iOS 应用中粘贴配对码/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 消息动作核心工具动作sendMessageto、content、可选mediaUrl、replyToMessageId、messageThreadIdreactchatId、messageId、emojideleteMessagechatId、messageIdeditMessagechatId、messageId、content通道消息动作提供友好别名send、react、delete、edit、sticker、sticker-search。发送目标支持chatId:topicId、chatId:topic:topicId以及纯 chatId/username 形式解析逻辑见 src/telegram/targets.ts。动作门控配置channels.telegram.actions.sendMessagechannels.telegram.actions.editMessagechannels.telegram.actions.deleteMessagechannels.telegram.actions.reactionschannels.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 topicthreadId1特殊处理消息发送时省略message_thread_idTelegram 会拒绝sendMessage(...thread_id1)正在输入动作仍携带message_thread_id。话题继承话题条目继承群组设置除非被显式覆盖requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy。模板上下文包含MessageThreadIdIsForum私聊线程行为带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.tsOpenClaw 会校验媒体是否为语音兼容格式通过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 NotificationsTelegram 反应以message_reaction更新到达与消息 payload 分离。启用后OpenClaw 会入队系统事件例如Telegram reaction added: by Alice (alice) on msg 42配置项channels.telegram.reactionNotificationsoff | own | all默认ownchannels.telegram.reactionLeveloff | 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.chunkModenewline会优先按段落边界空行切分再按长度切分channels.telegram.mediaMaxMb默认5限制入站 Telegram 媒体下载/处理大小channels.telegram.timeoutSeconds覆盖 Telegram API 客户端超时未设置时使用 grammY 默认值群组上下文历史用channels.telegram.historyLimit或messages.groupChat.historyLimit默认500表示禁用私聊历史控制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故障排查速查机器人不响应非提及的群组消息若requireMentionfalseTelegram 隐私模式必须允许完整可见性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.*访问控制dmPolicypairing | allowlist | open | disabled默认 pairing、allowFromDM 白名单数值 IDopen需要*、groupPolicyopen | allowlist | disabled默认 allowlist、groupAllowFrom群组发送者白名单、groups按群组默认值白名单*表示全局默认群组/话题级字段channels.telegram.groups.id.groupPolicy按群组覆盖 groupPolicychannels.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按话题覆盖 groupPolicychannels.telegram.groups.id.topics.threadId.requireMention按话题覆盖提及门控命令与菜单commands.native、customCommands按钮能力capabilities.inlineButtonsoff | dm | group | all | allowlist默认 allowlist、accounts.account.capabilities.inlineButtons线程与回复replyToModeoff | first | all默认off流式输出streamModeoff | partial | block、draftChunk、blockStreaming格式化与投递textChunkLimit默认 4000、chunkModelength默认 /newline、linkPreview默认 true、responsePrefix媒体与网络mediaMaxMb默认 5、timeoutSeconds、retryattempts、minDelayMs、maxDelayMs、jitter、network.autoSelectFamilyNode 22 上默认关闭以避免 Happy Eyeballs 超时、proxySOCKS/HTTP 代理 URLWebhookwebhookUrl需同时设置webhookSecret、webhookSecret、webhookPath默认/telegram-webhook、webhookHost默认127.0.0.1动作门控actions.sendMessage、actions.editMessage、actions.deleteMessage、actions.reactions、actions.sticker默认 false反应reactionNotificationsoff | own | all默认own、reactionLeveloff | ack | minimal | extensive默认minimal写入与历史configWrites、historyLimit默认 50、dmHistoryLimit、dms.*.historyLimit完整的通道级参数定义可对照配置参考 - Telegram。相关文档设备配对Pairing跨设备的配对机制与 Telegram 推荐路径通道路由Channel routing入站消息如何归一化与路由通道故障排查Troubleshooting跨通道诊断与修复手册赞分享人工智能AI Agent即时通讯后端本地部署语音【免费下载链接】openclaw-cn中文社区版OpenClaw同原版保持定期更新已内置钉钉、企业微信、飞书、QQ、微信以及国内网络环境优化。你的专属个人AI助手。支持所有操作系统和平台。项目地址https://gitcode.com/gh_mirrors/op/openclaw-cn点击查看免费下载相关推荐OpenClaw 接入 ClickClackbot-token 通道配置、目标语法与群组策略全解OpenClaw 接入 ClickClackbot token 通道配置、目标语法与群组策略全解本文基于 OpenClaw 官方渠道文档 docs/chanAI 应用AI Agent交互助手后端即时通讯网关OpenClaw 的 grammY 集成Telegram Bot API 通道的架构、配置与实战OpenClaw 的 grammY 集成Telegram Bot API 通道的架构、配置与实战导读本文深入剖析 OpenClaw本仓库为中文社区版 o人工智能AI Agent即时通讯后端本地部署语音cloudflare_temp_email 接入 Telegram Bot从 Bot 创建、Webhook 配置到邮件推送与 Mini App 部署实战cloudflare_temp_email 接入 Telegram Bot从 Bot 创建、Webhook 配置到邮件推送与 Mini App 部署实战本指后端前端上一篇把真实城市搬进 Minecraft用 Arnis 生成真实世界的三步上手下一篇探索gruvbox-factory的两种调色板Panther Pink与Snoopy White使用技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenClaw Telegram 通道实战指南：Bot API 接入、群组策略、草稿流式输出与 webhook 部署

相关推荐

OpenShell：跨平台终端体验重构框架，统一Linux/macOS/Windows/WSL开发工作流

Cisco Packet Tracer校园网组网实验：VLAN划分、Trunk与RIP配置详解

Ceph MON命令实战：从状态查看到仲裁恢复的运维指南

更多资讯

Apache Fesod (Incubating) Committer 入职完整指南：接受邀请、签署 iCLA、配置 ASF 账号与邮箱

Linux 内核初始化（九）：RCU 读-复制-更新子系统的初始化全解析

openwifi IQ 采样捕获实战指南：触发条件、AGC/RSSI 状态解析、频率偏移估计与 SNR 分析

OpenShell：用Git管理模块化Shell配置，打造可迁移的个人命令行环境

Cursor插件系统深度解析：加载机制、契约规范与故障排查

stack/queue中的deque

今日更新

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？