2026 OpenClaw 换机迁移与冷启动 Runbook：从拷贝目录到 Gateway 首次联通（systemd 与 launchd 清单）
把 ~/.openclaw 与工作区整棵拷到新机器后，常见症状是 openclaw 找不到、Gateway 起不来或通道「已配对但无响应」。本文按介质→环境→服务→通道分层，给 systemd 与 launchd 对照、七步冷启动顺序、可抄的快检命令，并与站内《安装路径对照》《status→doctor 阶梯》互补。
本文要点
1. 痛点拆解：拷贝≠可运行
换机时最容易产生的错觉是「目录一样就应该行为一样」。实际上 OpenClaw 同时依赖安装介质（哪条 openclaw 在 PATH 最前）、用户态配置树（~/.openclaw）、工作区与常驻服务的启动上下文。缺任一层都会在冷启动阶段表现为随机：有时 SSH 里手动能跑、断线或重启后又不起来。
- CLI 入口漂移：旧机用
npm -g、新机只有install.sh或反之，PATH未继承时直接command not found；拷贝配置并不能自动带来同一套二进制。若团队曾混用 pnpm 源码目录与全局包，还会出现「版本字符串一致但动态链接路径不同」的隐性分叉。 - daemon 上下文断裂：Linux 上习惯
systemd --user的Environment=HOME；macOS 上launchd若不显式设WorkingDirectory与PATH，Gateway 会以意外 cwd 启动，日志写错盘或读不到密钥。企业镜像里常见的「登录 shell 才注入的 nvm/pnpm 前缀」在 plist 里默认不存在，必须在单元里写死或用薄封装脚本导出环境。 - 冷启动顺序错误：未校验
openclaw.json与 18789 就去做通道 pairing，会误判为「通道坏了」；应先确认本机 Gateway 探针再查上游。否则你会在聊天侧反复解绑、重扫二维码，而根因只是本机监听地址绑在127.0.0.1却从另一网段来探。 - 卷与属主在迁移后错位：
rsync若以 root 拉树再切回业务用户，可能出现「配置可读、日志目录不可写」的半失败：进程活着但不落诊断信息，排障时间被拉长。
2. systemd 与 launchd：环境差异对照表
下表用于 Runbook 附件；列「第一站」指迁移后本机侧应先核对的项，与通道文档区分。跨平台团队建议把「服务定义文件」与「安装介质决策」放在同一变更单里评审：否则极易出现「单元照抄、环境未对齐」的无效迁移。
若目标机是 Mac 云且计划长期在线，优先在 launchd 层把绝对路径与固定日志文件写清，再讨论是否要 Docker 分区；反过来，在 Linux VPS 上若已用 systemd --user 管其他代理进程，可把 OpenClaw Gateway 与用户级 slice 一并纳入资源上限策略，避免与构建机争用 CPU 时拖垮响应。
| 维度 | Linux（systemd 用户单元） | macOS（launchd LaunchAgent） | 迁移第一站 |
|---|---|---|---|
| 环境变量 | Environment= 块或 drop-in | plist 无继承 shell；需写死或 wrapper | 核对 HOME、PATH 与 API Key 注入方式 |
| 工作目录 | WorkingDirectory= | WorkingDirectory 键 | 与 workspace 根一致，避免相对路径密钥 |
| 日志 | journalctl --user -u | StandardOutPath / StandardErrorPath | 先确认文件属主可写 |
| 开机拉起 | enable --user | RunAtLoad + bootstrap 域 | 重启后验收一次「非 SSH 子进程」 |
| 权限模型 | uid/gid + 可选 cgroup | 沙箱与 Full Disk Access 视工具链 | 钥匙串/文件隐私权限单独测 |
3. 七步冷启动：从目录到首次联通
七步刻意把「人眼能确认的输出」放在前，把「需要外部账号配合」的动作放在后，减少无效往返。演练时建议两人：一人改单元文件，一人只读 tail 日志，避免同时改配置与看通道。若夜间割接，把每步预计耗时写进窗口公告，便于值班长判断是继续还是回滚。
- 冻结版本与介质：记录旧机
openclaw --version、安装方式（npm / pnpm / 脚本 / 镜像 digest）；新机先按《安装路径对照》选定唯一入口，避免双二进制。若必须升级大版本，先在 staging 节点跑一遍 doctor 全绿再迁生产树。 - 同步目录树：
rsync -aH或等价方式拷贝~/.openclaw与工作区；排除缓存大目录若团队有规范；校验属主为运行服务的用户。同步后立刻做一次只读校验：关键文件 mtime 与大小是否与旧机摘要一致，防止传输中断被忽略。 - 权限与密钥可达：
ls -la ~/.openclaw；若用容器，核对卷映射与 uid，参见安装文 Docker 节。任何「宿主机工具链读容器内生成配置」的反模式都应在 Runbook 里标红禁止。 - 写服务单元：Linux 用
systemd --userunit 写明Environment；macOS 写 LaunchAgent plist，ProgramArguments用绝对路径指向openclaw。单元内建议显式写出监听地址与端口变量，避免默认值在版本间变化。 - 加载并冷启：
systemctl --user daemon-reload && restart或launchctl bootstrap+kickstart；确认进程父进程为 systemd/launchd。若仍看到 SSH 会话为父进程，说明未真正常驻化。 - 本机探针：
lsof -i :18789、最小 JSON 校验、openclaw doctor按阶梯执行；异常时对照《status→doctor》。探针未绿前不要动通道侧 token，以免把账号状态搅乱。 - 通道烟测：Gateway 正常后再做 pairing 或重连；把每步命令与输出片段记入变更单备审计。烟测通过后再开自动重启策略与监控探针，避免「告警先于稳定」。
快检命令块（可贴 Runbook）：which openclaw；openclaw --version；test -r ~/.openclaw/openclaw.json && echo ok；本机 HTTP/WS 探针按团队规范（如 curl 到绑定地址）。全绿再打开通道侧文档。若机器在公司代理后，再加一条从服务用户（非你个人 SSH 用户）执行的出口探测，避免「人能 curl、daemon 不能」的假阴性。
4. 可引用技术信息：路径、端口与审计字段
本节可直接贴进内部 wiki 的「附录」；与正文七步的关系是：正文讲顺序，本节列不得遗漏的检查项与证据字段，方便事后复盘。
- 配置单一路径：团队应规定「真」
openclaw.json所在主机与备份位置；迁移后 diff 旧新机文件，避免 silent merge。若使用配置管理工具，注明生成顺序：先落盘再 reload 服务，禁止边写边被进程读半截。 - 18789 争用：同机多实验实例须错端口或停旧服务；争用时常表现为「偶发能连」。Runbook 里写死「启新前 grep 端口」比口头约定可靠。
- 审计最小集：介质、版本号、unit/plist Label、镜像 digest、首次成功
doctor输出摘要、通道账号与配对时间戳。对外合规场景可再加操作者工号与双人复核记录。 - 回滚：保留旧机可工作的 unit 与全局包或镜像 tag；新机验证失败时能在 RTO 内切回。回滚演练应每季度做一次，避免密钥轮换后旧包不可用。
- 与安装文关系：介质与 plist/systemd 通过后，再处理 ClawHub Skill 等上层风险，参见 2026-04-16 审计清单文。
- 时区与日志时间戳：跨区迁移后若用文件日志排障，先统一 NTP 与时区显示，避免把「因果」看错一小时。
5. FAQ
Q：只拷了 workspace，没拷 ~/.openclaw，Gateway 能起来吗？
通常不能完整复现状态；至少缺密钥与本地状态。应两卷同迁或按文档重建密钥再配对。若必须重建，先在只读窗口导出旧机敏感字段清单，避免手工抄错。
Q：launchctl 显示已加载但端口未监听？
查 StandardErrorPath、WorkingDirectory、plist 内 PATH；再用 openclaw doctor 看 schema 与绑定地址。若错误日志为空，怀疑是否写到无权限路径导致静默失败。
Q：Linux 迁 macOS 后 systemd 单元能直接用吗？
不能；需改写成 LaunchAgent，并重做环境变量与日志路径验收。可把原 unit 的环境块逐行映射到 plist，避免遗漏。
Q：通道无响应但本机 18789 正常？
分层：先确认 Gateway 日志无报错，再查上游网络与白名单；勿先重置全部配置。若近期改过绑定 IP，优先核对防火墙与监听地址是否一致。
Q：同一台机器上想保留旧实例做对照？
务必错端口与错 Label，并在 Runbook 写清「对照实例不得写生产配置」。否则易出现双写同一 JSON 的灾难。
6. 从试用到生产：为什么原生 Mac 云更省事
换机 Runbook 的变量数与「能否 SSH 到与线上一致的宿主」强相关。笔记本与嵌套虚拟化会放大 PATH、卷与权限差；在专用 Mac 云上按 launchd 固化与安装文对齐，最容易把冷启动写成可审计步骤。需要隔离时再引入 Docker 分区，而不是在首迁混用多条安装路径。
对要把 OpenClaw 当「长期在线能力」的团队，建议把 Mac 云当成与生产构建同级的受管资产：磁盘分区、日志轮转、登录审计与节点标签一并纳入，而不是把 Gateway 当成个人开发机上的临时进程。这样换机时只需重复同一套 plist 与目录约定，而不是每人一套偏方。