1. 为什么 OpenClaw 接 Telegram 总卡在 Webhook 这一步OpenClaw 接入 Telegram 这件事真正让人头疼的往往不是写代码而是链路里那几个“看不见的环节”BotFather 里点错了按钮、Bot Token 复制时多了空格、Webhook 地址不是 HTTPS、Secret Token 对不上。任何一个环节出问题表现都是一样的——Bot 像死了一样不回消息日志里也看不出所以然。这篇就聚焦这条链路用 BotFather 创建 Bot、拿到 Bot Token、写 OpenClaw 的 config.toml、注册 Webhook、发一条消息验证回调是否真的通了。适合已经把 OpenClaw 跑起来、想把它接到 Telegram 的开发者也适合第一次接触 Telegram Bot 但想一次跑通的人。我会把每一步的命令和配置都写全包括我踩过的坑。另外OpenClaw 调用大模型时需要一套统一的凭证管理我会用 TaoToken 来统一管理 Key 和 API 通道这样 Telegram 渠道、其他渠道、本地调试都走同一套凭证不用到处散落 API Key。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 后面配置里会具体用到。先把整体链路说清楚Telegram 用户发消息 → Telegram 服务器 → 你的 Webhook URLHTTPS→ OpenClaw Gateway → 调用模型 → 回复消息。Webhook 验证失败整条链路就断在第三步。2. 前置准备BotFather 创建 Bot 与 TaoToken 凭证2.1 BotFather 创建 Bot 的完整操作在 Telegram 里搜索BotFather认准蓝色认证标识。进入对话后依次操作发送/newbotBotFather 会先问 Bot 的显示名称比如OpenClaw Assistant再问用户名必须以bot结尾比如openclaw_demo_bot。用户名被占用会提示重试换一个即可。创建成功后BotFather 返回一段这样的内容Use this token to access the HTTP API: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz Keep your token secure and store it safely, it can be used by anyone to control your bot.这串1234567890:ABCdef...就是 Bot Token格式是{bot_id}:{token_string}。它等同于 Bot 的密码谁拿到谁就能控制你的 Bot。复制时注意别把前后空格带进去这是最常见的低级错误。顺手把命令列表也配了发送/setcommands粘贴start - 开始使用 OpenClaw 助手 help - 查看帮助 status - 查看系统状态 clear - 清除对话上下文这样用户在输入框打/就能看到提示体验会好很多。2.2 用 TaoToken 统一管理模型调用凭证OpenClaw 本身负责渠道接入和消息路由真正生成回复要调用大模型。如果每个渠道、每个环境都单独配一份 API Key很快就会乱。我的做法是用 TaoToken 统一管理一个 Key 走统一 API 通道OpenClaw 的模型配置指向它就行。到 https://taotoken.net/api 拿到 API 地址在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后把 Key 存到环境变量不要写进 config.toml 明文。如果你后面要做长期编码或 Agent 场景可以看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想先验证模型通不通用模型对话页最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。3. 可复制配置config.toml 骨架与 Webhook 注册3.1 OpenClaw 的 config.toml 骨架OpenClaw 的 Telegram 渠道配置写在config.toml里。下面这份骨架可以直接改[channels.telegram] enabled true bot_token ${TELEGRAM_BOT_TOKEN} [channels.telegram.webhook] enabled true url https://your-domain.com/api/telegram/webhook secret_token ${TELEGRAM_WEBHOOK_SECRET} [channels.telegram.message] parse_mode MarkdownV2 disable_web_page_preview false [channels.telegram.access] admin_users [123456789] [channels.telegram.features] group_commands true private_only false [model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini几个关键点bot_token和secret_token都用环境变量注入避免明文进版本库base_url指向 TaoToken 的 API 地址api_key用环境变量parse_mode用MarkdownV2格式丰富但要注意转义。对应的.env文件TELEGRAM_BOT_TOKEN1234567890:ABCdefGHIjklMNOpqrsTUVwxyz TELEGRAM_WEBHOOK_SECRETyour-random-secret-string TAOTOKEN_API_KEYsk-your-taotoken-keyTELEGRAM_WEBHOOK_SECRET自己生成一串随机字符串建议用openssl rand -hex 32它用于校验请求确实来自 Telegram。3.2 注册 Webhook 的两种方式方式一用 OpenClaw 自带命令openclaw telegram set-webhook \ --url https://your-domain.com/api/telegram/webhook \ --secret your-random-secret-string方式二直接调 Telegram API方便排查curl -X POST https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook \ -H Content-Type: application/json \ -d { url: https://your-domain.com/api/telegram/webhook, secret_token: your-random-secret-string, allowed_updates: [message, callback_query] }返回{ok:true,result:true,description:Webhook was set}就说明注册成功。注意 URL 必须是 HTTPS端口必须是 443这是 Telegram 的硬性要求。3.3 本地开发怎么拿到 HTTPS 地址本地没有公网 IPWebhook 注册不上去。开发阶段用内网穿透把本地 18789 端口暴露成 HTTPSngrok http 18789ngrok 会输出一个https://xxxx.ngrok.io地址把它填进set-webhook的--url即可。生产环境则用 Nginx 做 SSL 终止把 Telegram 请求转发到本地 Gatewayserver { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; location /api/telegram/webhook { proxy_pass http://127.0.0.1:18789; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } }4. 验证请求确认 Webhook 真的通了4.1 查询 Webhook 当前状态注册完先查状态确认 Telegram 那边记的地址和你预期一致curl https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo返回里重点看这几个字段url是不是你的地址pending_update_count是不是 0last_error_message有没有报错。如果last_error_message显示Wrong response from the webhook: 401 Unauthorized基本就是 Secret Token 对不上。4.2 本地模拟 Telegram 请求在真实消息进来之前先本地模拟一次确认 OpenClaw 的处理逻辑没问题curl -X POST http://localhost:18789/api/telegram/webhook \ -H Content-Type: application/json \ -H X-Telegram-Bot-Api-Secret-Token: your-random-secret-string \ -d { update_id: 12345, message: { message_id: 1, from: {id: 123456789, first_name: Test}, chat: {id: 123456789, type: private}, text: /start } }如果返回 200 且日志里能看到消息被处理说明 Gateway 侧没问题。这一步能帮你把“Telegram 没推过来”和“OpenClaw 处理不了”两类问题分开。4.3 真实消息验证打开 Telegram找到你的 Bot发送/start。正常情况几秒内会收到回复。同时看 Gateway 日志docker logs -f openclaw-gateway日志里应该能看到收到 update、调用模型、发送回复的完整链路。如果模型调用报错检查TAOTOKEN_API_KEY和base_url是否配对如果回复格式乱码多半是 MarkdownV2 转义问题下一节讲。5. 本篇常见错排查5.1 Webhook 注册失败或收不到消息按这个顺序排查先getWebhookInfo看last_error_message再确认 URL 是 HTTPS 且公网可访问用curl -I https://your-domain.com/api/telegram/webhook测然后检查 SSL 证书是否有效浏览器访问不报证书错误才行最后核对 Secret Token 两边是否完全一致包括大小写。如果pending_update_count一直涨说明 Telegram 推了但你的服务没返回 200。看 Nginx 和 Gateway 日志通常是路径写错或服务没起来。5.2 MarkdownV2 转义导致消息发送失败Telegram 的 MarkdownV2 要求对_ * [ ] ( ) ~ \ # - | { } . !这些字符转义。AI 回复里出现C、1.5、a_b这类内容时不转义就会报400 Bad Request: cant parse entities。OpenClaw 内置了转义函数但如果你自己拼消息记得处理SPECIAL r_*[]()~#-|{}.! def escape_md_v2(text: str) - str: return .join(f\\{c} if c in SPECIAL else c for c in text)代码块内容不要转义否则反引号会被破坏。建议把代码块单独提取出来只转义普通文本部分。5.3 Bot 在群里不响应Telegram Bot 默认开启隐私模式群里只能收到/开头的命令和 提及。要么去 BotFather 发/setprivacy选 Disable要么在群里用/命令你的bot的形式。OpenClaw 侧确认group_commands true、private_only false。5.4 消息超过 4096 字符被截断Telegram 单条消息上限 4096 字符。长回复要分页按段落切分尽量别在句子中间断def split_message(text: str, limit: int 4096) - list[str]: if len(text) limit: return [text] parts, buf [], for para in text.split(\n\n): if len(buf) len(para) 2 limit: buf f{buf}\n\n{para} if buf else para else: if buf: parts.append(buf) buf para if buf: parts.append(buf) return parts5.5 模型调用 401 或超时401 一般是TAOTOKEN_API_KEY没读到或写错确认环境变量在容器里真的注入了可以用docker exec openclaw-gateway env | grep TAOTOKEN检查。超时则看base_url是否可达以及模型名是否拼对。接入细节可以对照文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 把凭证和渠道收拢到一处整条链路跑通后你会发现真正需要长期维护的其实就两样Telegram 侧的 Bot Token / Webhook Secret和模型侧的 API 凭证。前者用环境变量注入后者用 TaoToken 统一管理OpenClaw 的base_url指向 https://taotoken.net/api 就行换模型、加渠道都不用改代码。如果你还在调 Webhook 和接入参数先把 API Keys 和接入文档过一遍API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想快速验证模型响应用模型对话页最直接https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期跑编码或 Agent 任务的话Coding Plan 更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后留一个我常用的排查习惯每次改完 Webhook 配置先getWebhookInfo确认状态再本地 curl 模拟一次最后才发真实消息。三步走下来问题基本都能定位到具体环节不用瞎猜。
