OpenClaw 2026.7.1-2 升级后 Telegram 机器人失效排查记录
更新于 2026-07-09
OpenClaw 2026.7.1-2 升级后 Telegram 机器人失效排查记录
这是一篇 OpenClaw 升级后的故障排查笔记。问题表面是 Telegram 机器人在线但普通消息不回复，实际涉及 Gateway、Agent Dispatch、npm 全局包、插件依赖和 systemd 用户服务。
问题背景
OpenClaw 部署在 Ubuntu Server 上，通过 systemd 用户服务运行。常用通信渠道包括 Telegram Bot 和 QQ Bot，Gateway 监听在本机端口 127.0.0.1:18989。升级前整体运行正常，Telegram 和 QQ 都可以正常触发 Agent 回复。
某次执行 OpenClaw 升级后，出现了一个比较迷惑的现象：
- Telegram 显示机器人在线；
/help等命令类消息可以响应；- 普通聊天消息没有回复，例如发送
你好后一直无响应。
这个现象说明 Telegram Bot 本身没有掉线，Gateway 也不是完全不可用。问题更可能发生在消息进入 Gateway 之后，到 Agent 处理和回复发送之间。
初步判断
如果 Telegram 连接完全异常，通常会表现为机器人离线、Webhook 或 polling 不通、命令也无法响应。但这次 /help 正常，说明基础链路至少部分可用。
Telegram Bot
|
v
Gateway
|
v
Agent Dispatch
|
v
模型调用 / 工具调用
|
v
回复发送
所以排查重点放在 Gateway 日志、Agent Dispatch 错误、OpenClaw 版本和插件加载状态上。
检查 OpenClaw 状态
先确认当前版本：
openclaw --version
输出显示当前为：
OpenClaw 2026.7.1-2
新版 OpenClaw 的日志命令和旧版不完全一致，旧的 openclaw logs --tail 100 不再适用。可以直接查看 OpenClaw 日志，或者查看 systemd 用户服务日志：
openclaw logs
journalctl --user -u openclaw-gateway -n 100 --no-pager
第一个异常：Runtime 方法缺失
日志里出现了关键错误：
telegram dispatch failed:
TypeError:
runtime.recordSessionMetaFromInbound is not a function
这说明 Telegram 消息已经被 Gateway 收到，但在分发给 Agent Runtime 时失败。也就是说，问题不是 Telegram 平台侧的问题，而是 OpenClaw 内部运行时组件异常。
第二个异常：模块文件缺失
继续查看 systemd 服务状态：
systemctl --user status openclaw-gateway
服务状态显示仍然是 active (running)，但日志中出现模块缺失：
Error [ERR_MODULE_NOT_FOUND]
Cannot find module:
commands-status-BrbT1hMO.js
task-registry.maintenance-oc6FgV59.js
这个信号比单纯的 Runtime 报错更关键。它说明升级后的全局 npm 包文件不完整，或者新旧版本产物混杂。服务进程虽然还能启动，但部分动态加载模块已经找不到，导致聊天消息进入 Dispatch 后失败。
重新安装 OpenClaw
先停止 Gateway：
systemctl --user stop openclaw-gateway
重新安装当前版本：
npm install -g openclaw@2026.7.1-2
安装后再次确认版本：
openclaw --version
然后重新生成 systemd 服务并启动：
openclaw gateway install --force
systemctl --user daemon-reload
systemctl --user start openclaw-gateway
第三个异常：Codex 插件缺失
OpenClaw 主程序修复后，Gateway 仍然没有完全 ready。日志里出现：
plugins.entries.codex:
plugin not installed
继续观察可以看到 OpenClaw 尝试自动安装缺失插件，但 npm 源连接失败：
Failed to install missing configured plugin "codex"
npm error ECONNRESET
https://mirrors.tencentyun.com/npm/
原因很明确：配置里启用了 plugins.entries.codex，但全局环境里缺少 @openclaw/codex。同时当前 npm registry 使用的是腾讯云镜像，连接不稳定导致自动安装失败。
安装 Codex 插件
先查看 npm 源：
npm config get registry
如果输出为腾讯云镜像：
https://mirrors.tencentyun.com/npm/
可以切换为 npm 官方源：
npm config set registry https://registry.npmjs.org/
然后安装 Codex 插件：
npm install -g @openclaw/codex
最后重启 Gateway：
systemctl --user restart openclaw-gateway
恢复验证
检查服务状态：
systemctl --user status openclaw-gateway
确认 Gateway 处于运行状态：
Active: active (running)
继续检查渠道状态：
openclaw channels status --probe
确认 Telegram 和 QQ 都正常 connected。最后在 Telegram 发送普通消息：
你好
机器人恢复正常回复，说明从 Telegram 到 Gateway、Agent、模型和回复发送的完整链路已经恢复。
根因总结
1. OpenClaw 升级后程序文件不完整
表现为 ERR_MODULE_NOT_FOUND，动态加载的 JS 模块缺失。解决方式是重新安装对应版本的 OpenClaw，并重新生成 Gateway systemd 服务。
npm install -g openclaw@2026.7.1-2
openclaw gateway install --force
2. Codex 插件依赖缺失
表现为 plugins.entries.codex: plugin not installed。配置启用了 Codex 插件，但全局 npm 环境没有安装对应包。
npm install -g @openclaw/codex
3. npm 镜像源不稳定
表现为 ECONNRESET，导致 OpenClaw 自动安装缺失插件失败。遇到这类问题时，可以临时切换到 npm 官方源。
npm config set registry https://registry.npmjs.org/
以后升级 OpenClaw 的推荐流程
升级前先做备份，尤其是 ~/.openclaw 和 systemd 用户服务文件：
tar -czf openclaw-backup-$(date +%F).tar.gz \
~/.openclaw \
~/.config/systemd/user/openclaw-gateway.service
升级和刷新服务：
npm install -g openclaw@latest
openclaw gateway install --force
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway
升级后不要只看进程是否 running，还要看日志和渠道探测：
openclaw doctor
systemctl --user status openclaw-gateway
journalctl --user -u openclaw-gateway -n 100 --no-pager
openclaw channels status --probe
经验沉淀
OpenClaw 不是一个单进程小脚本，而是由 Gateway、Agent Runtime、模型、插件、渠道适配器和本地配置共同组成的 Agent 系统。升级时不能只关注 openclaw 主程序，还要关注插件、systemd 服务、npm registry 和会话迁移。
这次故障最有价值的经验是：服务在线不等于消息链路正常。当机器人在线、命令可用、普通消息无响应时，要优先看 Dispatch 和 Runtime 日志，而不是一上来怀疑 Telegram 平台。
最终状态
OpenClaw: 2026.7.1-2
Gateway: running
Telegram: connected
QQ: connected
Plugins: Codex installed
Models: GPT-5.5 / DeepSeek
个人 AI 助手恢复运行。