夜雨聆风我之前写过不少关于 OpenClaw 的文章，但今天这个话题，是我觉得最实用、也最容易被忽视的——如何防止 OpenClaw 假死。
什么叫假死？就是你发了一条消息，Agent 应该回复，但。它。完。全。不。动。了。没有报错，没有提示，就那么安静地待着。你等五分钟，等十分钟，发现不对劲，一查日志，才发现某个后台进程卡住了，或者某个 exec 任务超时了没处理。
这种情况，我踩过不少坑。今天把我的实战经验整理出来，给各位参考。
一、Gateway 超时配置：健康检查是第一道防线
OpenClaw 的 Gateway 其实自带健康监控系统，只是很多人没注意到。
1.1 核心配置项
在配置文件里，有三个关键参数：
gateway.channelHealthCheckMinutes：健康检查多久跑一次，默认 5 分钟gateway.channelStaleEventThresholdMinutes：频道多久没动静算"凉了"，默认 30 分钟gateway.channelMaxRestartsPerHour：每小时最多重启几次，默认 10 次
这三个参数配合起来，Gateway 会自动检测频道状态，发现凉了就重启。我之前有个 Telegram 频道，经常收不到消息，加了健康检查配置后，基本没再出过问题。
1.2 常用健康检查命令
日常诊断用这三个命令就够了：
openclaw status # 本地摘要：Gateway 能不能连通、频道链接状态、最近活动
openclaw status --all # 完整诊断，可复制粘贴用于调试
openclaw status --deep # 强制 live probe，包括每个频道的探测结果
openclaw health 这个命令也很有用，它会返回 Gateway 的健康快照，包括每个频道的状态、Session Store 的情况、Agent 是否可用。我一般在怀疑有问题的时候跑一下，能快速定位。
还有个简单的技巧：在 WhatsApp 或 WebChat 里单独发一条 /status，也会返回状态回复，不用每次都切到终端。
二、Hook 系统：让自动化替你盯着
2.1 Hook 是什么
Hook 是 OpenClaw 的事件驱动自动化机制。你可以把 Hook 理解成"监听器"——当某个事件发生时，自动执行一段代码。
事件类型包括：
命令事件： command:new、command:reset、command:stop生命周期事件： gateway:startup、agent:bootstrap消息事件： message:received、message:sent、message:transcribed、message:preprocessed会话事件： session:compact:before、session:compact:after、session:patch
Hook 的实现方式是：在配置文件中定义 JavaScript/TypeScript 文件路径，Gateway 加载时会自动扫描这些文件并注册事件监听器。
2.2 实战：用 Hook 实现防假死
这是我目前用的几个方案：
方案一：gateway:startup 时发送启动通知
每次 Gateway 启动成功时，自动发一条消息到指定频道。这样你在外面也能知道 Agent 什么时候重启了。
const handler = async (event) => {
if (event.type !== "gateway:startup") return;
event.messages.push("Gateway 已启动，健康检查已启用");
};
export default handler;
方案二：后台进程异常退出时告警
利用 exec 工具的 notifyOnExit 配置，可以在后台命令退出时触发事件。结合 Hook，可以做到进程异常退出时自动通知。
配置很简单：
{
"tools": {
"exec": {
"notifyOnExit": true,
"notifyOnExitEmptySuccess": false
}
}
}
这样后台命令异常退出时，你会收到通知，不用自己盯着。
方案三：定期心跳
用 cron job 定期跑一个轻量任务，作为"心跳检测"。如果心跳没响应，说明 Agent 可能出问题了。
0 */2 * * * curl -s http://localhost:18789/health || echo "ALERT: Gateway down"
2.3 启用 Hook
Hook 通过配置文件启用，示例：
{
"hooks": {
"internal": {
"entries": {
"session-memory": {
"enabled": true,
"path": "/path/to/session-memory/handler.ts"
},
"boot-md": {
"enabled": true,
"path": "/path/to/boot-md/handler.ts"
}
}
}
}
}
内置的 Hook 包括：
session-memory：每次/new或/reset时自动保存会话上下文boot-md：Gateway 启动时运行BOOT.mdcommand-logger：记录所有命令到日志文件bootstrap-extra-files：注入额外的 bootstrap 文件
三、后台进程与生命周期管理
3.1 exec 工具的参数
exec 是最常用的工具，但很多人不知道这几个参数能救命：
yieldMs：多长时间后自动转入后台，默认 10000（10秒）timeout：超时自动杀掉，单位是秒，默认 1800（30分钟）background：直接后台运行
关键来了：如果你有个任务可能跑很久，一定要设 timeout。我之前有个 OCR 任务没设 timeout，结果跑了三个小时没反应，查日志才发现图片太大处理卡住了。
正确的调用方式是通过工具调用：
{
"tool": "exec",
"command": "python process_images.py",
"timeout": 300,
"yieldMs": 5000
}
3.2 process 工具：管理和监控
后台进程挂起后，用 process 工具来管理。同样是通过工具调用：
{ "tool": "process", "action": "list" }
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
{ "tool": "process", "action": "log", "sessionId": "<id>" }
{ "tool": "process", "action": "kill", "sessionId": "<id>" }
{ "tool": "process", "action": "clear", "sessionId": "<id>" }
常用操作：
list：列出所有后台会话poll：查看输出和状态log：读取完整日志kill：杀掉卡住的进程clear：清理已结束的会话
我一般在跑长任务时，设个 5 分钟的 yieldMs，然后用 poll 定期查看进度。这样即使任务卡住，也能及时发现。
3.3 自动完成提醒
有个很好用的功能：当后台任务完成时，OpenClaw 可以自动推送通知。但这需要开启 notifyOnExit：
{
"tools": {
"exec": {
"notifyOnExit": true,
"notifyOnExitEmptySuccess": true
}
}
}
开启后，后台任务不管是成功还是失败，你都会收到通知。对于长时间运行的任务，这个功能很实用。
四、我的防假死配置方案
这是我目前线上用的完整配置，供各位参考：
{
"gateway": {
"channelHealthCheckMinutes": 5,
"channelStaleEventThresholdMinutes": 30,
"channelMaxRestartsPerHour": 10
},
"tools": {
"exec": {
"timeoutSec": 1800,
"backgroundMs": 10000,
"notifyOnExit": true,
"notifyOnExitEmptySuccess": false
}
},
"hooks": {
"internal": {
"entries": {
"boot-md": { "enabled": true },
"session-memory": { "enabled": true }
}
}
}
}
配合 cron job 每两小时检查一次 health，基本能做到：
频道异常自动重启 后台任务异常退出通知 Gateway 启动确认 会话自动保存
五、总结
防假死这事儿，关键是提前配置 + 异常监控：
健康检查配置不能省，这是 Gateway 自带的能力 Hook 系统很好用，事件驱动的自动化能省很多心 exec 和 process 工具的参数要熟悉，特别是 timeout 和 yieldMs 定期检查配合 cron job，能在问题变大之前发现
我的经验是，80% 的假死问题都可以通过配置避免。剩下的 20%，靠监控告警能及时发现。别等到用户来报问题时才反应。
