將 OpenClaw 遷移到新機器

本指南將 OpenClaw Gateway 從一台機器遷移到另一台，無需重新執行初始設定。

概念上遷移很簡單：

複製狀態目錄（$OPENCLAW_STATE_DIR，預設：~/.openclaw/）— 包含設定、授權、session 和頻道狀態。
複製workspace（預設 ~/.openclaw/workspace/）— 包含 agent 檔案（記憶、提示詞等）。

但常見的坑在於profile、權限和不完整複製。

開始前（你要遷移什麼）

1) 確認狀態目錄

大多數安裝使用預設值：

狀態目錄： ~/.openclaw/

但如果你使用了以下設定，可能不同：

--profile <name>（通常變成 ~/.openclaw-<profile>/）
OPENCLAW_STATE_DIR=/some/path

不確定的話，在舊機器上執行：

openclaw status

查看輸出中提到的 OPENCLAW_STATE_DIR / profile。如果執行多個閘道，對每個 profile 重複。

2) 確認 workspace

常見預設值：

~/.openclaw/workspace/（推薦的 workspace）
你自己建立的自訂資料夾

你的 workspace 存放 MEMORY.md、USER.md、memory/*.md 等檔案。

3) 了解會保留什麼

如果複製兩者（狀態目錄和 workspace），你會保留：

閘道設定（openclaw.json）
授權 profile / API 金鑰 / OAuth token
Session 歷史 + agent 狀態
頻道狀態（如 WhatsApp 登入/session）
Workspace 檔案（記憶、技能筆記等）

如果只複製 workspace（如透過 Git），你不會保留：

session
憑證
頻道登入

這些存在 $OPENCLAW_STATE_DIR 中。

遷移步驟（推薦）

步驟 0 — 備份（舊機器）

在舊機器上，先停止閘道以避免複製中途檔案變動：

openclaw gateway stop

（選用但推薦）封存狀態目錄和 workspace：

# 如果使用 profile 或自訂位置，請調整路徑
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

如果有多個 profile/狀態目錄（如 ~/.openclaw-main、~/.openclaw-work），各自封存。

步驟 1 — 在新機器上安裝 OpenClaw

在新機器上安裝 CLI（及 Node，如需要）：

請參閱：安裝

這個階段如果初始設定建立了新的 ~/.openclaw/ 是正常的——下一步你會覆蓋它。

步驟 2 — 將狀態目錄 + workspace 複製到新機器

複製兩者：

$OPENCLAW_STATE_DIR（預設 ~/.openclaw/）
workspace（預設 ~/.openclaw/workspace/）

常見方式：

scp 封存檔並解壓
透過 SSH 使用 rsync -a
外接硬碟

複製後確認：

隱藏目錄已包含（如 .openclaw/）
檔案擁有者正確，為執行閘道的使用者

步驟 3 — 執行 Doctor（遷移 + 服務修復）

在新機器上：

openclaw doctor

Doctor 是「安全無聊」的指令。它修復服務、套用設定遷移，並警告不一致之處。

然後：

openclaw gateway restart
openclaw status

常見陷阱（及如何避免）

陷阱：profile / state-dir 不匹配

如果舊閘道使用了 profile（或 OPENCLAW_STATE_DIR），而新閘道使用了不同的，你會看到：

設定變更無效
頻道消失 / 登出
空的 session 歷史

修正：使用你遷移的相同 profile/state dir 執行閘道/服務，然後：

openclaw doctor

陷阱：只複製 `openclaw.json`

openclaw.json 不夠。許多供應商在以下位置儲存狀態：

$OPENCLAW_STATE_DIR/credentials/
$OPENCLAW_STATE_DIR/agents/<agentId>/...

務必遷移整個 $OPENCLAW_STATE_DIR 資料夾。

陷阱：權限 / 擁有者

如果以 root 複製或換了使用者，閘道可能無法讀取憑證/session。

修正：確認狀態目錄 + workspace 由執行閘道的使用者擁有。

陷阱：在 remote/local 模式間遷移

如果 UI（WebUI/TUI）指向遠端閘道，session 儲存 + workspace 屬於遠端主機。
遷移你的筆電不會移動遠端閘道的狀態。

如果在 remote 模式，遷移的是閘道主機。

陷阱：備份中的秘密

$OPENCLAW_STATE_DIR 包含秘密（API 金鑰、OAuth token、WhatsApp 憑證）。將備份視為正式環境秘密：

加密儲存
避免透過不安全頻道傳輸
懷疑洩漏時輪換金鑰

驗證清單

在新機器上確認：

openclaw status 顯示閘道運行中
頻道仍然連線（如 WhatsApp 不需要重新配對）
Dashboard 開啟並顯示現有 session
Workspace 檔案（記憶、設定）存在