OpenClaw 更新全流程指南从 Agent Skill 路由到安全中断、会话恢复与版本验证【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本篇技术指南围绕 OpenClaw 仓库内的openclaw-update运维技能Skill展开系统讲解如何对一个已存在的本地或远端 OpenClaw Gateway 实例执行常规更新包括解析安装归属人owner、按安装形态路由到正确的更新工作流、遵守旧版继续服务、候选版本先验证再激活的更新纪律以及更新期间的中断与自动会话恢复语义。读完本文你将掌握如何判断一次更新请求该走哪条路径、如何在不停掉在途工作的前提下完成升级、如何验证真正在服务的版本而非仅确认进程健康并能在更新失败时利用openclaw update status / repair / cleanup完成诊断与收尾。一、openclaw-update技能是什么定位与职责边界在 OpenClaw 仓库中openclaw-update是一个定义在 .agents/skills/openclaw-update/SKILL.md 的 Agent 运维技能同一份定义也镜像在.claude/skills/openclaw-update/SKILL.md其元数据声明为名称openclaw-update描述将对现有本地或远端 OpenClaw Gateway 的常规更新请求路由到其安装归属人并具备自动会话恢复能力当存在部署专属技能时应优先让位给那些技能。它的职责边界非常明确只处理对既有 Claw/Gateway 的常规更新请求。以下事项明确不在该技能的工作范围内发布验证release validation与发布publication全新安装new installation与当前安装无关的其他主机unrelated hosts创建新的部署器或调度器——应沿用现有的更新工作流。换言之这是一个路由与纪律型技能它不发明新的部署机制而是确保每次更新都走安装形态对应的既有路径。仓库中与之一脉相承的配套文档包括 docs/install/updating.md面向用户的更新指南与 docs/cli/update.mdopenclaw update命令的完整 CLI 参考后者还进一步拆分为 docs/cli/update/how-updates-run.md更新如何运行、docs/cli/update/status-and-history.md状态与运行历史、docs/cli/update/repair-and-recovery.md修复与恢复。二、第一步解析安装归属人Resolve the owner任何更新请求的第一步都不是直接执行命令而是先确认这台安装归谁管、由哪个更新工作流负责。技能要求从以下维度解析 owner主机host安装运行在哪台机器运行时用户runtime user以哪个系统用户运行profile / 状态根目录profile/state rootOpenClaw 的配置与状态存放位置服务service由 systemd、launchd、LaunchAgent 还是手动进程托管正在运行的可执行文件/发布版本running executable/release当前实际服务的是哪个构建更新归属人update owner谁对该安装拥有更新权限。技能特别提醒当前所在仓库或 shell CLI 可能属于另一套安装——不要理所当然地认为我在这个仓库里就能更新这个仓库对应的服务。同时私有访问细节与状态信息不得进入公开产物例如不要在执行记录里泄露凭据、密钥或会话内容。解析完 owner 后读取 owner 的运行手册runbook选择匹配的更新工作流。三、第二步按安装形态选择更新工作流路由表这是整个技能的核心骨架。原文以路由表的形式给出四类安装及其对应更新路径完整继承如下安装形态更新路径规范的 live main 检出与 macOS 应用openclaw-live-updater操作员配置的 Team serverupdate-team-server其他托管部署容器、声明式安装等部署专属技能/运行手册 既有 owner标准包安装或单用户源码Updating 与 update CLI 契约在目标主机/profile 上使用归属 CLI3.1 前两条路径部署专属技能openclaw-live-updater.agents/skills/openclaw-live-updater/SKILL.md负责维护规范的 live OpenClaw main 检出要求检出保持干净、独立、完整、停留在main且只做 fast-forward每次更新都通过确定性脚本执行锁、构建、Gateway 证明、Mac 应用工作共享一把检出级锁只允许在受控的 Codex 工作树里做修复绝不直接修改 live 镜像。它还会执行精确 SHA 的构建证明dist/.buildstamp、dist/.runtime-postbuildstamp、dist/build-info.json.commit必须等于更新后的afterSha并对重启窗口的 Gateway 日志做审计。update-team-server.agents/skills/update-team-server/SKILL.md面向操作员配置的 Team server保留既有的每小时定时器作为唯一节奏绝不暂停它去制造空窗证明也绝不另建调度器部署、Gateway 生命周期、回滚与恢复全部由规范 owner 单独控制。3.2 后两条路径标准 CLI 更新对于标准包安装或单用户源码检出使用目标主机/profile 上的归属 CLI 执行openclaw update。推荐用法是 docs/install/updating.md 中的openclaw update该命令会自动探测安装类型npm、pnpm、Bun 或 git在旧 Gateway 继续服务的同时校验候选版本然后激活并验证更新。切换频道或锁定版本openclaw update --channel beta openclaw update --channel extended-stable openclaw update --channel dev openclaw update --dry-run # 仅预览不落地 openclaw update --tag beta # 一次性按 npm beta dist-tag 固定包 openclaw update --no-restart openclaw update --yes openclaw update --json各选项的语义来自 docs/cli/update.md 的参数表选项说明--no-restart成功后跳过 Gateway 服务重启会重启的包更新会在命令成功前验证重启服务上报了预期版本--channel stable\|extended-stable\|beta\|dev设置更新频道并在核心更新成功后持久化extended-stable 仅限包安装--tag dist-tag\|version\|spec仅对本次更新覆盖包目标不能与 effectiveextended-stable频道组合包安装拒绝main简写--dry-run预览计划动作频道/标签/目标/重启流程不写配置、不安装、不同步插件、不重启--json输出机器可读的UpdateRunResultJSON--timeout seconds每步超时默认1800秒--yes跳过确认提示例如降级确认--accept-capabilities接受插件在更新同步中经审查的能力变化关于频道语义需要特别澄清latest 保留已配置频道默认更新遵循保存的update.channel不会擅自跨频道跳级。latest main 才是开发流显式请求latest main才选择开发源码流对应标准 CLI 的--channel dev。预览并报告真实服务的 SHA开发预检可能选中一个更早但仍可构建的提交因此必须预览目标并报告实际服务的 SHA而非想当然地认为最新 main 就是刚拉取的 commit。不得自动接受未经批准的降级或插件能力变更降级必须显式确认docs/cli/update.md 中明确Downgrades require confirmation because older versions can break configuration。3.3 更新执行的通用纪律路由到具体工作流之后必须遵守该工作流的命令、锁、备份/迁移要求、恢复与清理约定并且不要在单独托管的发布或运行中的容器里应用标准 CLI 更新改动正在被 live Gateway 使用的文件覆盖脏检出dirty checkout。从源码结构看这些约束在实现层面有对应支撑更新 CLI 的逻辑集中在 src/cli/update-cli/ 目录包括update-command-run.ts更新命令运行、update-command-admission准入、update-command-activation激活、update-command-candidate-exit候选退出等模块并配合src/infra/update-run-ledger.ts的更新运行账本ledger来记录每次运行的阶段、结果与失败步骤——这正是每次更新有唯一运行 ID、可持久查询这一事实的实现基础。四、更新期间的中断与自动会话恢复一次更新请求天然包含例行的重启与有界中断但这受部署策略约束。技能强调三个关键语义合格会话自动恢复不要重复提问只要 agent、回复或任务仍在活跃就不应仅仅因为还有任务在跑而反复征求批准。应使用 owner 的优雅排空graceful drain与保恢复的中断方式。不得用粗暴手段制造空闲任务取消task cancellation、会话中止session abort、清空队列都可能丢弃工作不能用它们来人为制造空闲状态或手动重放已恢复的轮次。PTY 不存活Gateway 终端 PTY 属于进程内存进程结束即丢失不会被恢复。关于重启后什么能活下来docs/gateway/restart-recovery.md 给出了权威的状态矩阵节选状态存储重启后行为会话历史每 agent 一个 SQLite 数据库原样保留会话从已存 transcript 继续被中断的主会话轮次每 agent SQLite 会话行与 transcript启动后数秒内自动恢复或调和子 agent 运行SQLite共享状态库启动时恢复注册表中断运行恢复后台任务SQLite共享状态库启动时调和孤儿运行被恢复或标记丢失排队的外发投递SQLite 投递队列重启后排空未送达回复重试定时cron任务SQLite cron 存储调度持久化启动时重新武装Gateway 终端 PTY进程内存随旧进程结束不回话恢复因此正确姿势是让 Restart recovery 拥有恢复行为与限制更新请求本身只负责触发优雅排空——Gateway 停止接收新工作等待活跃 agent 轮次与后台任务结束默认排空预算 5 分钟大多数重启因此什么都不会打断。如果 owner缺少受控中断能力则应在权限范围内报告或修复该缺口不得臆造强制标志force flags、不得绕过持久化/兼容性门禁、不得重复询问中断批准问题。五、验证证明预期版本在服务而非进程健康更新完成的判定标准不是构建成功对方已确认或旧进程还健康。技能要求使用 owner 的验证手段证明预期版本/提交正在服务the intended version/commit is servingRPC/健康检查与已配置频道可用UI/资源在启用时能通过真实入口ingress加载同时检查启动/恢复错误且不暴露机密。配套实操docs/install/updating.md 的After updating章节建议在手动安装后执行三步openclaw doctor # 迁移配置、审计 DM 策略、检查网关健康 openclaw gateway restart openclaw health如果使用了解包的 Chrome 扩展还应运行openclaw browser doctor --browser-profile chrome出现版本不匹配警告时从chrome://extensions重新加载扩展。最终报告需要记录正在服务的版本与剩余问题。openclaw update status含--json暴露activeRun与lastRun可在重启后读取活动或最近一次运行报告更新历史由持久化的运行账本支撑失败步骤与恢复指引都记录在案。六、更新后的收尾清理恢复数据更新验证通过且对话确认无碍后可以预览并退休迁移恢复原件migration recovery originalsopenclaw update cleanup --dry-run # 元数据预览Gateway 可保持运行要点来自 docs/install/updating.md应用时需自行停止 Gateway等待其他 SQLite 维护结束并停止 session-listing 等数据库读取 watcher直到openclaw update cleanup退出只读连接可能改动 WAL/SHM 边车文件并使验证失效确认默认是 No自动化必须显式传--yes包括使用--json时cleanup 会永久放弃对合格原件的回滚能力但不会停止或重启 Gateway也不能替代更新前的备份。若更新历史停留在 in-progress 而 Gateway 健康可尝试openclaw update repair openclaw update status七、从聊天发起更新/update与update.run更新不一定都在终端完成。docs/install/updating.md 说明用户可以让 agent 执行更新或在 Discord 等已连接聊天中发送/update自然语言请求走既有gateway工具的update.run动作minimal、coding、messaging 三类 profile 暴露该更新动作但不授予配置读取或其他 Gateway 控制权/update是模型无关的兜底即使没有可用模型或无法访问gateway工具也能工作工具、斜杠命令与 Control UI 共用同一个 Gateway 更新处理器与授权检查更新过程中聊天内会按里程碑收到最多四条通知接受确认 →⏳ Restarting the gateway now (vfrom → vto)…→ Back on vto, verifying…→ 最终报告外部更新/重启通知只发往commands.ownerAllowFrom中列出的目标能聊天不等于拥有 owner 权限agent绝不应从聊天 shell 执行npm install -g openclaw或停止 Gateway 服务而应使用/update或更新动作以保证重启与通知协同。八、给 Agent 与操作员的行动清单把整个技能浓缩为可执行的检查清单解析 owner确认主机、运行时用户、profile/state 根、服务、当前可执行文件/版本、更新归属人私有凭据与状态不得进入公开产物。读 runbook按路由表选工作流live main/macOS →openclaw-live-updaterTeam server →update-team-server容器等托管部署 → 部署专属技能与既有 owner标准包/单用户源码 →openclaw update目标主机上归属 CLI。沿用既有更新工作流不新建 deployer/scheduler遵守锁、备份/迁移、恢复与清理要求不触碰 live Gateway 正在使用的文件、不覆盖脏检出。理解latest与latest main的区别预览目标并报告实际服务 SHA不自动接受未经批准的降级或插件能力变更。接受有界中断合格会话自动恢复不因活跃任务反复询问PTY 不存活用 owner 的优雅排空而非任务取消/清队列来制造空闲。验证证明预期版本/提交正在服务、RPC/健康与频道可用、UI/资源经真实入口加载报告服务中的版本与剩余问题。收尾openclaw doctor、必要时openclaw gateway restart、openclaw health验证后按需openclaw update cleanup --dry-run预览并退休迁移原件历史异常用openclaw update status/openclaw update repair诊断。相关资源Updating用户更新指南Docker/Podman/K8s 镜像替换、openclaw update推荐用法、升级后三步验证。update CLI 参考完整选项表、update wizard、SSH 自动化ssh -T usergateway-host openclaw update --yes /dev/null。How an update runs频道切换、候选验证、重启交接、Git 检出流。Repair and recovery失败更新后的 triage、update repair与update cleanup。Status and run historyupdate status、持久运行账本与各次运行报告。Restart recovery重启/崩溃后什么会存活、排空预算、自动恢复语义。openclaw-live-updater 技能 与 update-team-server 技能两条部署专属更新路径的实现纪律。实现参考src/cli/update-cli/更新命令运行、准入、激活、候选退出与src/infra/update-run-ledger.ts更新运行账本。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考