本指南将 OpenClaw Gateway 网关从一台机器迁移到另一台，无需重新进行新手引导<\/strong>。<\/p>\n 迁移在概念上很简单：<\/p>\n 但在配置文件<\/strong>、权限<\/strong>和部分复制<\/strong>方面有常见的陷阱。<\/p>\n 大多数安装使用默认值：<\/p>\n 但如果你使用以下方式，可能会不同：<\/p>\n 如果你不确定，在旧<\/strong>机器上运行：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} （可选但推荐）归档状态目录和工作区：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}<\/p>\n cd ~ tar -czf openclaw-workspace.tgz .openclaw\/workspace<\/p>\n Doctor 是”安全可靠”的命令。它修复服务、应用配置迁移，并警告不匹配问题。<\/p>\n 然后：<\/p>\n “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} 始终迁移整个 如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证\/会话。<\/p>\n 修复：请确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。<\/p>\n 如果你处于远程模式，请迁移 Gateway 网关主机<\/strong>。<\/p>\n 在新机器上，确认：<\/p>\n 迁移指南 将 OpenClaw $ […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-164","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/164","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=164"}],"version-history":[{"count":2,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/164\/revisions"}],"predecessor-version":[{"id":799,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/164\/revisions\/799"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=164"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=164"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=164"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\n
$OPENCLAW_STATE_DIR<\/code>，默认：~\/.openclaw\/<\/code>）— 这包括配置、认证、会话和渠道状态。<\/li>\n~\/.openclaw\/workspace\/<\/code>）— 这包括你的智能体文件（记忆、提示等）。<\/li>\n<\/ul>\n开始之前（你要迁移什么）<\/h2>\n
1）确定你的状态目录<\/h3>\n
\n
~\/.openclaw\/<\/code><\/li>\n<\/ul>\n\n
--profile <name><\/code>（通常变成 ~\/.openclaw-<profile>\/<\/code>）<\/li>\nOPENCLAW_STATE_DIR=\/some\/path<\/code><\/li>\n<\/ul>\n
\nopenclaw status<\/p>\n\n在输出中查找 `OPENCLAW_STATE_DIR` \/ profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。\n\n### 2）确定你的工作区\n\n常见默认值：\n\n* `~\/.openclaw\/workspace\/`（推荐的工作区）\n* 你创建的自定义文件夹\n\n你的工作区是 `MEMORY.md`、`USER.md` 和 `memory\/*.md` 等文件所在的位置。\n\n### 3）了解你将保留什么\n\n如果你复制**两者**——状态目录和工作区，你将保留：\n\n* Gateway 网关配置（`openclaw.json`）\n* 认证配置文件 \/ API 密钥 \/ OAuth 令牌\n* 会话历史 + 智能体状态\n* 渠道状态（例如 WhatsApp 登录\/会话）\n* 你的工作区文件（记忆、Skills 笔记等）\n\n如果你**只**复制工作区（例如通过 Git），你**不会**保留：\n\n* 会话\n* 凭证\n* 渠道登录\n\n这些存储在 `$OPENCLAW_STATE_DIR` 下。\n\n## 迁移步骤（推荐）\n\n### 步骤 0 — 备份（旧机器）\n\n在**旧**机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nopenclaw gateway stop\n<\/code><\/pre>\n如果你使用配置文件或自定义位置，请调整路径<\/h1>\n
\ntar -czf openclaw-state.tgz .openclaw<\/p>\n\n如果你有多个配置文件\/状态目录（例如 `~\/.openclaw-main`、`~\/.openclaw-work`），分别归档每个。\n\n### 步骤 1 — 在新机器上安装 OpenClaw\n\n在**新**机器上，安装 CLI（如果需要还有 Node）：\n\n* 参见：[安装](\/install)\n\n在这个阶段，如果新手引导创建了一个新的 `~\/.openclaw\/` 也没关系 — 你将在下一步覆盖它。\n\n### 步骤 2 — 将状态目录 + 工作区复制到新机器\n\n复制**两者**：\n\n* `$OPENCLAW_STATE_DIR`（默认 `~\/.openclaw\/`）\n* 你的工作区（默认 `~\/.openclaw\/workspace\/`）\n\n常见方法：\n\n* `scp` 压缩包并解压\n* 通过 SSH 使用 `rsync -a`\n* 外部驱动器\n\n复制后，确保：\n\n* 包含了隐藏目录（例如 `.openclaw\/`）\n* 文件所有权对于运行 Gateway 网关的用户是正确的\n\n### 步骤 3 — 运行 Doctor（迁移 + 服务修复）\n\n在**新**机器上：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nopenclaw doctor\n<\/code><\/pre>\n
\nopenclaw gateway restart
\nopenclaw status<\/p>\n\n## 常见陷阱（以及如何避免）\n\n### 陷阱：配置文件\/状态目录不匹配\n\n如果你在旧 Gateway 网关上使用了配置文件（或 `OPENCLAW_STATE_DIR`），而新 Gateway 网关使用了不同的配置，你会看到如下症状：\n\n* 配置更改不生效\n* 渠道丢失\/已登出\n* 会话历史为空\n\n修复：使用你迁移的**相同**配置文件\/状态目录运行 Gateway 网关\/服务，然后重新运行：\n\n```bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}\nopenclaw doctor\n<\/code><\/pre>\n陷阱：只复制
openclaw.json<\/code><\/h3>\nopenclaw.json<\/code> 是不够的。许多提供商在以下位置存储状态：<\/p>\n\n
$OPENCLAW_STATE_DIR\/credentials\/<\/code><\/li>\n$OPENCLAW_STATE_DIR\/agents\/<agentId>\/...<\/code><\/li>\n<\/ul>\n$OPENCLAW_STATE_DIR<\/code> 文件夹。<\/p>\n陷阱：权限\/所有权<\/h3>\n
陷阱：在远程\/本地模式之间迁移<\/h3>\n
\n
陷阱：备份中的密钥<\/h3>\n
$OPENCLAW_STATE_DIR<\/code> 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：<\/p>\n\n
验证检查清单<\/h2>\n
\n
openclaw status<\/code> 显示 Gateway 网关正在运行<\/li>\n相关内容<\/h2>\n
\n