OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Maintenance

遷移指南

OpenClaw 支援三種移轉路徑：從另一個代理系統匯入、將現有安裝移至新機器，以及就地升級外掛。

從另一個代理系統匯入

內建的移轉提供者可將指示、MCP 伺服器、skills、模型設定，以及（選擇性加入的）API 金鑰帶入 OpenClaw。任何變更執行前都會先預覽計畫，且報告中的秘密會經過遮蔽。獨立執行的 openclaw migrate 會以經過驗證的備份為依據；全新初始設定中的匯入則會先暫存並驗證本機成品，提交設定後才發布，並且會在進行任何不可逆的外部啟用之前完成。

從 Claude 移轉

匯入 Claude Code 與 Claude Desktop 狀態，包括 CLAUDE.md、MCP 伺服器、skills 和專案命令。
從 Hermes 移轉

匯入 Hermes 設定、提供者、MCP 伺服器、記憶、skills，以及支援的 .env 金鑰。

命令列介面的進入點是 openclaw migrate。初始設定偵測到已知來源（openclaw onboard --flow import）時，也可以提供移轉選項。

將 OpenClaw 移至新機器

複製狀態目錄（預設為 ~/.openclaw/）及你的工作區，以保留下列內容：

  • 設定 — openclaw.json 及所有閘道設定。
  • 驗證 — 每個代理的 auth-profiles.json（API 金鑰與 OAuth），以及 credentials/ 下的任何頻道或提供者狀態。
  • 工作階段 — 對話記錄與代理狀態。
  • 頻道狀態 — WhatsApp 登入、Telegram 工作階段及類似內容。
  • 工作區檔案 — MEMORY.md、USER.md、skills 和提示詞。

移轉步驟

  • 停止閘道並備份

    在舊機器上停止閘道，以免檔案在複製過程中變更，然後封存：

    bash
    openclaw gateway stopcd ~tar -czf openclaw-state.tgz .openclaw

    若使用多個設定檔（例如 ~/.openclaw-work），請分別封存每一個設定檔。

  • 在新機器上安裝 OpenClaw

    在新機器上安裝命令列介面（若需要，也安裝節點）。初始設定即使建立了全新的 ~/.openclaw/ 也沒關係，你接下來會覆寫它。

  • 複製狀態目錄與工作區

    透過 scp、rsync -a 或外接硬碟傳輸封存檔，然後解壓縮：

    bash
    cd ~tar -xzf openclaw-state.tgz

    確認其中包含隱藏目錄，且檔案擁有權與將執行閘道的使用者相符。

  • 執行 Doctor 並驗證

    在新機器上執行 Doctor，以套用設定移轉並修復服務：

    bash
    openclaw doctoropenclaw gateway restartopenclaw status

    • 若 Telegram 或 Discord 使用預設環境變數後援（TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN），請確認已移轉的狀態目錄中，.env 包含這些金鑰，且不會印出秘密值：

    bash
    awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

    當已啟用的預設 Telegram 或 Discord 帳號未設定權杖，且 Doctor 程序無法取得對應的環境變數時，openclaw doctor 也會發出警告。

    常見問題

    設定檔或狀態目錄不一致

    若舊閘道使用 --profile 或 OPENCLAW_STATE_DIR，而新閘道未使用，頻道會顯示為已登出，且工作階段將為空。請使用與已移轉內容相同的設定檔或狀態目錄啟動閘道，然後重新執行 openclaw doctor。

    只複製 openclaw.json

    僅有設定檔並不足夠。模型驗證設定檔位於 agents/<agentId>/agent/auth-profiles.json 下，頻道與提供者狀態則位於 credentials/ 下。請一律移轉整個狀態目錄。

    權限與擁有權

    若以 root 身分複製或切換了使用者，閘道可能無法讀取認證資訊。請確保狀態目錄與工作區由執行閘道的使用者擁有。

    遠端模式

    若你的使用者介面指向遠端閘道，工作階段與工作區由遠端主機持有。請移轉閘道主機本身，而不是你的本機筆記型電腦。請參閱常見問題。

    備份中的秘密

    狀態目錄包含驗證設定檔、頻道認證資訊及其他提供者狀態。請以加密方式儲存備份、避免使用不安全的傳輸管道，若懷疑資料外洩，請輪替金鑰。

    驗證檢查清單

    在新機器上確認：

    • [ ] openclaw status 顯示閘道正在執行。
    • [ ] 頻道仍保持連線（不需要重新配對）。
    • [ ] 儀表板可正常開啟並顯示現有工作階段。
    • [ ] 工作區檔案（記憶、設定）均存在。

    就地升級外掛

    就地外掛升級會保留相同的外掛 ID 與設定鍵，但可能會將磁碟上的狀態移至目前的配置。外掛專用的升級指南與其頻道文件放在一起：

    • Matrix 移轉：加密狀態的復原限制、自動快照行為，以及手動復原命令。

    相關內容

    Was this useful?
    On this page

    On this page