pdurlej/openclaw-skill-safe-update

# OpenClaw 安全升级演练套件

在您的 runtime 正式升级之前先进行演练。

本项目为人类、Codex 和 OpenClaw 提供了一种可重复的方法，用于在接触实际安装环境之前检查 OpenClaw 更新。它会下载确切的 npm artifacts，验证其身份与完整性，对比 package surfaces， 检查特定部署的自定义配置，并生成一个与 hash 绑定的证据 包。 **它不会更新 OpenClaw。** 它从不进行部署、重启服务、执行 package 生命周期脚本，也不会将绿色的报告视为允许变更 生产环境的凭证。 ## 存在原因 OpenClaw 安装环境通常不仅仅包含 `openclaw` 这一个 package。Channels、 plugins、native dependencies、MCP 工具、memory、provider routing、wrappers 和 local overlays 都可以独立变动。因此，一个发布版本可能在安装时看似 毫无问题，却悄悄移除了操作者所依赖的某些功能。 本套件背后的流程已经指导过两次高度 定制化的 OpenClaw 实例升级。准备工作刻意做得详尽且 有时耗时较长；而实际的升级过程则非常平淡。未来的每次升级 都将在此贡献另一组实地记录。 ## 作为 skill 安装 ### OpenClaw OpenClaw 直接支持基于 Git 的 skills： ``` openclaw skills install git:pdurlej/openclaw-skill-safe-update@main openclaw skills info openclaw-safe-update ``` 然后提问： ``` Use /openclaw-safe-update to rehearse my current OpenClaw version against an exact target version. Stop before apply. ``` 请参阅官方的 [OpenClaw skills 文档](https://docs.openclaw.ai/tools/skills) 以了解工作区、全局以及特定于 agent 的安装选项。 ### Codex 询问 Codex： ``` Install the openclaw-safe-update skill from https://github.com/pdurlej/openclaw-skill-safe-update and use it to rehearse my next OpenClaw update. ``` 或者显式使用内置的 Codex skill 安装程序： ``` python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \ --repo pdurlej/openclaw-skill-safe-update \ --path . \ --name openclaw-safe-update ``` 在下一轮 Codex 中使用 `$openclaw-safe-update` 调用它。 ## 直接运行演练 使用确切的版本。包含您的 runtime 依赖的每一个独立分发的 package。 ``` python3 scripts/openclaw_safe_update.py fetch \ --current-version 2026.6.11 \ --target-version 2026.7.1 \ --packages-json '["openclaw"]' \ --output-dir artifacts/input python3 scripts/openclaw_safe_update.py simulate \ --input-dir artifacts/input \ --customizations assets/customizations.example.json \ --output-dir artifacts/safe-update ``` 将示例自定义清单替换为对您实际的 wrappers、entrypoints、plugin contracts 和 overlays 的检查。原始部署可以 使用 `--allow-no-customizations`，但前提是必须明确确认它 没有任何本地集成接口。 ## 产出内容 | Artifact | 用途 | | --- | --- | | `runtime-truth.json` | 精确的 package 坐标与完整性凭证 | | `synthetic-update.json` | 有边界的当前版本与目标版本的 package diff | | `customization-compatibility.json` | 每个声明的本地 contract 的结果 | | `evidence-bundle.json` | 用于下游审查或 policy gates 的 SHA-256 绑定 | | `verdict.json` | 机器可读的 `blocked` 或 `ready_for_operator_plan` 判定 | | `summary.md` | 人类可读的审查界面 | `ready_for_operator_plan` 意味着 package 级别的证据通过了检查。这**并不** 意味着“立即更新”。一份真实的操作者计划仍然需要备份、维护 窗口期、特定于 runtime 的 postchecks 以及明确的审批边界。 ## 实地记录 当前的教训来自于真实的升级演练： - 将核心与外部 plugins 视为一个完整的依赖事务。 - 检查 plugins 和 native dependencies 的确切 `engines.node` 范围，而 不仅是 OpenClaw 核心。 - 当生命周期脚本可以从 GitHub 下载 二进制文件时，“离线安装”就不再是离线的了。 - 预先获取发布存档和 native artifacts，验证它们，并使用 SHA-256 绑定它们的字节。 - 使用真实的 plugin 集合运行模拟安装，而不是仅针对核心的 近似模拟。 - 在一次性的副本上演练状态迁移与恢复。 - 启动网关仅仅是技术上的激活；channel、memory、MCP、 attachment、voice 和 persona 行为仍然需要有序的 E2E 检查。 - 定义不可逆的激活点。在此之前，回滚可能是有效的； 在此之后，优先选择前向恢复，以免 channel 队列和加密状态 被倒回。 - 让策略工具去评判证据。不要让它们在不知不觉中成为更新 执行器。 ## 分享您的升级体验 每一次 OpenClaw 部署都会让这个流程学到新东西。如果某次更新 成功、失败、让您感到意外或需要变通方法，请提交一个 [升级体验 issue](https://github.com/pdurlej/openclaw-skill-safe-update/issues/new?template=upgrade-experience.yml)。 有用的报告包括： - 确切的当前版本与目标版本； - 安装架构与操作系统； - 相关的公共 plugin/package 名称； - 阻塞或出现回归的阶段； - 脱敏后的证据以及最终的修复方案。 切勿附带 tokens、私有配置值、对话、音频、 未脱敏的日志或生产数据库。经过验证后，可复用的经验教训将被整合回 skill、证据契约、示例和测试中。 ## 适用范围 首个稳定通道针对的是 Linux 上通过 npm 全局安装的 OpenClaw。其他 安装架构应通过显式的 adapter 实现，而不是假装 相同的回滚和激活规则适用于所有 runtime。 这是一个独立的社区项目，并非官方的 OpenClaw 发布或背书。 ## 许可证 [MIT](LICENSE)

标签：Homebrew安装, OpenClaw, SOC Prime, 开发工具, 暗色界面, 网络安全研究, 软件升级, 逆向工具