故障排除
针对行为异常的 Telegram 机器人的症状优先排查。
故障排查¶
机器人不响应未提及自己的群组消息
- 如果
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 的传输回退机制重试一次。持续出现网络/获取错误通常意味着到达api.telegram.org的 DNS/HTTPS 不通。
启动时报告未授权令牌
getMe returned 401表示配置的机器人令牌在 Telegram 认证失败。在 BotFather 中重新复制或重新生成令牌,然后更新channels.telegram.botToken、tokenFile、accounts.<id>.botToken或TELEGRAM_BOT_TOKEN(默认账户)。- 启动期间出现
deleteWebhook 401 Unauthorized同样是认证失败;将其视为“不存在 webhook”只会把同样的错误令牌问题推迟到后续的 API 调用。
轮询或网络不稳定
下方关于 `Node 22+` 的内容描述的是 Node 的网络行为,而非 OpenClaw 支持的运行时版本。当前要求请参阅 [Node.js](../../install/node.md)。
- 当 `AbortSignal` 类型不匹配时,使用自定义 fetch/proxy 的 Node 22+ 可能触发立即中止行为。
- 某些主机优先将 `api.telegram.org` 解析为 IPv6;IPv6 出口故障会导致间歇性 API 失败。
- 出现 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!` 的日志会作为可恢复的网络错误进行重试。
- 在轮询启动期间,OpenClaw 会复用启动时成功的 `getMe` 检查(用于 grammY),因此运行器在首次 `getUpdates` 之前无需再次 `getMe`。
- 如果 `deleteWebhook` 在轮询启动期间因临时网络错误失败,OpenClaw 会继续进入长轮询,而不是在轮询前发起另一次控制面调用。此时仍然有效的 webhook 会以 `getUpdates` 冲突的形式出现;OpenClaw 会重建传输并重试 webhook 清理。
- 日志中出现 `Polling stall detected` 表示 OpenClaw 默认在 120 秒未完成长轮询活跃检测后,会重启轮询并重建传输。
- 当正在运行的轮询账户在启动宽限期后未完成 `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 传输。
- 如果文本消息正常但附件出现 `getaddrinfo EAI_AGAIN` 或 `ENOTFOUND` 错误,仅设置代理环境变量仍会使媒体下载受本地 DNS 检查影响。将 `channels.telegram.proxy` 设置为可信的 HTTP(S) 或 SOCKS5 代理,以便解析媒体主机名,或配置[受管网络代理](/security/network-proxy)。代理端点本身必须保持本地可解析且可达。`dangerouslyAllowPrivateNetwork` 不能修复 DNS 缺失。
- 在直接出口/TLS 不稳定的 VPS 主机上,可通过代理路由 Telegram API 调用:
- 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 的行为效果更好时,可强制选择地址族:
- 默认情况下,RFC 2544 基准范围地址(`198.18.0.0/15`)已允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址,可选择启用 Telegram 专用的绕过选项:
- 同样的选项也可按账户在 `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 中设置。
- 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`,请先关闭该危险标志——该范围默认已允许。
Warning
channels.telegram.network.dangerouslyAllowPrivateNetwork 会削弱 Telegram 媒体 SSRF 保护。仅可用于受信任的、由操作者控制的代理环境(Clash、Mihomo、Surge fake-IP 路由),这些环境会生成 RFC 2544 基准范围之外的私有或特殊用途地址。正常的公共互联网 Telegram 访问应保持关闭。
-
临时环境变量覆盖:
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1、OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1、OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first。 - 验证 DNS 应答:
更多帮助:频道故障排查。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw