openclaw 文档

简体中文

English

简体中文

English

Appearance

将 OpenClaw 迁移到新机器 ​

本指南用于把 OpenClaw Gateway 从一台机器迁移到另一台机器，无需重新做 onboarding。

概念上迁移很简单：

  • 复制 state 目录（$OPENCLAW_STATE_DIR，默认：~/.openclaw/）——其中包含 config、鉴权、sessions，以及 channel state。
  • 复制你的 workspace（默认：~/.openclaw/workspace/）——其中包含你的 agent 文件（memory、prompts 等）。

但实践中常见坑集中在 profiles、权限、以及只拷贝了一部分。

开始之前（你要迁移的是什么） ​

1）确认你的 state 目录 ​

大多数安装使用默认值：

  • State dir： ~/.openclaw/

但如果你使用了以下任一项，它可能不同：

  • --profile <name>（通常会变成 ~/.openclaw-<profile>/）
  • OPENCLAW_STATE_DIR=/some/path

如果你不确定，在旧机器上运行：

bash
openclaw status

在输出里查找 OPENCLAW_STATE_DIR / profile 的相关信息。如果你跑了多个 gateways，请对每个 profile 重复检查。

2）确认你的 workspace ​

常见默认值：

  • ~/.openclaw/workspace/（推荐 workspace）
  • 你自己创建的自定义目录

workspace 是 MEMORY.md、USER.md、memory/*.md 等文件所在位置。

3）理解你会保留哪些内容 ​

如果你同时复制 state dir + workspace，你会保留：

  • Gateway 配置（openclaw.json）
  • Auth profiles / API keys / OAuth tokens
  • Session 历史 + agent state
  • Channel state（例如 WhatsApp 的登录/会话）
  • Workspace 文件（memory、技能笔记等）

如果你只复制 workspace（例如通过 Git），你不会保留：

  • sessions
  • credentials
  • channel logins

这些都在 $OPENCLAW_STATE_DIR 下。

迁移步骤（推荐） ​

Step 0 — 先备份（旧机器） ​

在旧机器上，先停止 gateway，避免拷贝过程中有文件变化：

bash
openclaw gateway stop

（可选但推荐）把 state dir 和 workspace 打包归档：

bash
# 如果你使用 profile 或自定义路径，请调整下面的路径
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

如果你有多个 profiles/state dirs（例如 ~/.openclaw-main、~/.openclaw-work），请分别归档每个目录。

Step 1 — 在新机器上安装 OpenClaw ​

在新机器上安装 CLI（必要时也安装 Node）：

此时即使 onboarding 创建了一个新的 ~/.openclaw/ 也没关系——下一步你会覆盖它。

Step 2 — 把 state dir + workspace 复制到新机器 ​

需要同时复制两者：

  • $OPENCLAW_STATE_DIR（默认 ~/.openclaw/）
  • 你的 workspace（默认 ~/.openclaw/workspace/）

常见方式：

  • scp 传 tar 包并解压
  • 通过 SSH 用 rsync -a
  • 外接硬盘

复制完成后请确认：

  • 包含了隐藏目录（例如 .openclaw/）
  • 文件所有权属于运行 gateway 的那个用户

Step 3 — 运行 Doctor（迁移 + service 修复） ​

在新机器上运行：

bash
openclaw doctor

Doctor 是“安全但无聊”的命令：修复 services、应用 config migrations，并对不匹配给出警告。

然后：

bash
openclaw gateway restart
openclaw status

常见坑（以及如何避免） ​

坑：profile / state-dir 不匹配 ​

如果旧 gateway 使用了 profile（或 OPENCLAW_STATE_DIR），但新 gateway 使用了不同的 profile/state dir，你会看到类似症状：

  • config 改了不生效
  • channels 丢失/登出
  • session history 为空

修复：确保新机器上的 gateway/service 使用与你迁移过来的同一个 profile/state dir，然后再运行：

bash
openclaw doctor

坑：只复制 openclaw.json ​

openclaw.json 不够。很多 provider 的状态存放在：

  • $OPENCLAW_STATE_DIR/credentials/
  • $OPENCLAW_STATE_DIR/agents/<agentId>/...

务必迁移整个 $OPENCLAW_STATE_DIR 文件夹。

坑：权限 / 所有权 ​

如果你用 root 复制或更换了用户，gateway 可能无法读取 credentials/sessions。

修复：确保 state dir + workspace 的所有者是运行 gateway 的用户。

坑：在 remote/local 模式之间迁移 ​

  • 如果你的 UI（WebUI/TUI）指向一个远程 gateway，那么 session store + workspace 的“事实来源”在远程主机上。
  • 仅迁移你的笔记本并不会迁移远程 gateway 的 state。

如果你处于 remote mode，请迁移gateway host。

坑：备份中包含 secrets ​

$OPENCLAW_STATE_DIR 包含 secrets（API keys、OAuth tokens、WhatsApp creds）。请把备份当作生产级 secrets 来对待：

  • 加密存储
  • 避免通过不安全渠道分享
  • 如果你怀疑泄露，轮换 keys

验证清单 ​

在新机器上确认：

  • openclaw status 显示 gateway 正在运行
  • channels 仍保持连接（例如 WhatsApp 不需要重新配对）
  • dashboard 能打开并能看到既有 sessions
  • workspace 文件（memory、configs）存在

相关链接 ​