我们准备长期维护一个开源计划：OpenClaw Windows Stability Lab。

原因很简单：从公开 issue 和实际使用体验看，OpenClaw 官方主线要处理的事情很多，Windows 端很难被投入和 Linux、macOS 同等密度的人手与精力，所以稳定性问题更容易长期堆积。

这篇文章复盘的 PR #76024，就是这个计划里已经跑通的一次样本：一个真实 Windows 问题，如何从本地排查、测试验证，走到 OpenClaw 官方合并。

它解决的不是一个很大的口号，也不是“Windows 稳定性全套方案”。它只处理一个边界很清楚的问题：

OpenClaw 在 Windows 上做 memory atomic reindex 时，需要交换一组 SQLite index 文件。如果这个瞬间遇到 Windows 的短暂文件锁，fs.rename 可能返回 EBUSY、EPERM 或 EACCES，原流程就可能直接失败。

PR #76024 做的事情，是在这个文件交换边界上增加有限 retry，让短暂文件锁有机会自行恢复，同时不改变更大的 SQLite 行为。

相关链接：

• PR：https://github.com/openclaw/openclaw/pull/76024
• Issue：https://github.com/openclaw/openclaw/issues/64187
• Merge commit：https://github.com/openclaw/openclaw/commit/f3fd0eedff215967eb75361d241dd5e6cea602e8

1. 问题不是“玄学”，而是 Windows 文件锁边界

OpenClaw 的 memory atomic reindex 流程会先构建临时索引，再把文件交换到正式位置。涉及的文件包括：

index.sqlite
index.sqlite-wal
index.sqlite-shm

在 Windows 上，文件锁比很多开发者预期得严格。运行时、杀毒软件、索引器，甚至某个短暂打开文件的进程，都可能让 rename 在某个瞬间失败。

这类问题麻烦在于，它经常不是每次都稳定复现。今天失败，明天可能正常；一台机器失败，另一台机器可能看不到。

所以这次 PR 没有扩大范围，没有去改：

• SQLite journal mode
• 全局 busy_timeout
• 其他 storage 模块
• gateway 启动逻辑
• Windows 进程管理策略

它只处理 memory atomic reindex 的文件交换阶段。

2. 补丁方式：小范围 retry，而不是大改架构

PR 标题是：

fix(memory): retry transient index swaps on Windows

核心思路很克制：

• 只处理 EBUSY、EPERM、EACCES
• 默认最多 6 次尝试
• 每次等待采用 25ms 线性递增
• 最大等待大约 375ms
• 保留 optional sidecar 文件缺失时的原有行为
• 非 transient 错误继续抛出，不用 retry 掩盖

这类修复最怕“为了修一个偶发问题，引入一个更难解释的新行为”。所以补丁没有把 retry 泛化到所有文件操作，也没有把问题包装成一个全局 SQLite 配置问题。

它只是在 Windows 短暂文件锁这个边界上，给 OpenClaw 一个小而可测的缓冲。

3. 为什么要把本地问题提交回上游

遇到 Windows 文件锁问题，本地 workaround 很常见：

• 重新运行命令
• 删临时文件
• 重启进程
• 写一个脚本兜底

这些办法有时候能救急，但很难真正改善生态。

能进入上游的修复，必须让维护者看清楚几件事：

• 关联哪个具体 issue
• root cause 是什么
• 修复范围有没有失控
• 是否有测试覆盖
• CI 是否通过
• 是否会改变已有行为
• changelog 是否补齐

这次 PR 走完了这条链路。

4. 本地验证怎么做

本地验证命令包括：

pnpm exec vitest run extensions/memory-core/src/memory/manager.atomic-reindex.test.ts

结果：

1 test file passed
6 tests passed

Node 22 环境也重新跑过：

$env:Path = 'D:\nvm4w\nodejs;' + $env:Path
node --version
pnpm exec vitest run extensions/memory-core/src/memory/manager.atomic-reindex.test.ts

结果：

v22.22.2
1 test file passed
6 tests passed

还跑了：

pnpm lint:extensions -- extensions/memory-core/src/memory/manager-atomic-reindex.ts extensions/memory-core/src/memory/manager.atomic-reindex.test.ts
pnpm check:changed
git diff --check

对应结果：

0 warnings, 0 errors
exit code 0
exit code 0

5. CI 状态要写准确

这次 head commit 的 GitHub check runs 汇总是：

项目	数量
total check runs	79
completed	79
success	71
skipped	8
failure	0
cancelled	0

所以我不会写“全部 CI 成功”。因为其中有 8 项 skipped。

更准确的说法是：

该 commit 的 79 个 check runs 已完成，其中 71 个 success、8 个 skipped，未看到 failure 或 cancelled。

6. 最终结果：官方合并

最终，PR #76024 被 OpenClaw 官方合并。

关键证据：

项目	信息
PR	https://github.com/openclaw/openclaw/pull/76024
状态	Merged / Closed
Merged by	steipete
Merged at	2026-05-02 18:07:49 +08:00
Merge commit	f3fd0eedff215967eb75361d241dd5e6cea602e8
Head commit	2b53246ab5cc75a0e46309c52cdc653afcc40d04

这条链路闭合以后，事情就不只是“我们本地修过一个 bug”了，而是：

真实 Windows 问题
-> issue 记录
-> 最小补丁
-> 测试验证
-> bot review
-> CI 无失败
-> 官方合并
-> merge commit 进入主线

7. 这对 AI Agent 实战有什么启发

我现在越来越觉得，AI Coding 的分水岭不在于“会不会让模型写代码”，而在于能不能把真实工程问题闭环。

一个实战项目，至少要留下这些东西：

• 问题截图
• 复现条件
• 本地验证命令
• 修复边界
• PR / issue 链接
• 官方回复
• CI 状态
• 最终合并或关闭状态

没有这些，文章很容易写成经验感想。有了这些，才像真正跑过现场。

这也是我们把这次 OpenClaw PR #76024 单独复盘的原因。它不大，但很完整。

8. 接下来：OpenClaw Windows Stability Lab

我们的目标，不只是修掉这一个问题。

因为 Windows 上跑 OpenClaw，真正头疼的往往不是某一个孤立 bug，而是一组连续出现的稳定性问题：

今天 memory 出问题，明天 gateway 起不来，后天消息通道又没反应。

如果每次都只靠本地 workaround，问题会一直散落在聊天记录、临时脚本和个人经验里。短期能救急，长期很难复用，也很难反馈到上游。

所以接下来，我们准备长期维护一个开源计划：

OpenClaw Windows Stability Lab

这个计划会重点沉淀几类东西：

• Windows 环境下 OpenClaw 的典型故障案例
• 可复现的最小问题描述
• 本地验证命令和日志证据
• 能被上游 review 的最小补丁
• PR / issue / 官方回复的证据台账
• 面向普通用户的排障 runbook

PR #76024 是这条路线里已经跑通的一次样本。后续如果遇到 gateway、memory、消息通道、升级恢复、Windows 权限策略等问题，我们会尽量按同一套方式处理：先把问题讲清楚，再验证，再沉淀证据，能上游贡献的就提交回官方。

延伸阅读

主站完整复盘：

https://kunpeng-ai.com/blog/openclaw-pr-76024-windows-ebusy-upstream-merged/

OpenClaw / Hermes 上游贡献长期记录：

https://kunpeng-ai.com/blog/open-source-upstream-contributions-openclaw-hermes/