针对高频故障的“照镜子”诊断

如果你已经跑完了上述5条命令，但机器人依然犯病，请对照以下几种最典型的“症状”进行自查：

1. 明明在线，但群聊里就是不理人（Telegram专项）

这是最普遍的Telegram机器人假死现象。根据官方文档，如果你看到机器人在线但群组一片沉默，问题几乎都出在 [隐私模式（Privacy Mode）] 和 [@提及要求] 上：

• 隐私模式未关闭：默认情况下，Telegram机器人无法读取群内的所有消息。你需要去 BotFather 那里使用 /setprivacy 指令关闭隐私模式，或者直接把机器人设为群管理员。
• 关键操作：修改隐私设置后，务必将机器人踢出群再重新拉入，否则Telegram不会立即应用新的聊天权限配置。
• 如果私聊也失灵，需通过 openclaw pairing list telegram 确认配对（Pairing）是否已批准。

2. 启动即报错：getMe returned 401

这代表鉴权失败。不用查网络，直接去查你的密钥：

• 在配置文件、环境变量或指定的 tokenFile 中，botToken 或者 TELEGRAM_BOT_TOKEN 填错了，或者这个Token已经被 BotFather 吊销了。请去 @BotFather 重新生成并更新配置。

3. 轮询冲突：getUpdates 报 409 错误

这个错误码代表“冲突”。官方文档明确指出：同一个机器人令牌（Bot Token）在同一时间只能有一个长效轮询器在工作。 出现 409 错误，意味着你大概率在另一个窗口、另一台设备或者另一个脚本里跑着另一个 OpenClaw 网关实例。如果不慎多开，关掉多余的那个进程就行。

4. 频繁掉线或重连死循环

如果机器人在线情况像心电图一样上蹿下跳，或者长时间卡顿不动，请重点怀疑网络链路：

• DNS与IPv6：服务器是否能正确解析 api.telegram.org？很多机器对 IPv6 的支持有缺陷。
• 代理与防火墙：如果你的服务器在中国大陆或者内部网络，需要确认代理路由是否能让服务顺畅访问外网。
• 轮询看门狗：OpenClaw 默认在 120 秒内若无数据则触发重启，如果仅仅是网络慢，适当调高 channels.telegram.pollingStallThresholdMs 的阈值可以缓解。

如果是“一更新就坏”，请按这个顺序抢救

很多故障其实发生在版本更新后，这是因为插件依赖树与旧的缓存残留发生了冲突。

如果你在 openclaw status --all 中看到了：

plugin load failed: dependency tree corrupted

千万别乱删文件。 正确的处理步骤如下：

1. 运行 openclaw status --all 查看全貌。
2. 运行 openclaw doctor --fix。这个命令专门用来清除过渡期产生的“脏”缓存和旧的认证影子文件。
3. 接着运行 openclaw gateway restart 重启网关。
4. 再次检查 openclaw status --all 确认恢复。

Telegram 渠道的正确开启姿势

不少用户容易搞混接入流程，这里特别强调一下：

• 不通过命令行登录。OpenClaw 的 Telegram 渠道不执行类似 openclaw channels login telegram 这样的操作。
• 正确流程：直接在配置文件中打开开关（channels.telegram.enabled: true），将 Token 写入环境变量或配置文件，然后直接启动网关。
• 私聊默认需要配对验证：网关启动后，给机器人发一条消息会收到配对码，用 openclaw pairing approve telegram <配对码> 批准即可。

结论

仅仅根据“botchat不工作”这条简单描述，还不足以判定是代码Bug还是环境问题。但排错的路线图已经非常明确：

• 第一反应：跑完那5条核心诊断命令。
• 如果是Telegram：按优先级排查隐私模式/提及设置、Token是否401过期、网络DNS/IPv6/代理、多开引发的409冲突。

针对高频故障的“照镜子”诊断

如果你已经跑完了上述5条命令，但机器人依然犯病，请对照以下几种最典型的“症状”进行自查：

1. 明明在线，但群聊里就是不理人（Telegram专项）

这是最普遍的Telegram机器人假死现象。根据官方文档，如果你看到机器人在线但群组一片沉默，问题几乎都出在 [隐私模式（Privacy Mode）] 和 [@提及要求] 上：

• 隐私模式未关闭：默认情况下，Telegram机器人无法读取群内的所有消息。你需要去 BotFather 那里使用 /setprivacy 指令关闭隐私模式，或者直接把机器人设为群管理员。
• 关键操作：修改隐私设置后，务必将机器人踢出群再重新拉入，否则Telegram不会立即应用新的聊天权限配置。
• 如果私聊也失灵，需通过 openclaw pairing list telegram 确认配对（Pairing）是否已批准。

2. 启动即报错：getMe returned 401

这代表鉴权失败。不用查网络，直接去查你的密钥：

• 在配置文件、环境变量或指定的 tokenFile 中，botToken 或者 TELEGRAM_BOT_TOKEN 填错了，或者这个Token已经被 BotFather 吊销了。请去 @BotFather 重新生成并更新配置。

3. 轮询冲突：getUpdates 报 409 错误

这个错误码代表“冲突”。官方文档明确指出：同一个机器人令牌（Bot Token）在同一时间只能有一个长效轮询器在工作。 出现 409 错误，意味着你大概率在另一个窗口、另一台设备或者另一个脚本里跑着另一个 OpenClaw 网关实例。如果不慎多开，关掉多余的那个进程就行。

4. 频繁掉线或重连死循环

如果机器人在线情况像心电图一样上蹿下跳，或者长时间卡顿不动，请重点怀疑网络链路：

• DNS与IPv6：服务器是否能正确解析 api.telegram.org？很多机器对 IPv6 的支持有缺陷。
• 代理与防火墙：如果你的服务器在中国大陆或者内部网络，需要确认代理路由是否能让服务顺畅访问外网。
• 轮询看门狗：OpenClaw 默认在 120 秒内若无数据则触发重启，如果仅仅是网络慢，适当调高 channels.telegram.pollingStallThresholdMs 的阈值可以缓解。

如果是“一更新就坏”，请按这个顺序抢救

很多故障其实发生在版本更新后，这是因为插件依赖树与旧的缓存残留发生了冲突。

如果你在 openclaw status --all 中看到了：

plugin load failed: dependency tree corrupted

千万别乱删文件。 正确的处理步骤如下：

1. 运行 openclaw status --all 查看全貌。
2. 运行 openclaw doctor --fix。这个命令专门用来清除过渡期产生的“脏”缓存和旧的认证影子文件。
3. 接着运行 openclaw gateway restart 重启网关。
4. 再次检查 openclaw status --all 确认恢复。

Telegram 渠道的正确开启姿势

不少用户容易搞混接入流程，这里特别强调一下：

• 不通过命令行登录。OpenClaw 的 Telegram 渠道不执行类似 openclaw channels login telegram 这样的操作。
• 正确流程：直接在配置文件中打开开关（channels.telegram.enabled: true），将 Token 写入环境变量或配置文件，然后直接启动网关。
• 私聊默认需要配对验证：网关启动后，给机器人发一条消息会收到配对码，用 openclaw pairing approve telegram <配对码> 批准即可。

结论

仅仅根据“botchat不工作”这条简单描述，还不足以判定是代码Bug还是环境问题。但排错的路线图已经非常明确：

• 第一反应：跑完那5条核心诊断命令。
• 如果是Telegram：按优先级排查隐私模式/提及设置、Token是否401过期、网络DNS/IPv6/代理、多开引发的409冲突。