05-排障 · 02 主会话锁死与后台任务噪音

预计阅读：12 分钟适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7，尤其适合长期运行 + 多后台任务场景 · 最后审核：2026-05-09 前置：05-排障/01-诊断流程 / 04-运维/08-自定义脚本与Cron治理本章回答：为什么 WebUI 和飞书会一起“不回消息”？日志里的 session file locked / stuck session 到底说明了什么？

典型症状

这类故障通常表现为：

WebUI 和飞书同时不回复
gateway 进程还活着
日志里反复出现：

session file locked (timeout 10000ms)
stuck session: sessionKey=agent:main:main

这时不要先怀疑模型、中转站或飞书插件。
更常见的是：主控会话自己的元数据或锁已经卡住了。

先判断是不是“主会话锁死”

1. 看活动索引里 `agent:main:main` 指向谁

node - <<'EOF'
const fs = require("fs");
const data = JSON.parse(fs.readFileSync(
  process.env.HOME + "/.openclaw/agents/main/sessions/sessions.json",
  "utf8"
));
console.log(JSON.stringify(data["agent:main:main"] || null, null, 2));
EOF

重点看：

sessionId
sessionFile
updatedAt

2. 看活动目录里有没有真实 `.lock`

ls ~/.openclaw/agents/main/sessions/*.lock

如果日志一直报锁，但目录里根本没有活着的 .lock，就不是普通并发写，而是 索引和实际会话状态已经脱节。

3. 看日志里是不是持续同一条会话

rg -n 'agent:main:main|session file locked|stuck session' \
  ~/.openclaw/logs/gateway.err.log

如果始终是同一个 sessionKey、同一份 sessionFile，基本就是坏主会话。

两个强信号：说明不是普通慢，而是元数据坏了

信号 1：`sessionId` 和 `sessionFile` 对不上

例如：

sessionId 是一条新 boot 会话
sessionFile 却还指向几小时前那份老文件

这说明 索引已漂移。

信号 2：主会话条目持续 `processing`，但没有新的正常推进

也就是：

queueDepth 不高
没有持续新回复
age 持续增长

这是卡死，不是单纯“模型慢”。

最小破坏修复流程

第 1 步：停 gateway

openclaw gateway stop

第 2 步：把坏会话文件归档，不直接删除

mkdir -p ~/.openclaw/temp/session-recovery-YYYYMMDD-HHMMSS
mv ~/.openclaw/agents/main/sessions/<坏会话>.jsonl \
   ~/.openclaw/temp/session-recovery-YYYYMMDD-HHMMSS/
mv ~/.openclaw/agents/main/sessions/<坏会话>.trajectory.jsonl \
   ~/.openclaw/temp/session-recovery-YYYYMMDD-HHMMSS/

第 3 步：从 `sessions.json` 里删掉坏索引

node - <<'EOF'
const fs = require("fs");
const path = process.env.HOME + "/.openclaw/agents/main/sessions/sessions.json";
const data = JSON.parse(fs.readFileSync(path, "utf8"));
delete data["agent:main:main"];
fs.writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
EOF

第 4 步：清理相关后台哨兵（如果是后台 review 触发出来的）

rm -f ~/.openclaw/state/pending-background-review
rm -f ~/.openclaw/state/pending-background-review.running

第 5 步：重启 gateway

openclaw gateway start
openclaw gateway status

修完后看什么

看 1：`agent:main:main` 是否还绑着旧文件

再次执行：

openclaw gateway status

以及：

node - <<'EOF'
const fs = require("fs");
const data = JSON.parse(fs.readFileSync(
  process.env.HOME + "/.openclaw/agents/main/sessions/sessions.json",
  "utf8"
));
console.log(JSON.stringify(data["agent:main:main"] || null, null, 2));
EOF

如果现在是 null，或者被重新建立成新条目且不再指向那份旧文件，就算摘干净了。

看 2：旧 `session file locked` 是否还继续新增

rg -n 'session file locked|stuck session: sessionId=.*agent:main:main' \
  ~/.openclaw/logs/gateway.err.log | tail -30

如果后面不再新增同类记录，说明主控锁死这条已经止血。

这类故障常见诱因

诱因 1：后台任务复用主会话

比如 background review、周审、批量修复直接往 agent:main:main 这条主链塞任务。
一旦主控本来就慢，就会互相抢锁。

诱因 2：超大旧会话 + context overflow

主会话太大时，即使不死锁，也会非常容易演化成：

Context overflow
auto-compaction 失败
session rotate 之后索引漂移

诱因 3：配置/脚本在半重启状态下重复改 session 状态

比如：

gateway 正在 draining
background job 还在发消息
自愈脚本同时在重启 / 清理

这时最容易产生“条目还是新的，但指针还是老的”。

预防办法

1. 后台任务一律用独立 session id

不要复用主会话。

2. 有 `pending` / `running` 哨兵的后台任务，必须原子清理

不然下一轮触发器会把旧状态当成新任务继续堆。

3. 主会话一旦连续报 stuck，不要反复继续投递任务

先修会话，再谈功能。

4. 保留恢复目录

会话问题不要直接 rm -f。
先归档，后面你还可能要回看：

用户到底在那条会话里做了什么
为什么索引漂移
是否需要抽取 durable lesson

一句话经验

“Gateway 还活着但前台不回消息”时，先查 agent:main:main，不要先查模型。

主会话锁死会同时拖住 WebUI、飞书和后台任务，是最容易被误判成“模型又坏了”的故障。