將 OpenClaw 遷移到新機器¶
本指南說明如何在不重新進行入門引導的情況下，將 OpenClaw Gateway 閘道器 從一台機器遷移到另一台。
概念上，遷移很簡單：
- 複製 狀態目錄（
$OPENCLAW_STATE_DIR，預設：~/.openclaw/）— 其中包含設定、身分驗證、工作階段與頻道狀態。 - 複製您的 工作區（預設為
~/.openclaw/workspace/）— 其中包含您的代理程式檔案（記憶、提示詞等）。
但在 設定檔（profiles）、權限 與 不完整複製 上，常見一些踩雷點。
開始之前（您要遷移的內容）¶
1. 確認您的狀態目錄¶
多數安裝使用預設值：
- 狀態目錄：
~/.openclaw/
但如果您使用下列方式，路徑可能不同：
--profile <name>（通常會變成~/.openclaw-<profile>/）OPENCLAW_STATE_DIR=/some/path
若不確定，請在 舊 機器上執行：
openclaw status
在輸出中尋找 OPENCLAW_STATE_DIR／profile 的相關提及。如果你執行多個 gateway，請針對每個 profile 重複此步驟。
2. 確認您的工作區¶
常見預設值：
~/.openclaw/workspace/（建議的工作區）- 您自行建立的自訂資料夾
您的工作區是存放如 MEMORY.md、USER.md 與 memory/*.md 等檔案的位置。
3. 了解您將保留哪些內容¶
若您同時複製 狀態目錄 與 工作區，將保留：
- Gateway 閘道器 設定（
openclaw.json） - 身分驗證設定檔／API 金鑰／OAuth 權杖
- 會話歷史 + 代理狀態
- 頻道狀態（例如 WhatsApp 登入／工作階段）
- 您的工作區檔案（記憶、Skills 筆記等）
若您 只 複製工作區（例如透過 Git），則 不會 保留：
- cli/sessions.md
- 憑證
- 頻道登入
這些內容位於 $OPENCLAW_STATE_DIR 之下。
遷移步驟（建議）¶
步驟 0 — 建立備份（舊機器）¶
在 舊 機器上，請先停止 Gateway 閘道器，避免在複製過程中檔案變動：
openclaw gateway stop
（選用但建議）將狀態目錄與工作區封存：
# Adjust paths if you use a profile or custom locations
cd ~
tar -czf openclaw-state.tgz .openclaw
tar -czf openclaw-workspace.tgz .openclaw/workspace
若您有多個 profile／狀態目錄（例如 ~/.openclaw-main、~/.openclaw-work），請分別封存。
步驟 1 — 在新機器上安裝 OpenClaw¶
在 新 機器上，安裝 CLI（以及需要時的 Node）：
- 參見：Install
此階段若入門引導建立了新的 ~/.openclaw/ 也沒關係 — 您會在下一步覆蓋它。
步驟 2 — 將 state 目錄 + workspace 複製到新機器¶
請同時複製 兩者：
$OPENCLAW_STATE_DIR（預設為~/.openclaw/）- 您的工作區（預設為
~/.openclaw/workspace/）
常見方式：
- 使用
scp傳輸壓縮檔並解壓縮 - 透過 SSH
rsync -a - 使用外接硬碟
複製完成後，請確認：
- 已包含隱藏目錄（例如
.openclaw/） - 檔案擁有權正確，屬於執行 Gateway 閘道器 的使用者
步驟 3 — 執行 Doctor（遷移＋服務修復）¶
在 新 機器上：
openclaw doctor
Doctor 是「安全且穩定」的指令。它會修復服務、套用設定遷移，並對不一致之處提出警告。 It repairs services, applies config migrations, and warns about mismatches.
然後：
openclaw gateway restart
openclaw status
常見踩雷點（以及如何避免）¶
踩雷：profile／狀態目錄不一致¶
若舊的 Gateway 閘道器 是以某個 profile（或 OPENCLAW_STATE_DIR）執行，而新的 Gateway 閘道器 使用了不同的 profile，您可能會看到以下狀況：
- 設定變更未生效
- 頻道遺失／被登出
- 空的會話歷史
修正方式：使用相同的 profile／狀態目錄來執行您已遷移的 Gateway 閘道器，然後重新執行：
openclaw doctor
踩雷：只複製 openclaw.json¶
僅有 openclaw.json 並不足夠。許多提供者會將狀態儲存在以下位置： Many providers store state under:
$OPENCLAW_STATE_DIR/credentials/$OPENCLAW_STATE_DIR/agents/<agentId>/...
請務必遷移整個 $OPENCLAW_STATE_DIR 資料夾。
踩雷：權限／擁有權¶
如果你以 root 身分複製或變更使用者，gateway 可能無法讀取憑證／會話。
修正方式：確保 state 目錄 + workspace 的擁有者為執行 gateway 的使用者。
踩雷：在遠端／本機模式之間遷移¶
- 如果你的 UI（WebUI/TUI）指向遠端 gateway，則遠端主機擁有會話儲存區 + workspace。
- 遷移您的筆電並不會移動遠端 Gateway 閘道器 的狀態。
若您處於遠端模式，請遷移 閘道器主機。
踩雷：備份中的機密資料¶
$OPENCLAW_STATE_DIR 包含機密（API 金鑰、OAuth 權杖、WhatsApp 憑證）。請將備份視同正式環境的機密資料： Treat backups like production secrets:
- 以加密方式儲存
- 避免透過不安全的通道分享
- 如果懷疑金鑰外洩，請輪換金鑰
驗證檢查清單¶
在新機器上，請確認：
openclaw status顯示 Gateway 閘道器 正在執行- 您的頻道仍保持連線（例如 WhatsApp 不需要重新配對）
- 儀表板會開啟並顯示現有會話
- 您的工作區檔案（記憶、設定）皆存在