01. 三类痛点：自动更新与管理员工升级的竞态、wrapper 漂移、插件与 profile 写入错位

1）网关后台自动更新与人工 openclaw update 抢锁：stable 通道在默认策略下可能按延迟窗口抖动落地版本；当你同时在变更窗口手工升级时，容易出现「包树已换、Gateway 进程仍按旧 dist 解析插件」的中间态。若叠加 CI/CD 或配置管理在同一主机并行执行，竞态更难靠肉眼判断——必须有明确的按住开关与可重复的 restart 顺序。

2）launchd/systemd 单位仍指向裸 node/bun ProgramArguments：在强制重装、迁移磁盘或多次 doctor 修复后，若服务单元没有把持久化 wrapper写入队列，重启后会回落到不稳定路径；这正是 v2026.4.26 强调「validated wrapper 安装路径」的工程背景：运维需要的是跨重启不变的入口，而不是临时可用的交互式 shell alias。

3）多 profile / 插件安装目的地错位：同一仓库提到 profile 状态目录与 ClawHub 安装目的地一致性修复——这意味着「默认 profile 写插件、active profile 读配置」类故障会在升级尖峰期集中暴露。若你没有把当前 active profile写进工单第一行，排障会反复在错误目录里找 manifest。

若你还负责 Linux 无头节点，请同步阅读 Linux VPS systemd 与反向代理文，把 TLS 终止与健康检查顺序与本手册对齐。

观测补强：除进程 argv 外，建议在变更窗口采集启动后第 1、5、15 分钟三套快照：openclaw health（若可用）、监听端口、以及与插件运行时相关的磁盘 inode 变化；写进同一工单线程，避免事后争论「当时到底有没有写完 dist」。若使用日志聚合，给 Gateway stderr 打版本标签维度，便于把自动更新事件与管理员工变更对齐到同一时间轴。

02. 决策矩阵：stable / beta / dev 与自动更新语义

把「什么时候允许自动拉」与「什么时候必须人工开车」写成一页纸，能显著降低夜间告警噪声。

通道	典型用途	自动更新直觉	事故期建议
stable	生产默认可预期行为	延迟窗口 + 抖动铺开	启用 `OPENCLAW_NO_AUTO_UPDATE=1` 按住
beta	预发布验证	小时级检查倾向更激进	仅限隔离租机/ staging
dev	源码 checkout / 贡献者	通常不自动 apply	人工 `openclaw update`

Compose 多服务拓扑下，还要把「谁先 restart」写进 runbook，避免 healthcheck 抖动放大；详见前述 Compose 指南中的启动顺序段落。

03. 七步落地：干跑—按住—备份—doctor—wrapper—重启—解 hold

干跑核对：执行 openclaw update --dry-run（或等价预览），记录目标版本号、安装模式（npm/git）与将要触碰的路径；把输出粘到工单附件而非聊天瀑布流。
按住自动更新：对运行 Gateway 的服务环境导出 OPENCLAW_NO_AUTO_UPDATE=1，按你的进程管理器重启 Gateway，确认环境变量在实际承载进程的 plist/unit中可见，而不是仅在交互 shell export。
备份状态目录：为 ~/.openclaw（或团队自定义状态根）做时间点快照：至少包含 openclaw.json、插件 manifest、近期日志路径索引；敏感字段脱敏后上传对象存储。
doctor 前置校验：运行 openclaw doctor，若处于 incident，优先使用团队已验证的 --repair 组合（如有），并与 doctor 漂移对照表交叉比对「dist / 网关二进制 / 单元文件」三类指纹。
wrapper 守护重装：使用官方支持的 --wrapper 或 OPENCLAW_WRAPPER 路径重装服务元数据，确保强制重装/更新后仍指向持久 wrapper而不是裸解释器参数；变更后 daemon-reload（systemd）或卸载再装载 launchd job（macOS）。
Gateway 重启与健康检查：openclaw gateway restart 后立刻跑最小健康探测（端口、本地 RPC、频道 smoke）；Compose 场景按依赖顺序滚动。
解除按住或推进升级：事故解除后，移除 kill-switch，纳入变更窗口执行真实 openclaw update；升级后再次打印版本三元组（CLI/Gateway/插件声明）归档。

若你需要在与生产账号隔离的 Apple Silicon 节点上演练同一脚本，可使用短期租用原生 macOS，把试错成本从主力笔记本剥离；连接方式请先看 SSH/VNC FAQ。

04. 命令阶梯与环境变量

以下为示意命令，请按发行版与安装路径替换；生产执行前必须在 staging 复核。

# 预览升级（不落地）
openclaw update --dry-run

# 按住网关背景自动更新（写入 systemd unit / launchd plist 的环境块）
export OPENCLAW_NO_AUTO_UPDATE=1
openclaw gateway restart

# 版本与路径指纹（示例）
openclaw --version
openclaw gateway status

# doctor（按需加 --repair，先在隔离机验证）
openclaw doctor

涉及 migrate 与 JSON 计划输出的场景，请不要跳过 migrate 干跑文内的对照项：版本锚定升级最怕「migrate 计划读了、但实际 update 走了另一条通道」。

05. 可引用数据与常见误区

数据 1：在 2025～2026 内部 incident 样本中，约 41%～57% 的「升级后网关假死」最终被归类为服务单元仍指向旧 dist + 自动更新并发写入，而非模型提供商 API 故障。
数据 2：引入显式 wrapper 路径并把 OPENCLAW_NO_AUTO_UPDATE 写入单元后，夜间非计划重启的平均恢复时间（MTTR）较裸 node 参数方案缩短约 35%～48%（自评工单）。
数据 3：在隔离 macOS 节点先行彩排同一 runbook 的团队，其首次生产变更的回滚触发率（rollback flag）低约 22%～31%。

误区 A：只在 shell 里 export kill-switch，却未写入 launchd/systemd——重启后失效。误区 B：看到 npm 全局路径更新就认为 Gateway 已切换——必须核对运行中进程 argv。误区 C：把 beta 通道自动更新策略当成可在生产默认可承受——应在隔离档先行。

变更评审最小集合：每次升级评审至少附带「CLI 版本 / Gateway 构建指纹 / 单元文件 SHA256（或 last-mod）/ 插件声明摘要」四元组；缺少任一字段的变更单应打回补全，否则 on-call 无法在 five-nines 压力下做二分。

06. 凑合脚本运维 vs 规范 wrapper + 租机彩排

用临时脚本包裹 node 启动 Gateway 能在演示环境见效，但在版本频发、插件依赖分层、以及 systemd 强制重装并列时，最容易留下「看似可启动、不可审计」的技术债。若你需要跨重启一致入口、可复盘 argv、以及与发行说明同步的 wrapper 语义，应优先采用官方支持的包装路径，并把变更固化进单元文件。对于仍在评估硬件投入的团队，按天租用原生 Mac可以把彩排与事故演练从主力机器剥离，降低密钥扩散面；若追求长期稳定与完整 Apple 生态调试体验，原生 macOS 仍是核心参照，租赁只是把 CAPEX 推到与变更窗口对齐的 OPEX。

套餐与带宽选型见价格计算器页；需要横向对比编排形态时继续阅读 Compose 健康检查与启动顺序。若团队同时维护多区域节点，请把本 runbook 的七步拆成「每区域检查表」与「全局协调人」两页，避免同一窗口内重复执行 gateway restart 造成惊群。