07-实战 · 版本统一与脚本治理实战
目标：用一组真实工程场景把三件事串起来：CLI / gateway 版本统一、memory 迁移、自定义脚本治理。这不是理论课，而是一条能直接套用到你自己环境里的收口路径。
这篇适合什么时候读
Section titled “这篇适合什么时候读”如果你已经遇到下面任意一个症状，直接读这一篇：
config validate说某个键非法，但 gateway 明明又要求你设置它- embedding 维度从 1024 切到 4096 后，记忆系统起不来
- 你自己的
~/.openclaw/scripts/开始“帮倒忙” - 飞书和 WebUI 一起不回，但 gateway 进程看起来还活着
一条真实的故障链长什么样
Section titled “一条真实的故障链长什么样”这类系统性事故通常不是单点，而是链式叠加：
- 模型 / 中转站配置收敛 你刚刚统一了主模型、fallback、压缩模型。
- embedding 升级到 4096 维 配置是新的，LanceDB 表还是旧的。
- 自定义自愈脚本回滚 baseline
刚改好的
dbPath、rerank 配置又被抹回旧值。 - 后台 review 继续抢主会话
agent:main:main卡死，前台开始一起不回。 - CLI 和 gateway 版本还不一致 你看到的 warning 和你能不能写配置键再次打架。
这时候如果你分开一个个猜，会很慢。 正确策略是按“依赖关系”收：
版本统一 ↓配置定稿 ↓迁移记忆库 ↓治理自定义脚本 ↓清理坏会话 / 背景任务噪音第一层：先统一版本，不然你连“什么算正确配置”都说不清
Section titled “第一层：先统一版本，不然你连“什么算正确配置”都说不清”先看：
which -a openclawopenclaw --versionopenclaw gateway statusbash ~/.openclaw/scripts/runtime-status-report.sh如果 CLI 和 gateway 不是同一版，优先统一。 详见 06-升级/03-CLI与Gateway版本统一。
原则：
- 先统一入口
- 再加新配置键
- 最后再重启服务
- 如果服务文件指向旧 nvm / npm 目录，先跑
repair-gateway-service.sh --repair --restart
最近一次收口后，这一层还多了一个判断：全局 OpenClaw runtime 缺失也要能自愈。
也就是说，不只是修 launchd / systemd 里的文本路径，还要确认这个路径背后的 dist/index.js 真的存在。否则下次重启仍然会炸。
第二层：embedding 升级时，新库重建比“原地硬改”更靠谱
Section titled “第二层：embedding 升级时，新库重建比“原地硬改”更靠谱”你要升到：
Qwen/Qwen3-Embedding-8B + 4096不要只改：
embedding.modelembedding.dimensions
而是：
- 新建
dbPath reembed- 校验计数
- 再切流量
详见 04-运维/07-LanceDB-4096维迁移与重嵌入。
第三层：脚本只补缺省，不要整段回滚
Section titled “第三层：脚本只补缺省，不要整段回滚”真实环境里最危险的一类脚本不是“完全坏掉”，而是“看起来在修复，实际上在覆盖生产新配置”。
最典型的错误就是：
baselineMemory != currentMemory→ 全部恢复成 baseline正确做法：
只补 baseline 里有、当前缺失的字段保留已经显式改过的生产配置memory-lancedb-pro 补丁要校验源码和清单两边
Section titled “memory-lancedb-pro 补丁要校验源码和清单两边”本地补丁常见的“修了一半”是：
源码里已经把超时改成 15000msopenclaw.plugin.json 里默认值仍是 5000ms这会让状态报告和实际运行理解不一致。补丁脚本应该同时检查：
- 源码里的默认超时
openclaw.plugin.json里的autoRecallTimeoutMs- 当前 OpenClaw 全局安装目录是否解析正确
特别是买家端机器可能使用 nvm、系统 npm、Homebrew 或 ~/.local，不要把作者本机路径写死进补丁脚本。
第四层：后台任务必须和主会话隔离
Section titled “第四层：后台任务必须和主会话隔离”当你开始做：
- background review
- 周审
- 自动归并
- 自愈脚本
这些后台动作时，默认不要去抢 agent:main:main。
应该做的是：
- 最近活跃会话门槛
pending/running哨兵- 独立
session-id - 快速
/health门槛 - 派发硬超时
这样就算后台任务失败，也只是“没跑成”，不会顺手把主控拖死。
第五层：把“修完了”变成可复用经验
Section titled “第五层：把“修完了”变成可复用经验”很多人修完就结束，下一次同类事故还从头踩。
更好的做法是把经验拆成三层：
层 1：当天日志
Section titled “层 1：当天日志”记录：
- 现象
- 根因
- 怎么修
- 哪些命令有效
层 2：durable correction
Section titled “层 2：durable correction”只保留真正可复用的原则，比如：
- CLI 和 gateway 必须版本统一
- 自愈脚本只补缺省，不整段回滚
- 4096 维迁移必须新库重嵌入
层 3：公开教程
Section titled “层 3：公开教程”把“这不是你一个人的坑”的部分写成文档。 这样以后不需要从聊天记录里翻答案。
这套收口流程的价值
Section titled “这套收口流程的价值”它不是“修好一个 bug”，而是把系统稳定性往上抬一层：
- 版本口径统一
- 数据口径统一
- 脚本边界清晰
- 服务路径可自愈
- 后台任务不再反噬主控
- 同类问题可文档化复用
这才是长期运行 OpenClaw 最值得做的那类工程工作。
如果你现在已经处在“能跑，但怕再炸”的阶段，建议按这个顺序继续：
- 把所有高风险脚本做一次 owner 清单
- 把 memory / model / channel 的基线和生产配置分开
- 给每条后台任务加 lock、cooldown、独立 session id
- 把已经验证过的经验写进公开文档，而不是只留在聊天记录里