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_HOME 與使用中的 Hermes 設定檔，並在 macOS/Linux 上回退至 ~/.hermes，或在 Windows 上回退至 %LOCALAPPDATA%\hermes。它會在套用前預覽每項變更，並在計畫與報告中遮蔽祕密。獨立執行的 openclaw migrate 會寫入經驗證的備份；全新初始設定路徑會暫存設定、認證資訊與檔案，並且只在匯入的推論通過驗證後才發布。明確指定的 --from 路徑一律優先。

兩種匯入方式

初始設定精靈

偵測使用中的 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  # 套用並略過確認

加入 --from <path> 可覆寫 Hermes 主目錄／設定檔探索。

匯入的內容

模型設定
  • 來自 Hermes config.yaml 的預設模型選擇。
  • 來自 model、providers 與 custom_providers 的已設定模型提供者及自訂端點，包括目前的 Hermes Chat Completions、Codex Responses 與 Anthropic Messages 傳輸方式。
MCP 伺服器

來自 mcp_servers 或 mcp.servers 的 MCP 伺服器定義，包括停用狀態、逾時、平行工具支援、OAuth 範圍、相容的 TLS 欄位，以及原生／資源／提示詞工具原則。常值環境變數與標頭需要取得匯入認證資訊的同意。Hermes 專屬的生命週期、取樣、引導式資訊擷取、預檢、保持連線、CA 套件組、受密碼保護的用戶端金鑰，以及預先註冊的 OAuth 用戶端設定，會成為需手動檢閱的項目，而非無效的 OpenClaw 設定。

工作區檔案
  • SOUL.md 與 AGENTS.md 會複製到 OpenClaw 代理程式工作區。
  • memories/MEMORY.md 與 memories/USER.md 會附加至相符的 OpenClaw 記憶檔案，而非覆寫這些檔案。
  • 僅記憶體介面的行為不同：初始設定記憶體頁面與控制介面的記憶體匯入頁面會將這兩個檔案複製到 memory/imports/hermes/ 下以供索引召回，並保持現有工作區記憶不變。
記憶體設定

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

Skills

系統會遞迴探索 skills/ 下任何位置含有 SKILL.md 檔案的 Skills，將其扁平化至 OpenClaw 工作區的 skill 目錄，並連同其支援檔案一起複製。來自 skills.config 的各 skill 設定值會予以保留。

驗證認證資訊

互動式 openclaw migrate 會在匯入驗證認證資訊前詢問，且預設選取「是」。可接受的匯入項目包括目前的 Hermes OpenAI Codex OAuth 項目、OpenCode OpenAI OAuth 與 GitHub Copilot 項目，以及支援的 Hermes .env 金鑰。非互動式匯入請使用 --include-secrets，略過認證資訊請使用 --no-auth-credentials，或使用初始設定的 --import-secrets 旗標。匯入 Hermes OAuth 後，請勿讓 Hermes 與 OpenClaw 繼續使用相同的重新整理授權；在同時執行兩者前，請重新驗證其中一方。

僅保留於封存的內容

提供者會將下列項目複製到遷移報告目錄以供手動檢閱，但不會將其載入使用中的 OpenClaw 設定或認證資訊：

  • plugins/
  • sessions/
  • logs/
  • cron/
  • mcp-tokens/
  • plans/、workspace/、skins/ 與 kanban/
  • pairing/ 與 platforms/ 儲存區，以及閘道路由／程序狀態
  • state.db、hermes_state.db、projects.db、response_store.db、memory_store.db、verification_evidence.db、kanban.db 與 retaindb_queue.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 均已載入。

    • 衝突處理

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

    全新安裝時很少發生衝突。通常是在已包含使用者編輯內容的設定上重新執行匯入時才會出現。

    如果衝突在套用途中浮現（例如設定檔發生非預期的競爭情況），該項目會回報為衝突，而彼此獨立的檔案、Skills、認證資訊、封存內容與設定項目則會繼續處理。解決衝突項目後重新執行匯入；相同的記憶體匯入具有冪等性。

    祕密

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

    • 接受後會匯入目前的 Hermes OpenAI Codex OAuth 項目、OpenCode OpenAI OAuth 與 GitHub Copilot 項目，以及支援的 .env 金鑰。
    • 若只要匯入非祕密狀態，請使用 --no-auth-credentials，或在提示時回答「否」。
    • 若要在無人值守的 --yes 執行中匯入認證資訊，請使用 --include-secrets。
    • 若要從精靈匯入認證資訊，請使用初始設定精靈的 --import-secrets 旗標。

    用於自動化的 JSON 輸出

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

    使用 --json 且未使用 --yes 時，套用作業會輸出計畫但不變更狀態，這是 CI 與共用腳本最安全的模式。

    疑難排解

    套用因衝突而遭拒

    檢查計畫輸出。每項衝突都會指出來源路徑與現有目標。請逐項決定要略過、編輯目標，或使用 --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