遷移前：了解 OpenClaw 的資料結構
OpenClaw 有兩個關鍵目錄需要遷移，外加一個可選的第三個：
| 目錄 | 預設路徑 | 內容 |
|---|---|---|
| State 目錄 | ~/.openclaw/ |
設定檔（openclaw.json）、API 金鑰、OAuth 憑證、頻道認證、session 歷史、代理狀態 |
| Workspace 目錄 | ~/.openclaw/workspace/ |
MEMORY.md、USER.md、SOUL.md、memory/*.md、skills、提示詞檔案 |
| 環境變數（可選） | .env 檔案 |
如果你有透過環境變數覆寫設定的話 |
重要提醒： 如果你只複製 openclaw.json，登入憑證不會跟著過來。你必須複製整個 ~/.openclaw/ 資料夾，因為憑證和代理狀態都存放在裡面。
步驟一：在 Mac 上備份
# 1. 確認你的資料目錄位置
openclaw status
# 注意輸出中的 OPENCLAW_STATE_DIR 或 profile 名稱
# 2. 停止 Gateway（防止複製過程中檔案變動）
openclaw gateway stop
# 3. 打包 state 目錄
cd ~
tar -czf openclaw-state.tgz .openclaw/
# 4. 如果 workspace 在不同位置（某些舊版安裝用 ~/clawd）
# tar -czf openclaw-workspace.tgz clawd/
使用社群遷移 Skill（可選的自動化方式）
社群有一個專門的遷移 skill 可以自動化整個流程：
npx playbooks add skill openclaw/skills --skill migrate
# 匯出（在 Mac 上執行）
bash scripts/export.sh -o /tmp --include-sessions
# 這會產生：clawdbot-export-YYYYMMDD_HHMMSS.tar.gz
匯出內容預設包含：
| 元件 | 預設包含 | 需要旗標 |
|---|---|---|
| Workspace | ✓ | — |
| Config（openclaw.json） | ✓ | — |
| 託管 skills | ✓ | — |
| WhatsApp session | ✓ | — |
| Session 對話紀錄 | ✗ | --include-sessions |
| 敏感憑證 | ✗ | --include-credentials（小心處理） |
步驟二：準備 Ubuntu VPS
# SSH 進入你的 VPS
ssh ubuntu@YOUR_VPS_IP
# 更新系統
sudo apt update && sudo apt upgrade -y
# 安裝 Node.js 22+（使用 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
# 安裝 OpenClaw
npm install -g openclaw@latest
# 執行 onboarding（先建立基礎結構，之後會覆蓋）
openclaw onboard
# 這會建立一個新的 ~/.openclaw/，沒關係，下一步會覆寫
步驟三：傳輸檔案到 Ubuntu
# 從你的 Mac 執行 scp
scp ~/openclaw-state.tgz ubuntu@YOUR_VPS_IP:~/
# 或者如果你用了遷移 skill 的匯出檔
scp /tmp/clawdbot-export-*.tar.gz ubuntu@YOUR_VPS_IP:~/
步驟四：在 Ubuntu 上還原
方法 A：手動還原
# 在 Ubuntu VPS 上執行
cd ~
# 停止新建的 gateway
openclaw gateway stop
# 備份新建的設定（以防萬一）
cp -r ~/.openclaw ~/.openclaw.backup
# 解壓縮並覆蓋
tar -xzf openclaw-state.tgz
# 確認檔案權限正確
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/credentials 2>/dev/null
方法 B：使用遷移 skill 還原
bash scripts/import.sh clawdbot-export-YYYYMMDD_HHMMSS.tar.gz --force
步驟五：調整設定（Mac → Ubuntu 的差異）
遷移後有幾個地方需要手動調整：
Gateway 綁定設定
# 確保綁定到 localhost（安全性）
openclaw config set gateway.bind loopback
# 驗證
netstat -an | grep 18789 | grep LISTEN
# 應該顯示 127.0.0.1:18789 而非 0.0.0.0:18789
瀏覽器設定
Mac 上的瀏覽器路徑在 Ubuntu 上無效，需要更新：
# 移除 macOS 的路徑設定
openclaw config set browser.executablePath "/usr/bin/google-chrome"
# 或
openclaw config set browser.executablePath "/usr/bin/chromium-browser"
# 如果要用無頭模式（推薦用於 VPS）
openclaw config set browser.defaultProfile "openclaw"
openclaw config set browser.headless true
安裝無頭瀏覽器依賴（Ubuntu 常見問題）
# 安裝 Chromium 和必要的共享函式庫
sudo apt install -y chromium-browser
# 或
sudo apt install -y google-chrome-stable
# 安裝 Playwright 需要的依賴（如果用 openclaw 託管瀏覽器）
npx playwright install-deps chromium
步驟六：執行 Doctor 修復
這是最關鍵的一步。openclaw doctor 會自動偵測和修復遷移問題：
openclaw doctor --fix
Doctor 會處理：
- 服務修復
- 設定遷移（舊版結構升級到新版 schema）
- 權限檢查
- 路徑一致性驗證
步驟七：驗證遷移成功
# 確認 gateway 正常運行
openclaw status
# 檢查頻道是否還連接（如 WhatsApp）
openclaw channels list
# 確認 workspace 檔案存在
ls ~/.openclaw/workspace/
# 應該看到 MEMORY.md、USER.md、memory/ 等
# 確認 session 歷史
openclaw sessions list
# 啟動 gateway
openclaw gateway start
步驟八：安全加固（必做）
# 設定防火牆
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw limit 22/tcp
sudo ufw enable
# 如果需要 Tailscale 遠端存取（推薦）
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
常見踩坑與解決方案
Session 歷史消失
如果你只複製了 workspace 而沒有複製 state 目錄，session 紀錄會遺失。Session 存放在 ~/.openclaw/agents/<agentId>/sessions/ 下的 JSONL 檔案中。
頻道需要重新配對
如果你只還原了 workspace，WhatsApp 等頻道的登入 session 不會保留，需要重新配對。
權限錯誤
如果你用 root 複製檔案，gateway 可能無法讀取。確保執行 gateway 的使用者對 state 目錄和 workspace 有完整存取權：
sudo chown -R $USER:$USER ~/.openclaw/
Profile 路徑不匹配
如果你在舊機器上使用了自訂的 OPENCLAW_STATE_DIR 或 profile，新機器上也要用相同的設定，否則會看到空的 session 歷史。
舊版目錄名稱
某些早期安裝可能還在使用 ~/.clawdbot 或 ~/clawd。打開 openclaw.json 確認你的 agent workspace 設定指向正確路徑。
推薦架構：Mac + Ubuntu 混合模式
遷移完成後，考慮保留 Mac 作為 node 連接到 Ubuntu 上的 Gateway：
Ubuntu VPS（Gateway 主機）
├── 24/7 運行 Gateway
├── 無頭瀏覽器自動化
├── WhatsApp/Telegram/Slack 頻道
└── Cron 排程任務
Mac（作為 Node 連接）
├── 本機開發測試
├── Canvas 視覺化工作區
├── Voice Wake 語音喚醒
└── macOS 專屬工具（iMessage 等）
這樣你可以在 Mac 上開發 skills 和測試，同時讓 Ubuntu 處理所有生產環境的自動化工作。透過 Tailscale 建立安全的私有網路連接兩者，不需要開放任何公共連接埠。