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

Maintenance

從 Hermes 遷移

內建的 Hermes 遷移提供者會偵測 ~/.hermes 中的狀態、在套用前預覽每項變更、遮蔽計畫與報告中的機密，並在接觸任何內容前寫入經驗證的 OpenClaw 備份。

兩種匯入方式

初始設定精靈

偵測 ~/.hermes 中的 Hermes，並在套用前顯示預覽。

bash
openclaw onboard --flow import

或指定特定來源：

bash
openclaw onboard --import-from hermes --import-source ~/.hermes

命令列介面

使用 openclaw migrate 執行指令碼化或可重複的作業。完整參考請參閱 openclaw migrate。

bash
openclaw migrate hermes --dry-run    # 僅預覽openclaw migrate apply hermes --yes  # 略過確認並套用

當 Hermes 位於 ~/.hermes 以外的位置時，請加上 --from <path>。

匯入的內容

模型設定
  • 從 Hermes config.yaml 匯入預設模型選擇。
  • 從 providers 與 custom_providers 匯入已設定的模型提供者及自訂 OpenAI 相容端點。
MCP 伺服器

從 mcp_servers 或 mcp.servers 匯入 MCP 伺服器定義。

工作區檔案
  • SOUL.md 與 AGENTS.md 會複製到 OpenClaw 代理程式工作區。
  • memories/MEMORY.md 與 memories/USER.md 會附加至對應的 OpenClaw 記憶檔案，而非覆寫它們。
記憶設定

OpenClaw 檔案記憶的預設記憶設定。Honcho 等外部記憶提供者會記錄為封存或需手動檢閱的項目，讓你能審慎地移轉它們。

Skills

位於 skills/<name>/ 下且包含 SKILL.md 檔案的 Skills 會連同 skills.config 中各 Skill 的設定值一起複製。

驗證憑證

互動式 openclaw migrate 會在匯入驗證憑證前詢問，且預設選取「是」。接受後會從 OpenCode 的 auth.json 匯入 OpenCode OpenAI OAuth 與 GitHub Copilot 項目，以及支援的 Hermes .env 鍵。Hermes 自身 auth.json 中的 OAuth 項目屬於舊版狀態：它們會顯示為需要手動重新驗證或由 Doctor 處理的項目，而不會匯入即時驗證設定。非互動式執行時可使用 --include-secrets 匯入憑證、使用 --no-auth-credentials 完全略過憑證匯入，或使用初始設定精靈的 --import-secrets 旗標。

僅保留於封存的內容

提供者會將下列項目複製到遷移報告目錄供手動檢閱，但不會將它們載入即時 OpenClaw 設定或憑證：

  • plugins/
  • sessions/
  • logs/
  • cron/
  • mcp-tokens/
  • state.db

由於不同系統間的格式與信任假設可能產生差異，OpenClaw 拒絕自動執行或信任這些狀態。檢閱封存內容後，請手動移轉所需項目。

建議流程

  • 預覽計畫

    bash
    openclaw migrate hermes --dry-run

    計畫會列出所有即將變更的內容，包括衝突、略過的項目與敏感項目。輸出中看似機密的巢狀鍵會被遮蔽。

  • 建立備份並套用

    bash
    openclaw migrate apply hermes --yes

    OpenClaw 會在套用前建立並驗證備份。此非互動式範例只匯入非機密狀態。若要以互動方式回答憑證提示，請執行時省略 --yes；若要在無人值守的執行中包含支援的憑證，請加上 --include-secrets。

  • 執行 Doctor

    bash
    openclaw doctor

    Doctor 會重新套用任何待處理的設定遷移，並檢查匯入期間產生的問題。

  • 重新啟動並驗證

    bash
    openclaw gateway restartopenclaw status

    確認閘道運作正常，且匯入的模型、記憶與 Skills 均已載入。

    • 衝突處理

    當計畫回報衝突（目標位置已存在檔案或設定值）時，套用作業會拒絕繼續。

    全新安裝通常不會發生衝突。當你對已有使用者編輯內容的設定重新執行匯入時，通常才會出現衝突。

    如果套用過程中出現衝突（例如設定檔發生非預期的競爭條件），Hermes 會將其餘相依設定項目標記為 skipped，原因為 blocked by earlier apply conflict，而不會只寫入部分內容。遷移報告會記錄每個受阻項目，讓你能解決原始衝突後重新執行匯入。

    機密

    互動式 openclaw migrate 會詢問是否匯入偵測到的驗證憑證，且預設選取「是」。

    • 接受後會從 OpenCode 的 auth.json 匯入 OpenCode OpenAI OAuth 與 GitHub Copilot 項目，以及支援的 .env 鍵。Hermes 自身 auth.json 中的 OAuth 項目則會列入報告，供手動重新進行 OpenAI 驗證或由 Doctor 修復。
    • 使用 --no-auth-credentials，或在提示中回答「否」，即可只匯入非機密狀態。
    • 在無人值守的 --yes 執行中，使用 --include-secrets 匯入憑證。
    • 使用初始設定精靈的 --import-secrets 旗標，從精靈匯入憑證。

    自動化所用的 JSON 輸出

    bash
    openclaw migrate hermes --dry-run --jsonopenclaw migrate apply hermes --json --yes

    使用 --json 但未使用 --yes 時，套用作業會輸出計畫而不變更狀態，這是命令列介面與共用指令碼最安全的模式。

    疑難排解

    套用因衝突而遭拒

    檢查計畫輸出。每項衝突都會指出來源路徑與現有目標。請逐項決定要略過、編輯目標，或使用 --overwrite 重新執行。

    Hermes 位於 ~/.hermes 以外的位置

    傳入 --from /actual/path（命令列介面）或 --import-source /actual/path（初始設定）。

    初始設定拒絕匯入現有設定

    初始設定匯入需要全新的設定。請重設狀態並重新執行初始設定，或直接使用 openclaw migrate apply hermes；後者支援 --overwrite 與明確的備份控制。

    API 金鑰未匯入

    互動式 openclaw migrate 只有在你接受憑證提示時才會匯入 API 金鑰。非互動式 --yes 執行需要加上 --include-secrets；初始設定匯入則需要 --import-secrets。只有支援的 .env 鍵會被辨識，其他 .env 變數會被忽略。

    相關內容

    • openclaw migrate：完整的命令列介面參考、外掛合約與 JSON 結構。
    • 初始設定：精靈流程與非互動式旗標。
    • 遷移：在不同機器間移轉 OpenClaw 安裝。
    • Doctor：遷移後的健康狀態檢查。
    • 代理程式工作區：SOUL.md、AGENTS.md 與記憶檔案的所在位置。
    Was this useful?
    On this page

    On this page