修复内容

当以下情况发生时，会出现会话文件被锁定错误：

• - OpenClaw在写入会话时崩溃
• 多个进程尝试访问同一会话
• 会话写入期间网络超时
• 系统崩溃导致残留锁定文件

症状：

• - 出现会话文件被锁定（超时10000毫秒）错误
• 所有模型因锁定超时而失败
• 会话无响应

工作原理

1. 1. 扫描~/.openclaw/agents//sessions/.jsonl.lock文件
2. 检查拥有该锁的进程是否仍在运行
3. 如果进程已终止，则移除过期锁定
4. 可选地恢复已损坏的会话数据

命令

check

bash
neckr0ik-session-healer check [--verbose]

扫描被锁定的会话并报告：

• - 锁定文件路径
• 拥有进程PID
• 进程状态（存活/终止）
• 锁定时长
• 会话ID

heal

bash
neckr0ik-session-healer heal [--force]

清除所有过期锁定（拥有进程已终止的情况）。

选项：
--force 清除所有锁定，即使进程仍在运行（危险操作）
--dry-run 仅显示将要清除的内容，不实际执行

unlock

bash
neckr0ik-session-healer unlock

通过会话ID清除特定会话锁定。

recover

bash
neckr0ik-session-healer recover

尝试恢复已损坏的会话文件：

• - 验证JSON行格式
• 移除损坏的行
• 恢复前创建备份

安全特性

• - 绝不会清除仍在运行进程的锁定（除非使用--force）
• 修改会话文件前创建备份
• 记录所有操作以供审计追踪
• 修复后验证会话文件完整性

示例输出

$ neckr0ik-session-healer check

正在检查被锁定的会话...
发现3个锁定文件：

✗ 会话：c4fa26e6-20be-4843-9678-a2f328dd1844
锁定：/Users/user/.openclaw/agents/main/sessions/.../c4fa...jsonl.lock
PID：52251（已终止 - 进程未运行）
时长：2小时34分钟
状态：过期 - 可安全清除

✓ 会话：a1b2c3d4-5678-90ab-cdef-1234567890ab
锁定：/Users/user/.openclaw/agents/main/sessions/.../a1b2...jsonl.lock
PID：12345（运行中）
时长：5分钟
状态：活跃 - 请勿清除

$ neckr0ik-session-healer heal

正在修复过期锁定...
[已清除] c4fa26e6-20be-4843-9678-a2f328dd1844（PID 52251已终止）
[已跳过] a1b2c3d4-5678-90ab-cdef-1234567890ab（PID 12345仍在运行）

已修复1个会话。0个错误。

相关参考

• - scripts/healer.py - 主修复脚本
• references/lock-recovery.md - 详细恢复指南