你正在用 OpenClaw，用得挺顺，AI 也记住了很多你的习惯和项目背景。这时候终端提示有新版本可以更新——你直接跑了 npm install -g openclaw@latest。

更新完，重启 Gateway，发现 AI 不记得你了，配置回到了出厂状态，所有的对话历史和自定义设置都消失了。

这种情况并不常见，但它会发生。原因通常不是更新本身有 bug，而是更新过程中遇到了破坏性变更，或者更新命令附带了某些会重写配置的参数。

预防它的方法很简单，就一步——更新之前先备份。更多资源请访问 OpenClaw 中文版官网。

一、先搞清楚 OpenClaw 的数据存在哪

知道数据在哪，才知道要保护什么：

~/.openclaw/
├── openclaw.json          # ← 核心！你所有的配置都在这里
├── credentials/           # ← API Key、OAuth Token 等认证信息
├── agents/
│   ├── main/
│   │   ├── sessions/      # ← 对话历史（JSONL 格式）
│   │   ├── agent/
│   │   │   ├── auth-profiles.json  # ← 模型认证信息
│   │   │   └── models.json         # ← 模型缓存
│   │   └── workspace/     # ← 智能体工作区文件
│   └── soul.md            # ← AI 的"记忆"文件（如果有配置）
├── skills/                # ← 自定义安装的技能
└── logs/                  # ← 运行日志（可以不备份）

其中最重要的三样：

  1. openclaw.json：你花时间配置的模型、渠道、权限设置，全在这里。更新后如果这个文件被覆盖，需要从头重配
  2. credentials/：所有的 API Key 和 Token 认证信息。这些信息可以重新获取，但要花时间
  3. agents/main/sessions/：对话历史。一般更新不会删这个，但出于谨慎还是一起备

二、更新前：一条命令备份所有数据

这是你在更新之前需要做的唯一一件事：

# 把整个 .openclaw 目录备份到带日期的文件夹
cp -r ~/.openclaw ~/.openclaw_backup_$(date +%Y%m%d)

# 验证备份成功
ls ~/ | grep openclaw_backup
# 应看到类似：openclaw_backup_20260401

这条命令会把 ~/.openclaw 目录完整复制一份，以当天日期命名。整个操作不超过 10 秒。

如果你的 sessions/ 目录很大（对话历史很多），备份可能需要稍长一点。如果只想备份关键配置，不备份历史对话：

# 只备份配置文件和凭证
mkdir -p ~/openclaw_config_backup_$(date +%Y%m%d)
cp ~/.openclaw/openclaw.json ~/openclaw_config_backup_$(date +%Y%m%d)/
cp -r ~/.openclaw/credentials/ ~/openclaw_config_backup_$(date +%Y%m%d)/

三、更新前：检查有没有破坏性变更

OpenClaw 的更新有两类：普通迭代（只加新功能，不改旧行为）和破坏性变更（某些配置写法改了，旧版本的配置文件会导致新版本启动失败）。

每次更新前，花 2 分钟查看一下 Release Notes 里有没有标注 “Breaking Change”：

open https://github.com/openclaw/openclaw/releases
# 或者查看当前安装版本和目标版本之间的变更

历史上影响面最大的一次破坏性变更是 v2026.3.7：如果你的配置文件里同时有 gateway.auth.token 和 gateway.auth.password 两个字段，升级后 Gateway 会拒绝启动，必须先手动设置 gateway.auth.mode。

在升级到 v2026.3.7 之前，必须先检查：

openclaw config get gateway.auth

# 如果输出里同时有 token 和 password 两个字段：
openclaw config set gateway.auth.mode token
# 或
openclaw config set gateway.auth.mode password

# 然后再升级

不同版本可能有不同的破坏性变更，养成查 Release Notes 的习惯，能省去很多麻烦。

四、执行更新

备份做完、破坏性变更检查完，才是真正执行更新的时候：

# npm 安装方式
npm install -g openclaw@latest

# pnpm 安装方式
pnpm add -g openclaw@latest

# Docker 方式
docker compose pull
docker compose up -d

五、更新完：立刻做这三件事验证

更新完不是结束，马上验证一下系统是否正常：

第一件：确认版本和 Gateway 状态

# 确认已升级到新版本
openclaw --version

# 确认 Gateway 正常运行
openclaw gateway status
# 期望：Runtime: running / RPC probe: ok

第二件：运行 doctor 扫描配置

openclaw doctor

# 如果有 FAIL 或 WARN，加 --fix 尝试自动修复
openclaw doctor --fix

新版本引入的配置迁移通常 doctor --fix 会自动处理，不需要手动修改配置文件。

第三件：发一条消息确认 AI 正常响应

# 在聊天里发这条
/status

# 如果返回了正确的模型和会话信息，说明一切正常

如果 /status 有响应，你的 OpenClaw 更新成功，配置也完整保留了。

六、出了问题：如何回滚

如果更新后出了问题，你有两种回滚路径：

路径一：只恢复数据，保持新版本

有时候问题出在配置文件被部分覆盖，而不是新版本本身的问题。这时候只恢复配置即可：

# 用备份的配置覆盖当前配置
cp ~/openclaw_backup_20260401/openclaw.json ~/.openclaw/openclaw.json

# 重启 Gateway
openclaw daemon restart

# 再次验证
openclaw doctor

路径二：完整回滚，包括版本降级

如果新版本本身有问题，回到之前的版本：

# 查看 OpenClaw 的历史版本
npm view openclaw versions --json

# 安装指定版本（比如回到 2026.3.23）
npm install -g openclaw@2026.3.23

# 恢复备份的数据
cp -r ~/openclaw_backup_20260401/ ~/.openclaw/

# 重启
openclaw gateway install
openclaw daemon restart

七、配置一个自动备份（彻底省心）

如果不想每次更新前都手动备份，可以用 OpenClaw 自己的 Cron 机制设置自动每周备份：

openclaw cron add \
  --name "weekly-backup" \
  --cron "0 3 * * 0" \
  --tz "Asia/Shanghai" \
  --session "isolated" \
  --message "执行命令：cp -r ~/.openclaw ~/.openclaw_backup_\$(date +%Y%m%d)；然后告诉我备份已完成，备份路径是什么" \
  --announce

每周日凌晨 3 点自动备份一次，完成后发通知告诉你。不需要记着，也不需要手动执行。

如果更喜欢用原生命令，也可以在系统的 crontab 里加：

# 编辑系统 crontab
crontab -e

# 添加这一行（每周日 3 点自动备份）
0 3 * * 0 cp -r ~/.openclaw ~/.openclaw_backup_$(date +\%Y\%m\%d) 2>/dev/null

总结

更新 OpenClaw 之前只需要做一件事：

cp -r ~/.openclaw ~/.openclaw_backup_$(date +%Y%m%d)

这一条命令，10 秒钟，就是本文想说的全部核心。

顺带再做两件事更保险：查一下 Release Notes 里有没有破坏性变更（特别是大版本跨越），以及更新完立刻跑一次 openclaw doctor。

有了备份，即使更新出了任何问题，都能在 5 分钟内回到之前正常工作的状态。没有备份，出了问题就只能从头重配。

想了解更多 OpenClaw 使用技巧，欢迎访问 OpenClaw 中文版官网。