症状#

周末在 Telegram 上给家里跑着的 OpenClaw agent 发消息，直接报错：

Something went wrong while processing your request. Please try again.

没有任何有用的回复。agent 像是活着，但又像死了。

排查过程#

SSH 上去先看状态。openclaw status 跑了一下，表面上一切正常：

• Gateway 在跑，PID 正常
• Telegram channel 状态 OK
• 21 个 session 活着，主 agent 1 分钟前还有心跳

看起来没问题？但仔细看 status 输出有一行：

1
Gateway │ unreachable (missing scope: operator.read)

先跑了 openclaw gateway probe，发现 gateway 其实是通的（28ms），只是缺 operator.read scope 导致状态报告不完整。这不是致命问题。

真正的线索在日志里。openclaw logs 尾部赫然几行红色 error：

1
[tools] read failed: Cannot find module '.../dist/pi-tools.before-tool-call.runtime-CZmjUGKp.js'
2
[tools] exec failed: Cannot find module '.../dist/pi-tools.before-tool-call.runtime-CZmjUGKp.js'
3
[tools] memory_search failed: Cannot find module '.../dist/pi-tools.before-tool-call.runtime-CZmjUGKp.js'

所有 tool 调用全部失败。 agent 收到消息后想调用工具，但运行时找不到对应的模块文件，直接炸了。

根因#

去 dist 目录看了一下实际存在的文件：

1
$ ls dist/pi-tools.before-tool-call.runtime-*
2
dist/pi-tools.before-tool-call.runtime-1XfOSG54.js
3
dist/pi-tools.before-tool-call.runtime-B1zfu9VW.js
4
dist/pi-tools.before-tool-call.runtime-CZ9ni5mW.js
5
dist/pi-tools.before-tool-call.runtime-DYLhgwWK.js
6
...

注意看：代码里 import 的是 CZmjUGKp，但 dist 里存在的是 CZ9ni5mW。一个字符都不能差。

这是典型的 build 产物版本不一致问题。OpenClaw 用 tsdown（基于 rolldown）打包，输出文件名带 content hash。某些模块在新版本中被修改后，hash 变了，但 gateway 进程加载的还是旧的入口文件，引用的是旧 hash。

git status 一看，果然：

1
Update │ available · behind 5 · deps ok

本地代码落后 origin 5 个 commit。之前可能跑过一次 git pull 但没重新 build，或者 build 中途被打断了，导致 dist 目录里新旧文件混杂。

修复#

三步搞定：

1
cd ~/openclaw
2
git stash        # 保存本地改动
3
git pull origin main
4
pnpm run build   # 完整重新构建
5
openclaw gateway restart

重启后再看日志，Cannot find module 错误消失了。Telegram 上发消息，正常响应。

教训#

1. 带 content hash 的构建系统，版本必须完全对齐。 不能只 pull 不 build，也不能 build 到一半就跑。入口文件引用的 hash 和 dist 里实际存在的文件，差一个字符就是 module not found。

2. “服务在跑”不等于”服务正常”。 Gateway 进程活着、Telegram webhook 通着、session 有心跳——但 tool runtime 缺失意味着 agent 什么都做不了。status 页面不会直接告诉你这个。

3. 日志永远是第一手线索。 status 看着都是绿的，但 openclaw logs 里的 error 一眼就能定位问题。遇到”说不出哪里不对”的情况，先看日志。

TIP

如果你也在自建 OpenClaw，建议把更新流程写成一个脚本，确保 pull + install + build + restart 是原子操作，避免中间状态。