OpenClaw配置备份指南：Qwen3-4B模型参数迁移方案

1. 为什么需要配置备份

上周我的主力开发机突然硬盘故障，导致辛苦配置了两个月的OpenClaw环境全部丢失。最痛苦的不是重装软件，而是那些精心调试的模型参数、飞书机器人凭证和自定义技能配置需要从头再来。这次教训让我意识到：OpenClaw的配置备份应该成为每个用户的必修课。

与普通软件不同，OpenClaw的配置分散在多个位置：

• 核心配置文件（openclaw.json）
• 环境变量（如飞书/钉钉的App Secret）
• 技能模块的本地缓存
• 模型连接参数（特别是自建Qwen3-4B这类本地模型）

本文将分享我通过血泪教训总结出的全量备份方案，重点解决三个实际问题：

1. 如何完整打包关键配置不遗漏
2. 跨设备迁移时的版本兼容性处理
3. 环境变量丢失后的快速恢复技巧

2. 核心配置文件备份

2.1 定位关键文件

OpenClaw的核心配置存储在用户目录下的隐藏文件夹中（以macOS为例）：

# 配置文件主目录
~/.openclaw/
├── openclaw.json       # 主配置文件（含模型、渠道参数）
├── workspace/          # 工作区（含环境变量）
├── plugins/            # 已安装插件
└── skills/             # 技能模块配置

必须备份的四个核心文件：

1. openclaw.json - 包含模型连接参数、渠道配置
2. workspace/TOOLS.md - 存储敏感凭证的环境变量
3. skills/目录下的manifest.yaml - 记录技能自定义参数
4. plugins/feishu/config.json - 飞书插件专用配置（如存在）

2.2 创建备份包

建议使用tar命令打包，保留文件权限和目录结构：

cd ~
tar -czvf openclaw_backup_$(date +%Y%m%d).tar.gz \
    .openclaw/openclaw.json \
    .openclaw/workspace/TOOLS.md \
    .openclaw/skills/*/manifest.yaml \
    .openclaw/plugins/*/config.json

关键技巧：

• 给备份包加上日期标签（如20240520）
• 排除node_modules等无关目录减少体积
• 敏感文件建议加密存储（如用gpg加密）

3. Qwen3-4B模型参数迁移

3.1 模型连接配置解析

当使用本地部署的Qwen3-4B模型时，openclaw.json中会有如下关键字段：

{
  "models": {
    "providers": {
      "my-qwen": {
        "baseUrl": "http://localhost:8000/v1",
        "apiKey": "sk-no-key-required",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-4b",
            "name": "Local Qwen3-4B",
            "contextWindow": 32768,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

迁移注意事项：

1. 如果新设备的模型服务地址变化（如从localhost改为IP），需同步修改baseUrl
2. apiKey字段对于本地模型通常可忽略，但某些封装服务可能要求虚拟key
3. 模型规格参数（如contextWindow）需与实际情况一致

3.2 版本兼容性处理

遇到过OpenClaw版本升级导致配置不兼容的情况，我的解决方案是：

1. 备份时记录软件版本：

   openclaw --version > version.txt
   

2. 在新环境优先安装相同版本：

   npm install -g openclaw@1.2.3
   

3. 如果必须升级，先用openclaw doctor检查配置有效性

典型版本冲突案例：

• v1.3.0开始要求models.providers必须包含api字段
• v1.5.0废弃了旧的channel拼写，改为channels

4. 飞书凭证与环境变量恢复

4.1 凭证备份要点

飞书机器人的配置涉及两类敏感信息：

1. 开放平台凭证：App ID和App Secret
2. 环境变量：通常存储在TOOLS.md中

建议采用分层次备份策略：

• 将App ID这类低频变更信息记录在密码管理器
• 环境变量等高频变更内容通过文件备份

4.2 环境变量丢失处理

当发现飞书机器人无法连接时，按以下步骤排查：

1. 检查环境变量是否加载：

   grep WECHAT_APP_ID ~/.openclaw/workspace/TOOLS.md
   

2. 如果文件存在但未生效，尝试：

   source ~/.openclaw/workspace/TOOLS.md
   openclaw gateway restart
   

3. 完全丢失时，从备份恢复并重新授权IP白名单

血泪教训：曾因忘记更新IP白名单，导致迁移后机器人持续报错401。现在我的检查清单一定会包含这步：

# 获取当前公网IP并更新白名单
curl ifconfig.me | tee current_ip.txt

5. 跨设备迁移实战演示

以下是我最近一次从MacBook迁移到Linux主机的完整流程：

5.1 准备工作

1. 在旧设备执行备份命令（见第2章）
2. 将备份包和版本信息拷贝到新设备
3. 新设备安装相同版本的OpenClaw

5.2 恢复配置

# 解压备份包到临时目录
tar -xzvf openclaw_backup_20240520.tar.gz -C /tmp

# 恢复核心配置
cp /tmp/.openclaw/openclaw.json ~/.openclaw/

# 恢复环境变量（注意权限）
chmod 600 /tmp/.openclaw/workspace/TOOLS.md
cp /tmp/.openclaw/workspace/TOOLS.md ~/.openclaw/workspace/

# 按需恢复技能配置
rsync -av /tmp/.openclaw/skills/ ~/.openclaw/skills/

5.3 模型重定向

由于新设备的Qwen3-4B部署在192.168.1.100，需要修改配置：

sed -i 's/localhost:8000/192.168.1.100:8000/g' ~/.openclaw/openclaw.json

5.4 最终验证

openclaw gateway restart
openclaw models list  # 应显示迁移后的模型

6. 我的自动化备份方案

为了避免再次遭遇数据丢失，我实现了一个简单的自动化备份方案：

1. 创建备份脚本~/.openclaw/scripts/backup.sh：

   #!/bin/bash
   BACKUP_DIR="$HOME/openclaw_backups"
   mkdir -p "$BACKUP_DIR"
   tar -czvf "$BACKUP_DIR/openclaw_$(date +%Y%m%d).tar.gz" \
       ~/.openclaw/openclaw.json \
       ~/.openclaw/workspace/TOOLS.md \
       ~/.openclaw/skills/*/manifest.yaml
   find "$BACKUP_DIR" -type f -mtime +30 -delete  # 保留30天
   

2. 添加cron任务每周自动运行：

   (crontab -l ; echo "0 3 * * 0 $HOME/.openclaw/scripts/backup.sh") | crontab -
   

3. 重要备份同步到加密云存储

现在，每次重大配置变更后，我都会手动执行一次备份脚本。这个习惯已经帮我避免了至少三次潜在的配置灾难。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。