问题现象
你的 agent 停止回复，日志里出现 session file locked (timeout 10000ms)。这通常不只是某个模型超时；session write 在返回输出前失败，可能连 fallback provider 也一起受影响。
故障排查
OpenClaw "session file locked" timeout 修复
当日志出现 "session file locked"、"timeout 10000ms" 或 stale .jsonl.lock，并且 agent 停止回复时，先确认只有一个 OpenClaw gateway 正在写 session store。然后检查对应 .jsonl.lock 文件，确认 owner PID 是否仍然存活且确实是预期的 gateway process。优先 clean restart gateway；只有在 owner 已死亡或明确 stale 时，才删除具体 lock file。删除活跃 lock 可能造成 session corruption。
简体中文 View English source
为什么危险
这个故障容易被低估，因为它看起来像单次 model timeout。实际上，locked session file 会让后续模型调用、fallback 路径和渠道回复一起失败。搜索这个错误的用户通常正处于生产或准生产故障中，需要低风险、可复现的 runbook。
OpenClaw 如何锁 session
OpenClaw 把 session history 存在 ~/.openclaw/agents/main/sessions/ 下的 JSONL 文件中。写入时使用 .jsonl.lock 防止并发写坏数据。这个设计本身合理；事故通常来自 lock ownership、process lifecycle 或存储延迟失配。
诊断流程
确认精确错误签名：搜索日志里的 session file locked (timeout 10000ms)，记录 session ID 和 lock path。
确认只有一个 gateway process/container 在写同一个 session directory。多个实例竞争同一目录是自托管场景最常见原因。
检查 lock file owner metadata，记录 pid 和 createdAt。
确认 owner PID 是否存活，并核对 command 与 uptime；PID 可能被复用，不能只看数字存在。
检查磁盘压力或 network filesystem latency。I/O wait、远程 volume 或高负载会放大 lock starvation。
先 clean restart gateway，再用一个受控 prompt 验证写入路径。
安全恢复
如果可能，先暂停高流量 inbound channels 或 webhooks。
快速备份 ~/.openclaw/agents/main/sessions。
clean restart gateway，不要一上来 force kill。
用一个测试 session 复测。
如果 lock 仍存在，且 owner PID 已死亡或明确 stale，只删除对应 lock file。
恢复流量前记录事故时间线、触发条件和验证结果。
验证 checklist
30-60 分钟内没有新的 timeout 10000ms lock 错误。
至少 10 个跨 session 测试 prompt 正常完成。
fallback model path 可用。
runtime policy 保证只有一个 gateway 写 session store。
on-call runbook 写明何时可以删除 lock file。
托管迁移路径
如果 lock incident 反复出现，问题可能已经不是单个 bug，而是运维复杂度：process contention、host instability 和脆弱的 incident handling。可以把现有 OpenClaw 迁移到 Lobsterland 托管实例，保留上下文，减少自管 runtime 的排障成本。