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。進行任何變更前會先預覽計畫、報告中的秘密資訊會經過遮蔽，而套用作業則有經過驗證的備份保障。

從 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

    在新機器上安裝命令列介面（如有需要，也安裝 Node）。即使初始設定建立了新的 ~/.openclaw/ 也沒關係，下一步會覆寫它。

  • 複製狀態目錄與工作區

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

    bash
    cd ~tar -xzf openclaw-state.tgz

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

  • 執行診斷並驗證

    在新機器上執行診斷工具，以套用設定遷移並修復服務：

    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 帳號未設定權杖，且診斷程序無法取得對應的環境變數時，openclaw doctor 也會發出警告。

    常見問題

    設定檔或狀態目錄不一致

    如果舊閘道使用 --profile 或 OPENCLAW_STATE_DIR，而新閘道沒有使用，頻道會顯示為已登出，工作階段也會是空的。請使用遷移時的相同設定檔或狀態目錄啟動閘道，然後再次執行 openclaw doctor。

    只複製 openclaw.json

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

    權限與擁有權

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

    遠端模式

    如果你的使用者介面連線至遠端閘道，工作階段與工作區由遠端主機管理。請遷移閘道主機本身，而不是你的本機筆記型電腦。請參閱常見問題。

    備份中的秘密資訊

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

    驗證清單

    請在新機器上確認：

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

    就地升級外掛

    就地升級外掛會保留相同的外掛識別碼與設定鍵，但可能會將磁碟上的狀態移至目前的目錄配置。外掛專用的升級指南位於其頻道文件旁：

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

    相關內容

    Was this useful?
    On this page

    On this page