2026 在租用的 ProxyMac Mac mini 上升级 OpenClaw：版本锁定与 launchctl 回滚
自动化网关「老化」极快：一次次 semver 小版本就可能改写 TLS 默认值、重命名 CLI 开关，或收紧 LaunchAgent 曾假设稳定的沙箱路径。在 香港、日本、韩国、新加坡或美国 的 ProxyMac Mac mini 上，运维契约可以概括为三件事：可预测的重启、可审计的回滚、以及在客户感知漂移前就触发的 健康探针。本文说明 谁应把住升级闸门（平台负责人，而非每个特性团队各自为政），给出带具体阈值的 升级前矩阵（系统卷空闲 ≥20%、Webhook 5xx 滚动 24 小时 <0.5%），记录配置树的 快照 + 校验和 仪式，按 网关恢复 对齐 launchctl bootout / kickstart -k 顺序，用表格对比 四种回滚策略，并把升级后钩子接到 健康探针 与 JSONL 日志，最后以无人值守升级 FAQ 收尾。请把 配置 GitOps 与 部署排错 视为同一变更窗口内的必读材料。
锁定版本、收敛爆炸半径、生产拒绝「永远 latest」
为每个生产 plist 标注合规团队可引用的 精确二进制路径 或容器 digest。开发笔记本「永远拉 main」可以接受；在跑清结算、模型路由或夜间 ETL 的租用金属上，它就是事故发生器。在与生产 同区域 保留一台 预发 mini 以对齐 TLS 时延—价格页 列出 ProxyMac 当前托管 M4 级 mini 的五个区域。
- 在 OpenClaw YAML 旁检入 语义化 lockfile，让 diff 表达意图而非惊吓。
- 尊重 ThrottleInterval：升级链不得快于 launchd 允许 worker 排空的速度。
- 密钥轮换 与二进制升级解耦—按独立日历轮转。
升级前检查矩阵
| 信号 | 绿灯阈值 | 若红灯 |
|---|---|---|
| APFS 空闲空间 | 系统卷 ≥ 20% | 先归档 JSONL、清理缓存再动二进制 |
| Webhook 5xx 占比（滚动 24h） | < 0.5% | 先修上游—升级会掩盖根因 |
| LaunchAgent 最近退出码 | 前 3 次重启均为 0 | 在统一日志中读崩溃循环 |
| 时钟偏差 | 相对 NTP < 2 秒 | 升级后 JWT/HMAC 校验会莫名失败 |
为配置、队列与模型缓存做快照并校验
先将完整 ~/Library/Application Support/OpenClaw 树（具体目录因安装而异）复制到同卷的按日期 tar—事故中跨 SMB 卷拷贝最容易产生半写入。对 tar 运行 shasum -a 256 并把哈希写入变更单。保留策略与 日志指南 对齐，便于法务回答「我们保留了什么」而无需突击取证。
git push。在 Git 标签旁用元数据记录它们的版本。
launchctl 顺序：bootout、等待、bootstrap、kickstart
现代 macOS 奖励耐心。卸载 Agent 后，等到 launchctl print user/$(id -u)/com.openclaw.gateway 不再显示运行中 PID，再把新构建安装到 带版本号目录 并维护 current 符号链接，然后才执行 launchctl bootstrap 与 launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway。跳过等待会让 worker 仍绑定旧共享内存区—正是 排错文 里那种「周二前都好好的」缺陷类。
# 示例顺序—请替换为你的 Label
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist
sleep 2
# 在此切换版本目录与 symlink
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist
launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway
回滚矩阵：软链切换 vs 全量 tar 恢复 vs 重装
| 策略 | 回退耗时 | 风险 | 适用场景 |
|---|---|---|---|
| 指回上一 semver 目录的 symlink | 30–90 秒 | 遗漏数据库迁移 | 纯二进制/API 回归 |
| 完整 tarball 还原 | 3–10 分钟 | 覆盖飞行中队列文件 | 怀疑配置损坏 |
| 重装 mini（最后手段） | 15–45 分钟 | 人为恢复失误 | 内核扩展或 TCC 纠缠 |
| 区域级切到第二台 mini | 受 DNS TTL 约束 | 共享 DB 时脑裂 | 重大 CVE 无热修 |
升级后健康钩子与可观测性
在 kickstart 后首 15 分钟，对本地管理端口跑合成探针、采样队列深度，并用成本仅几美分的 canary 提示词验证出站模型调用。告警应绑定相对变更前基线的 p95 延迟偏移 >15%，而非仅硬失败。导出带 upgrade_from、upgrade_to、change_ticket 字段的结构化行，便于日志管道按版本分面事故。
常见问题
维护窗口能用 brew upgrade 吗？ 仅当合规允许生产使用 Homebrew 路径；许多 ProxyMac 客户改为把 tarball 安装到 /opt/openclaw/releases/<semver>。
迁移应在新二进制启动前还是后跑？ 向后兼容迁移应 在 接流量 之前 完成；破坏性迁移应以跨数天的两阶段特性开关发布。
XPC 助手呢？ 按主 plist 旁文档的依赖顺序启动—父子关系图见 重启恢复。
为何在 ProxyMac Mac mini 上沉淀升级纪律
Apple Silicon M4 mini 提供长期稳定主机名、可预测性能，以及蓝绿切换时与生产并排跑 canary worker 的余量—而不必每周二与宿主机邻居争抢。把自动化锚定在 港/日/韩/新/美，大版本仍由人把关，把机架琐事交给不必自己上架的硬件。需要 GUI 授权时退回 VNC；SSH 被代理整形时读本周同发的 企业 CONNECT 指南。
