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 與目錄約定，而不是每人一套偏方。