OpenClaw 环境完整迁移实操步骤

2026-03-07 15:21:43 海兰

一、迁移概述

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

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

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

组件类型	作用说明	默认/常见路径示例
全局配置文件	存储 OpenClaw 的核心设置（模型默认参数、认证方式、日志级别等）	`~/.npm-global/lib/node_modules/openclaw/config.json`
模型配置文件	自定义模型的定义（如模型名称、API 端点、参数映射等）	`~/.npm-global/lib/node_modules/openclaw/models.json`
插件目录	所有已安装插件的代码和配置（插件是 OpenClaw 功能扩展的核心）	`~/.npm-global/lib/node_modules/openclaw/plugins/`
技能目录	所有已安装技能的定义（技能是插件的上层封装，用于特定任务流）	`~/.npm-global/lib/node_modules/openclaw/skills/`
用户工作空间	存储项目文件、对话记忆（MEMORY.md）、用户偏好（USER.md）、会话历史等	`~/.openclaw/workspace/`（可通过配置修改）
环境变量配置	存储敏感信息（如 API 密钥）、自定义路径等（OpenClaw 会读取 `OPENCLAW_*` 开头的变量）	`~/.bashrc` / `~/.zshrc` / `~/.profile`

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

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

# 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. 确认当前使用的 Shell
echo "当前 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 1
fi
# --- 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. 目标环境准备

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

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

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

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

确认目标环境路径（和源环境一样，先执行“路径查找方法”获取 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 1
fi
# --- 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. 版本兼容性

源环境和目标环境的 OpenClaw 大版本必须一致（如 3.x → 3.x，不要跨 2.x 大版本直接迁移），否则可能出现配置解析错误。
若必须跨版本，建议先在目标环境安装新版本，再手动迁移 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. 环境变量冲突

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

5. 工作空间软链接

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

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

操作	命令示例
查找 npm 全局目录	`npm root -g`
查看 OpenClaw 版本	`openclaw --version`
查看 OpenClaw 配置	`openclaw config list`
停止 OpenClaw 进程	`pkill -f openclaw`
复制目录（保留权限/软链）	`cp -a 源目录目标目录`

七、一键打包脚本

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

#!/bin/bash
# OpenClaw 环境备份打包脚本
# 功能：将当前 OpenClaw 配置、模型、插件、技能和工作空间打包成一个 tarball
set -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 不存在 (跳过)"
fi
if [ -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")"
    fi
done
# 创建工作空间中的归档目录
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/

到此这篇关于OpenClaw 环境完整迁移实操步骤的文章就介绍到这了,更多相关OpenClaw 环境迁移内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！