OpenClaw 环境完整迁移实操步骤

OpenClaw 环境完整迁移实操步骤并不只看表面做法，关键还要理解相关条件、限制和后续影响。

一、迁移概述

OpenClaw 的运行环境由全局核心配置、模型定义、插件/技能生态、用户工作空间和环境变量认证五部分组成。迁移的本质是将这五部分核心文件完整复制到目标环境，确保配置、功能和数据完全一致。

二、关键文件/目录详解（先搞懂“为什么要拷”）

在开始操作前，需先确认源环境的实际路径（npm 全局安装路径因人而异，见下文“路径查找方法”）。

? 路径查找方法（避免拷贝错误！）

在源环境执行以下命令，获取真实路径：

# 1. 查找 OpenClaw 全局安装目录（核心！）OPENCLAW_GLOBAL="$(npm root -g)/openclaw"echo "OpenClaw 全局目录: $OPENCLAW_GLOBAL"# 2. 查找用户工作空间目录OPENCLAW_WORKSPACE="$(openclaw config get workspace 2>/dev/null || echo "$HOME/.openclaw/workspace")"echo "OpenClaw 工作空间: $OPENCLAW_WORKSPACE"# 3. 确认当前使用的 Shellecho "当前 Shell: $SHELL"

如下图所示

三、实操步骤（分“备份源环境”和“恢复目标环境”）

? 第一阶段：源环境备份（按顺序执行）

1. 备份前准备

确保 OpenClaw 未运行（避免文件被占用）：

# 谨慎执行！强制结束 OpenClaw 进程（若有）pkill -f openclaw || echo "无 OpenClaw 进程运行"

或者使用以下命令查看进程：

ps -ef | grep openclaw

红框中为openclaw进程，如下图所示：

定义备份路径（建议带日期，方便管理）：

# 自定义备份目录（可修改为你想存放的位置）BACKUP_DIR="$HOME/openclaw_backup_$(date +%Y%m%d)"mkdir -p "$BACKUP_DIR"echo "备份目录: $BACKUP_DIR"

2. 执行备份（复制所有核心文件）

# --- 1. 备份全局配置、模型、插件、技能 ---if [ -d "$OPENCLAW_GLOBAL" ]; then  cp -a "$OPENCLAW_GLOBAL/config.json" "$BACKUP_DIR/" 2>/dev/null || echo "config.json 不存在，跳过"  cp -a "$OPENCLAW_GLOBAL/models.json" "$BACKUP_DIR/" 2>/dev/null || echo "models.json 不存在，跳过"  cp -a "$OPENCLAW_GLOBAL/plugins/" "$BACKUP_DIR/" 2>/dev/null || echo "plugins 目录不存在，跳过"  cp -a "$OPENCLAW_GLOBAL/skills/" "$BACKUP_DIR/" 2>/dev/null || echo "skills 目录不存在，跳过"else  echo "错误: 未找到 OpenClaw 全局目录 $OPENCLAW_GLOBAL"  exit 1fi# --- 2. 备份用户工作空间 ---if [ -d "$OPENCLAW_WORKSPACE" ]; then  cp -a "$OPENCLAW_WORKSPACE" "$BACKUP_DIR/workspace"else  echo "警告: 未找到工作空间 $OPENCLAW_WORKSPACE，跳过"fi# --- 3. 备份 Shell 配置文件（环境变量） ---# 根据上面查到的 Shell 选择对应文件（以下以 bash 为例，zsh 请改为 ~/.zshrc）SHELL_CONFIG="$HOME/.bashrc"cp -a "$SHELL_CONFIG" "$BACKUP_DIR/$(basename $SHELL_CONFIG)"echo "✅ 备份完成！请检查 $BACKUP_DIR 内容："ls -lah "$BACKUP_DIR"

? 第二阶段：目标环境恢复

1. 目标环境准备

1. 安装 Node.js & npm：确保版本与源环境一致（可通过 node -v 和 npm -v 查看源环境版本）。
2. 安装 OpenClaw：建议安装与源环境相同版本（避免配置不兼容）：

# 先查看源环境 OpenClaw 版本（在源环境执行）openclaw --version# 目标环境安装对应版本（假设源环境是3.2）npm install -g [email protected]

如果能确认都是最新版本，或者源环境是最新版本，则直接执行如下命令安装：

curl -fsSL https://openclaw.ai/install.sh | bash

1. 确认目标环境路径（和源环境一样，先执行“路径查找方法”获取 OPENCLAW_GLOBAL 和 OPENCLAW_WORKSPACE）。

2. 上传备份文件到目标环境

将源环境的 $BACKUP_DIR 文件夹（如 openclaw_backup_20260305）上传到目标环境的任意位置（如 ~/openclaw_backup_20260305）。

3. 执行恢复（按顺序！）

# --- 0. 定义变量（请根据实际情况修改！） ---# 目标环境的 OpenClaw 全局目录（通过 npm root -g 获取）OPENCLAW_GLOBAL="$HOME/.npm-global/lib/node_modules/openclaw"# 目标环境的工作空间目录（通过 openclaw config get workspace 获取）OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"# 上传后的备份目录路径BACKUP_DIR="$HOME/openclaw_backup_20260305"# 目标环境的 Shell 配置文件SHELL_CONFIG="$HOME/.bashrc"# --- 1. 停止 OpenClaw 进程 ---pkill -f openclaw || echo "无 OpenClaw 进程运行"# --- 2. 恢复全局配置、模型、插件、技能 ---if [ -d "$BACKUP_DIR" ]; then  # 恢复 config.json  [ -f "$BACKUP_DIR/config.json" ] && cp -a "$BACKUP_DIR/config.json" "$OPENCLAW_GLOBAL/"  # 恢复 models.json  [ -f "$BACKUP_DIR/models.json" ] && cp -a "$BACKUP_DIR/models.json" "$OPENCLAW_GLOBAL/"  # 恢复 plugins 目录  [ -d "$BACKUP_DIR/plugins" ] && cp -a "$BACKUP_DIR/plugins/" "$OPENCLAW_GLOBAL/"  # 恢复 skills 目录  [ -d "$BACKUP_DIR/skills" ] && cp -a "$BACKUP_DIR/skills/" "$OPENCLAW_GLOBAL/"else  echo "错误: 未找到备份目录 $BACKUP_DIR"  exit 1fi# --- 3. 恢复工作空间 ---if [ -d "$BACKUP_DIR/workspace" ]; then  mkdir -p "$(dirname $OPENCLAW_WORKSPACE)"  # 确保父目录存在  cp -a "$BACKUP_DIR/workspace" "$OPENCLAW_WORKSPACE"fi# --- 4. 恢复环境变量（谨慎！建议先备份目标环境原配置） ---# 先备份目标环境当前的 Shell 配置cp -a "$SHELL_CONFIG" "$SHELL_CONFIG.bak.$(date +%Y%m%d)"# 方法 A：直接覆盖（仅当目标环境是全新环境时推荐）# cp -a "$BACKUP_DIR/$(basename $SHELL_CONFIG)" "$SHELL_CONFIG"# 方法 B：手动合并（推荐！）# 打开备份的 Shell 配置文件，将其中 OPENCLAW_* 开头的行复制到目标环境的 $SHELL_CONFIG 末尾echo "⚠️  请手动合并环境变量："echo "   1. 打开备份文件: cat $BACKUP_DIR/$(basename $SHELL_CONFIG)"echo "   2. 将其中 OPENCLAW_* 开头的行复制到 $SHELL_CONFIG 末尾"echo "   3. 执行: source $SHELL_CONFIG"# --- 5. 修复权限（如果全局目录需要 sudo） ---# 若 OpenClaw 安装在系统目录（如 /usr/local/lib/node_modules），需加 sudo 执行上述 cp 命令# 例如: sudo cp -a "$BACKUP_DIR/config.json" "$OPENCLAW_GLOBAL/"echo "✅ 恢复操作完成！请继续执行“验证步骤”。"

四、验证迁移是否成功（必须做！）

在目标环境依次执行以下命令，确认所有组件正常：

# 1. 检查 OpenClaw 版本openclaw --version# 2. 检查全局配置openclaw config list# 3. 检查模型列表openclaw models list# 4. 检查插件列表openclaw plugins list# 5. 检查技能列表openclaw skills list# 6. 检查工作空间文件ls -lah "$(openclaw config get workspace)"# 7. 运行简单测试（替换为你常用的命令）openclaw run "测试迁移是否成功"

五、常见问题与注意事项

1. 版本兼容性

1. 源环境和目标环境的 OpenClaw 大版本必须一致（如 3.x → 3.x，不要跨 2.x 大版本直接迁移），否则可能出现配置解析错误。
2. 若必须跨版本，建议先在目标环境安装新版本，再手动迁移 config.json 和工作空间，插件重新安装。

2. 插件依赖缺失

部分插件可能依赖系统库或第三方工具（如 ffmpeg、python3、tensorflow 等）。迁移后若插件报错，需在目标环境手动安装依赖：

# 以 Ubuntu 为例，安装常见依赖sudo apt update && sudo apt install -y ffmpeg python3 python3-pip# 若插件要求特定 Python 包pip3 install xxx

3. 权限问题

若 OpenClaw 是通过 sudo npm install -g 安装的，全局目录可能在 /usr/local/lib/node_modules/openclaw，此时备份和恢复需要加 sudo，且要注意文件所有者：

# 恢复后修复所有者（假设你的用户名是 user）sudo chown -R user:user "$OPENCLAW_GLOBAL"sudo chown -R user:user "$OPENCLAW_WORKSPACE"

4. 环境变量冲突

1. 若目标环境已有 OPENCLAW_API_KEY 等变量，手动合并 Shell 配置时需注意覆盖顺序（后写的生效）。
2. 建议使用 openclaw config set 命令重新设置敏感信息，替代直接复制环境变量。

5. 工作空间软链接

1. 若工作空间中包含软链接（ln -s 创建的文件），cp -a 会保留软链接。若软链接指向的文件不在工作空间内，需单独迁移这些文件，或修改软链接为相对路径。

六、快速参考（核心命令速查）

七、一键打包脚本

1、用户目录替换成自己的。

#!/bin/bash# OpenClaw 环境备份打包脚本# 功能：将当前 OpenClaw 配置、模型、插件、技能和工作空间打包成一个 tarballset -e# 定义变量USER_HOME="/home/tht"OPENCLAW_NPM="$USER_HOME/.npm-global/lib/node_modules/openclaw"WORKSPACE="$USER_HOME/.openclaw/workspace"BACKUP_DIR="$WORKSPACE/backup_staging"TIMESTAMP=$(date +%Y%m%d_%H%M%S)ARCHIVE_NAME="openclaw_backup_$TIMESTAMP.tar.gz"# 创建备份目录echo "正在创建备份目录..."rm -rf "$BACKUP_DIR"mkdir -p "$BACKUP_DIR"# 定义要备份的文件和目录echo "正在检查并复制文件..."# 配置文件if [ -f "$OPENCLAW_NPM/config.json" ]; then    cp "$OPENCLAW_NPM/config.json" "$BACKUP_DIR/"    echo "✓ 已复制：config.json"else    echo "⚠ config.json 不存在 (跳过)"fiif [ -f "$OPENCLAW_NPM/models.json" ]; then    cp "$OPENCLAW_NPM/models.json" "$BACKUP_DIR/"    echo "✓ 已复制：models.json"else    echo "⚠ models.json 不存在 (跳过)"fi# 插件目录if [ -d "$OPENCLAW_NPM/plugins" ]; then    cp -r "$OPENCLAW_NPM/plugins" "$BACKUP_DIR/"    echo "✓ 已复制：plugins"else    echo "⚠ plugins 目录不存在 (跳过)"fi# 技能目录if [ -d "$OPENCLAW_NPM/skills" ]; then    cp -r "$OPENCLAW_NPM/skills" "$BACKUP_DIR/"    echo "✓ 已复制：skills"else    echo "⚠ skills 目录不存在 (跳过)"fi# 工作空间 (排除 backup_staging 目录本身)echo "正在处理工作空间..."WORKSPACE_BACKUP_DIR="$BACKUP_DIR/workspace_content"mkdir -p "$WORKSPACE_BACKUP_DIR"# 复制工作空间中除备份目录外的所有内容for item in "$WORKSPACE"/*; do    if [ -e "$item" ] && [ "$(basename "$item")" != "backup_staging" ] && [ "$(basename "$item")" != "archives" ]; then        cp -r "$item" "$WORKSPACE_BACKUP_DIR/"        echo "✓ 已复制工作空间项：$(basename "$item")"    fidone# 创建工作空间中的归档目录echo ""echo "正在创建压缩包..."ARCHIVE_WORKSPACE_DIR="$WORKSPACE/archives"mkdir -p "$ARCHIVE_WORKSPACE_DIR"# 创建压缩包cd "$BACKUP_DIR"tar -czf "$ARCHIVE_WORKSPACE_DIR/$ARCHIVE_NAME" ./*echo "✓ 压缩包已创建：$ARCHIVE_WORKSPACE_DIR/$ARCHIVE_NAME"# 显示文件信息echo ""echo "=========================================="echo "备份完成！"echo "=========================================="echo "压缩包位置：$ARCHIVE_WORKSPACE_DIR/$ARCHIVE_NAME"echo "文件大小：$(du -h "$ARCHIVE_WORKSPACE_DIR/$ARCHIVE_NAME" | cut -f1)"echo ""echo "解压命令:"echo "  tar -xzf $ARCHIVE_WORKSPACE_DIR/$ARCHIVE_NAME -C /path/to/target"echo ""echo "=========================================="

2. 给脚本添加执行权限

chmod +x /home/tht/.openclaw/workspace/backup_openclaw.sh

3. 执行备份脚本

sh /home/tht/.openclaw/workspace/backup_openclaw.sh

4. （可选）清理临时目录

rm -rf /home/tht/.openclaw/workspace/backup_staging

生成的压缩包位置，比如今天这个包：

路径: /home/tht/.openclaw/workspace/archives/openclaw_backup_20260305_160638.tar.gz

如下图所示：

5.在目标环境解压命令

tar -xzf /path/to/openclaw_backup_xxxx.tar.gz -C /path/to/target

如果您想要手动直接打包而不使用脚本，可以使用以下命令（记得换成你自己的目录）：

# 直接打包到工作空间tar -czf /home/tht/.openclaw/workspace/archives/openclaw_manual_backup.tar.gz   ~/.npm-global/lib/node_modules/openclaw/config.json   ~/.npm-global/lib/node_modules/openclaw/skills   /home/tht/.openclaw/workspace/AGENTS.md   /home/tht/.openclaw/workspace/SOUL.md   /home/tht/.openclaw/workspace/USER.md   /home/tht/.openclaw/workspace/MEMORY.md   /home/tht/.openclaw/workspace/memory/