1. 痛点拆解：拷走仓库≠拷走运行态
（1）状态目录与 workspace 混为一谈：很多人把「技能脚本、提示词、工具配置」放在项目里，却把会话、渠道绑定、Gateway 缓存留在用户态目录；换机后只恢复 git 仓库，表现为 CLI 能跑但频道侧「幽灵会话」或空配置。（2）密钥与 OAuth 刷新令牌的落点分散：Slack、Discord、企业 IM 的 token 往往既在配置文件也在运行时加密存储里；只备份明文 openclaw.json 而不备份完整状态树，会在新机上触发重新授权，若未按顺序停 Gateway，会出现双端抢 session 的竞态。（3）launchd 与 shell 环境不一致：launchd 不会继承你在 .zshrc 里 export 的 API Key；迁机时若把变量只写在交互 shell，而 plist 未同步，会出现「终端里手动起 Gateway 正常、重启后 plist 拉起就缺变量」的经典错位。（4）远程 Mac 上的用户与会话边界：VNC/SSH 登录用户与跑 Gateway 的用户必须一致；换机到远程节点时若混用 root 与登录用户，文件权限与 Keychain 访问会分叉，排错成本指数上升。
2. 分工表：该备份什么（2026 实操口径）
| 对象 | 典型路径 / 含义 | 是否应纳入「冷迁移包」 |
|---|---|---|
| 用户态状态树 | ~/.openclaw（版本差异下子目录名可能微调，以官方文档为准） |
是：含渠道绑定、缓存与本地密钥材料；迁机核心 |
| Workspace / 项目 | 技能、脚本、openclaw.json（若放在仓内） |
是：但需与状态树同一快照时间，避免 schema 半一致 |
| launchd / 服务单元 | ~/Library/LaunchAgents/ 下对应 plist |
是：记录运行用户、工作目录、环境变量键名 |
| 容器卷（若用 Docker） | compose 中命名的 volume 或绑定挂载点 | 条件：与《Docker 生产》路径一致时再整体快照 |
| 系统 Keychain 中的秘密 | 部分渠道或工具把刷新令牌放进钥匙串 | 谨慎：优先走官方「重新授权」流程，避免粗暴导出违反合规 |
3. 五步迁移（冻结→打包→校验→冷启动→重配对）
步骤 1：冻结写入：在旧机先停 Gateway 与相关 launchd job（或 compose 栈），确认没有后台会话仍在写状态目录；若不停服就打包，快照里可能含半写入的 SQLite/锁文件，恢复后随机损坏。步骤 2：打「成对快照」：同一时刻打包 ~/.openclaw 与 workspace（含 lockfile）；若用 Docker，再对卷做只读拷贝或镜像导出，三者时间戳对齐。步骤 3：校验与脱敏：在新机解压前，用校验和确认包完整；检查配置里是否硬编码了旧机 hostname、绝对路径或内网 URL，需要批量替换为远程节点可达地址。步骤 4：冷启动 Gateway：先以最小配置启动（仅本地 loopback 或管理端口），跑 openclaw doctor 或项目文档中的自检；确认日志目录、权限与监听端口与 plist 一致。步骤 5：频道重配对：按渠道官方流程重新 OAuth / webhook 注册——很多系统不允许同一 bot 多实例并行；应在旧机彻底下线后再在新机启用，避免重复投递与签名冲突。
NUMBERS / THRESHOLDS（可引用）
① 快照三件套：~/.openclaw + workspace + plist（或 compose 文件与卷清单）缺一则视为不完整迁移。
② 环境变量：launchd plist 与交互 shell 的 export 必须显式对齐；至少核对 API/代理/时区三类键。
③ 频道切换：旧实例停止与新实例拉起的时间窗建议 ≥ 渠道文档建议的冷却时间；无文档时以分钟级灰度为准。
④ 迁到远程 Mac：SSH 用户 = 跑 Gateway 用户；会话工具（Screen Sharing）与无人值守 launchd 不要混用不同 UID。
⑤ 回滚预案：保留旧机只读快照至少一个发布周期，再销毁可写副本。
4. 参数与排错：为什么「启动了却无回复」
迁移后最常见的假阳性是进程存活、健康检查通过，但频道消息进不来。第一查监听地址：是否从 127.0.0.1 改成了内网 IP 却忘了同步反向代理或防火墙规则。第二查 webhook URL：云平台控制台里的回调地址是否仍指向旧公网 IP 或已失效的隧道域名。第三查时钟与 TLS：远程 Mac 若 NTP 漂移过大，部分签名验证会失败；企业 MITM 代理若替换证书，也会导致 TLS 握手静默失败。第四查工具 profile：若你在旧机用 tools.profile 限制了可执行路径，新机路径变化会导致工具调用被静默拒绝——对照《sessions_spawn 与 tools.profile》逐项放开或改写白名单。
5. 决策表：继续本机 vs 迁到远程 Mac Gateway
| 维度 | 留在本机 | 迁到远程 Mac（常驻） |
|---|---|---|
| 可用性 | 受合盖、睡眠、差旅影响大 | 7×24 边界清晰，适合渠道客服类负载 |
| 权限与 Keychain | 与桌面会话绑定，调试方便 | 需明确无人值守策略，避免 GUI 弹窗阻塞 |
| 网络 | 家庭宽带出口可能变 IP | 可用固定 egress 或隧道域名，利于 webhook |
| 成本 | 硬件折旧与电费隐性 | 租赁透明，适合 SLA 导向团队 |
6. FAQ：迁移中最常被问到的五个问题
问：能不能只同步 workspace，不同步 ~/.openclaw？可以跑通部分 CLI 场景，但只要涉及渠道与会话连续性，就强烈不建议；你会在排错上花掉远超备份体积的时间。问：Docker 与裸机混迁怎么选？优先保持目标侧与文档一致的一种形态；跨形态迁移等于同时做换机与换栈，风险叠加。问：plist 里能不能写明文 API Key？能跑但不推荐；更稳妥是文件权限受限的 env 文件 + plist 引用，或托管密钥方案。问：远程 Mac 上要不要开屏幕共享？日常运维可用 SSH；仅当工具强依赖 GUI 或首次授权时才短时开 VNC，并在变更单记录。问：旧机要不要立即 wipe？建议先并行观察一个完整业务周期，再销毁可写数据。
7. 深度分析：迁移本质是「状态与身份」一起搬家
2026 年 OpenClaw 一类代理栈的复杂度，早已不在「能不能装」，而在状态如何被多个进程读写、渠道如何把外部身份映射到内部会话。换机如果只搬代码不搬状态，就像搬办公室只搬了桌椅没搬保险柜——门能开，业务不能续。workspace 里的 openclaw.json 往往描述「意图与工具白名单」，而用户态目录承载「已经与外部世界握过手的凭据与缓存」；二者必须同事务级一致，否则就会出现 doctor 全绿、频道全哑的诡异分裂。
launchd 与交互式 shell 的分裂，是 Mac 迁移中第二常见的坑。许多开发者在终端里 export 了模型供应商的 API Key，却在 plist 里忘记写入，结果 launchd 拉起的 Gateway 读不到密钥，日志里却只有含糊的 401。反过来，有人在 plist 里塞满环境变量，却忘了给日志目录与状态目录正确的用户所有权，进程能启动但无法 rotate 日志，最终在磁盘满时一次性暴雷。迁移清单里应把「环境变量三件套」——plist、shell profile、CI/远程脚本——放在同一页表格里交叉核对。
频道重配对不是「重复劳动」，而是安全与一致性机制：多数 IM 与协作平台假设 bot endpoint 唯一；双活会导致重复投递、乱序响应，甚至被平台风控。迁移 runbook 里应写明旧实例下线确认（进程、监听、DNS、控制台回调四联查），再执行新实例上线与灰度观察。对于企业微信、飞书、Slack 等不同渠道，冷却时间与 IP 白名单策略各异，不宜用一份模板套所有客户。
迁到远程 Mac 时，还要把「图形会话」与「无人值守服务」从心智上拆开：前者适合偶发调试与授权弹窗，后者应是可审计、可重启、可回滚的守护路径。MACGPU 一类节点提供的价值，是把 Apple Silicon 与统一内存留在「正确的一层」跑长期 Gateway，让笔记本回归交互与创作，而不是 7×24 的热节流与合盖断流。这与「安装路径选型」一脉相承：先定栈与状态真源，再谈渠道与 SLA。
8. 收束：换机可以快，但不能省步骤
（1）当前方案的客观限制：状态目录随版本演进可能调整布局，迁移包应记录 OpenClaw 版本号；跨大版本时优先参考发行说明中的 breaking changes。密钥与合规策略可能禁止直接拷贝钥匙串，需要预留重新授权窗口。（2）为什么远程 Mac 常更省心：固定拓扑、固定用户与固定出口，减少「笔记本即服务器」带来的长尾故障。（3）与 MACGPU 的衔接：若你希望把 Gateway 迁到可租赁、可预期的 Apple 生态节点上完成验收，再决定长期拓扑，可从首页了解套餐与帮助入口。