從 OpenClaw 遷移

hermes claw migrate 命令可將你的 OpenClaw（或舊版 Clawdbot/Moldbot）設置導入到 Hermes。本指南詳細說明了遷移內容、配置鍵映射關係，以及遷移後需要驗證的事項。

快速開始

# 預覽將發生的操作（不會修改文件）
hermes claw migrate --dry-run

# 運行遷移（默認不包含密鑰）
hermes claw migrate

# 完整遷移（包含 API 密鑰）
hermes claw migrate --preset full

遷移默認從 ~/.openclaw/ 讀取數據。如果你仍保留舊版的 ~/.clawdbot/ 或 ~/.moldbot/ 目錄，系統會自動檢測。同樣，舊版配置文件名（如 clawdbot.json、moldbot.json）也會被自動識別。

選項

選項	描述
`--dry-run`	預覽將要遷移的內容，但不寫入任何數據。
`--preset <name>`	`full`（默認，包含密鑰）或 `user-data`（不包含 API 密鑰）。
`--overwrite`	在發生衝突時覆蓋現有的 Hermes 文件（默認：跳過）。
`--migrate-secrets`	包含 API 密鑰（當使用 `--preset full` 時默認開啟）。
`--source <path>`	自定義 OpenClaw 目錄路徑。
`--workspace-target <path>`	指定 `AGENTS.md` 的存放位置。
`--skill-conflict <mode>`	`skip`（默認）、`overwrite` 或 `rename`。
`--yes`	跳過確認提示。

遷移內容

人格、記憶與指令

內容	OpenClaw 源路徑	Hermes 目標路徑	說明
人格設定	`workspace/SOUL.md`	`~/.hermes/SOUL.md`	直接複製
工作區指令	`workspace/AGENTS.md`	`--workspace-target` 指定的 `AGENTS.md`	需要 `--workspace-target` 標誌
長期記憶	`workspace/MEMORY.md`	`~/.hermes/memories/MEMORY.md`	解析為條目，與現有內容合併，去重。使用 `§` 作為分隔符。
用戶檔案	`workspace/USER.md`	`~/.hermes/memories/USER.md`	與記憶相同的條目合併邏輯
每日記憶文件	`workspace/memory/*.md`	`~/.hermes/memories/MEMORY.md`	所有每日文件合併至主記憶文件

所有工作區文件還會檢查 workspace.default/ 作為備用路徑。

技能（4 個來源）

來源	OpenClaw 位置	Hermes 目標位置
工作區技能	`workspace/skills/`	`~/.hermes/skills/openclaw-imports/`
管理/共享技能	`~/.openclaw/skills/`	`~/.hermes/skills/openclaw-imports/`
個人跨項目技能	`~/.agents/skills/`	`~/.hermes/skills/openclaw-imports/`
項目級共享技能	`workspace/.agents/skills/`	`~/.hermes/skills/openclaw-imports/`

技能衝突由 --skill-conflict 處理：skip 保留現有 Hermes 技能，overwrite 替換之，rename 創建 -imported 複製版本。

模型與提供方配置

內容	OpenClaw 配置路徑	Hermes 目標路徑	說明
默認模型	`agents.defaults.model`	`config.yaml` → `model`	可為字符串或 `{primary, fallbacks}` 對象
自定義提供方	`models.providers.*`	`config.yaml` → `custom_providers`	映射 `baseUrl`、`apiType`（"openai"→"chat_completions"，"anthropic"→"anthropic_messages"）
提供方 API 密鑰	`models.providers.*.apiKey`	`~/.hermes/.env`	需啟用 `--migrate-secrets`。詳見下方 API 密鑰解析

Agent 行為

內容	OpenClaw 配置路徑	Hermes 配置路徑	映射關係
最大輪次	`agents.defaults.timeoutSeconds`	`agent.max_turns`	`timeoutSeconds / 10`，上限為 200
詳細模式	`agents.defaults.verboseDefault`	`agent.verbose`	"off" / "on" / "full"
思考力度	`agents.defaults.thinkingDefault`	`agent.reasoning_effort`	"always"/"high" → "high"，"auto"/"medium" → "medium"，"off"/"low"/"none"/"minimal" → "low"
壓縮功能	`agents.defaults.compaction.mode`	`compression.enabled`	"off" → false，其他值 → true
壓縮模型	`agents.defaults.compaction.model`	`compression.summary_model`	直接複製字符串
人類延遲	`agents.defaults.humanDelay.mode`	`human_delay.mode`	"natural" / "custom" / "off"
人類延遲時間	`agents.defaults.humanDelay.minMs` / `.maxMs`	`human_delay.min_ms` / `.max_ms`	直接複製
時區	`agents.defaults.userTimezone`	`timezone`	直接複製字符串
執行超時	`tools.exec.timeoutSec`	`terminal.timeout`	直接複製（字段為 `timeoutSec`，非 `timeout`）
Docker沙箱	`agents.defaults.sandbox.backend`	`terminal.backend`	"docker" → "docker"
Docker 鏡像	`agents.defaults.sandbox.docker.image`	`terminal.docker_image`	直接複製

會話重置策略

OpenClaw 配置路徑	Hermes 配置路徑	說明
`session.reset.mode`	`session_reset.mode`	"daily"、"idle" 或兩者兼有
`session.reset.atHour`	`session_reset.at_hour`	每日重置的小時數（0–23）
`session.reset.idleMinutes`	`session_reset.idle_minutes`	無操作分鐘數

注意：OpenClaw 還有 session.resetTriggers（一個簡單的字符串數組，如 ["daily", "idle"]）。如果未找到結構化 session.reset，遷移將回退至從 resetTriggers 推斷。

MCP 服務器

OpenClaw 字段	Hermes 字段	說明
`mcp.servers.*.command`	`mcp_servers.*.command`	Stdio 傳輸
`mcp.servers.*.args`	`mcp_servers.*.args`
`mcp.servers.*.env`	`mcp_servers.*.env`
`mcp.servers.*.cwd`	`mcp_servers.*.cwd`
`mcp.servers.*.url`	`mcp_servers.*.url`	HTTP/SSE 傳輸
`mcp.servers.*.tools.include`	`mcp_servers.*.tools.include`	工具過濾
`mcp.servers.*.tools.exclude`	`mcp_servers.*.tools.exclude`

TTS（文本轉語音）

TTS 設置從兩個 OpenClaw 配置位置讀取，優先級如下：

messages.tts.providers.{provider}.*（標準位置）
頂層 talk.providers.{provider}.*（回退位置）
舊版扁平鍵 messages.tts.{provider}.*（最舊格式）

項目	Hermes 目標位置
提供商名稱	`config.yaml` → `tts.provider`
ElevenLabs 語音 ID	`config.yaml` → `tts.elevenlabs.voice_id`
ElevenLabs 模型 ID	`config.yaml` → `tts.elevenlabs.model_id`
OpenAI 模型	`config.yaml` → `tts.openai.model`
OpenAI 語音	`config.yaml` → `tts.openai.voice`
Edge TTS 語音	`config.yaml` → `tts.edge.voice`
TTS 資產	`~/.hermes/tts/`（文件複製）

消息平臺

平臺	OpenClaw 配置路徑	Hermes `.env` 變量	說明
Telegram	`channels.telegram.botToken`	`TELEGRAM_BOT_TOKEN`	Token 可為字符串或 SecretRef
Telegram	`credentials/telegram-default-allowFrom.json`	`TELEGRAM_ALLOWED_USERS`	從 `allowFrom[]` 數組中以逗號連接
Discord	`channels.discord.token`	`DISCORD_BOT_TOKEN`
Discord	`channels.discord.allowFrom`	`DISCORD_ALLOWED_USERS`
Slack	`channels.slack.botToken`	`SLACK_BOT_TOKEN`
Slack	`channels.slack.appToken`	`SLACK_APP_TOKEN`
Slack	`channels.slack.allowFrom`	`SLACK_ALLOWED_USERS`
WhatsApp	`channels.whatsapp.allowFrom`	`WHATSAPP_ALLOWED_USERS`	通過 Baileys QR 配對認證（非 token）
Signal	`channels.signal.account`	`SIGNAL_ACCOUNT`
Signal	`channels.signal.httpUrl`	`SIGNAL_HTTP_URL`
Signal	`channels.signal.allowFrom`	`SIGNAL_ALLOWED_USERS`
Matrix	`channels.matrix.botToken`	`MATRIX_ACCESS_TOKEN`	通過 deep-channels 遷移
Mattermost	`channels.mattermost.botToken`	`MATTERMOST_BOT_TOKEN`	通過 deep-channels 遷移

其他配置

項目	OpenClaw 路徑	Hermes 路徑	說明
審批模式	`approvals.exec.mode`	`config.yaml` → `approvals.mode`	"auto"→"off", "always"→"manual", "smart"→"smart"
命令白名單	`exec-approvals.json`	`config.yaml` → `command_allowlist`	模式合併並去重
瀏覽器 CDP URL	`browser.cdpUrl`	`config.yaml` → `browser.cdp_url`
瀏覽器無頭模式	`browser.headless`	`config.yaml` → `browser.headless`
Brave 搜索密鑰	`tools.web.search.brave.apiKey`	`.env` → `BRAVE_API_KEY`	需啟用 `--migrate-secrets`
網關認證 token	`gateway.auth.token`	`.env` → `HERMES_GATEWAY_TOKEN`	需啟用 `--migrate-secrets`
工作目錄	`agents.defaults.workspace`	`.env` → `MESSAGING_CWD`

已歸檔（無直接 Hermes 對應項）

這些配置將保存至 ~/.hermes/migration/openclaw/<timestamp>/archive/ 以供手動審查：

項目	歸檔文件	如何在 Hermes 中重建
`IDENTITY.md`	`archive/workspace/IDENTITY.md`	合併至 `SOUL.md`
`TOOLS.md`	`archive/workspace/TOOLS.md`	Hermes 內置工具說明
`HEARTBEAT.md`	`archive/workspace/HEARTBEAT.md`	使用 cron 任務實現週期性任務
`BOOTSTRAP.md`	`archive/workspace/BOOTSTRAP.md`	使用上下文文件或技能
Cron 任務	`archive/cron-config.json`	使用 `hermes cron create` 重建
插件	`archive/plugins-config.json`	參見插件指南
鉤子/Webhook	`archive/hooks-config.json`	使用 `hermes webhook` 或網關鉤子
記憶後端	`archive/memory-backend-config.json`	通過 `hermes honcho` 配置
技能註冊表	`archive/skills-registry-config.json`	使用 `hermes skills config`
UI/身份	`archive/ui-identity-config.json`	使用 `/skin` 命令
日誌	`archive/logging-diagnostics-config.json`	在 `config.yaml` 的 logging 部分設置
多 Agent 列表	`archive/agents-list.json`	使用 Hermes 配置文件
通道綁定	`archive/bindings.json`	按平臺手動設置
複雜通道	`archive/channels-deep-config.json`	手動平臺配置

API 密鑰解析

當啟用 --migrate-secrets 時，API 密鑰將按優先級從 三個來源 收集：

配置值 — models.providers.*.apiKey 和 openclaw.json 中 TTS 提供商密鑰
環境文件 — ~/.openclaw/.env（如 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等）
認證配置文件 — ~/.openclaw/agents/main/agent/auth-profiles.json（按 Agent 的憑據）

配置值具有最高優先級。.env 文件用於填充缺失的值。認證配置文件則用於填充剩餘的空白。

支持的鍵目標

OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZAI_API_KEY, MINIMAX_API_KEY, ELEVENLABS_API_KEY, TELEGRAM_BOT_TOKEN, VOICE_TOOLS_OPENAI_KEY

不在上述允許列表中的鍵將永遠不會被複制。

SecretRef 處理

OpenClaw 配置中用於令牌和 API 密鑰的值可以採用三種格式：

// 純字符串
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// 環境模板
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// SecretRef 對象
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }

遷移過程會解析這三種格式。對於環境模板和 source: "env" 的 SecretRef 對象，它會從 ~/.openclaw/.env 中查找對應值。而 source: "file" 或 source: "exec" 的 SecretRef 對象無法自動解析——這些值必須在遷移後手動添加到 Hermes 中。

遷移後操作

檢查遷移報告 —— 遷移完成後會打印報告，包含已遷移、跳過和衝突項的數量。
審查歸檔文件 —— ~/.hermes/migration/openclaw/<timestamp>/archive/ 中的任何內容都需要手動處理。
驗證 API 密鑰 —— 運行 hermes status 以檢查各服務商的認證狀態。
測試消息功能 —— 如果你遷移了平臺令牌，請重啟網關：systemctl --user restart hermes-gateway
檢查會話策略 —— 確認 hermes config get session_reset 的值符合你的預期。
重新配對 WhatsApp —— WhatsApp 使用二維碼配對（Baileys），不支持令牌遷移。請運行 hermes whatsapp 來完成配對。

故障排除

“未找到 OpenClaw 目錄”

遷移過程會依次檢查 ~/.openclaw/、~/.clawdbot/、~/.moldbot/。如果你的安裝路徑不同，請使用 --source /path/to/your/openclaw 指定路徑。

“未找到任何服務商 API 密鑰”

密鑰可能位於你的 .env 文件中，而非 openclaw.json。遷移過程會同時檢查兩者——請確保 ~/.openclaw/.env 存在且包含所需密鑰。如果密鑰使用了 source: "file" 或 source: "exec" 的 SecretRef，則無法自動解析。

遷移後技能未出現

導入的技能會存放在 ~/.hermes/skills/openclaw-imports/。要使這些技能生效，請啟動一個新的會話，或運行 /skills 命令以確認它們已加載。

TTS 語音未被遷移

OpenClaw 將 TTS 設置存儲在兩個位置：messages.tts.providers.* 和頂層的 talk 配置。遷移過程會檢查這兩個位置。如果你的語音 ID 是通過 OpenClaw UI 設置的（存儲在其他路徑），可能需要手動設置：hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID。

快速開始​

選項​

遷移內容​

人格、記憶與指令​

技能（4 個來源）​

模型與提供方配置​

Agent 行為​

會話重置策略​

MCP 服務器​

TTS（文本轉語音）​

消息平臺​

其他配置​

已歸檔（無直接 Hermes 對應項）​

API 密鑰解析​

支持的鍵目標​

SecretRef 處理​

遷移後操作​

故障排除​

“未找到 OpenClaw 目錄”​

“未找到任何服務商 API 密鑰”​

遷移後技能未出現​

TTS 語音未被遷移​