先说为什么

用 OpenClaw 一段时间之后，AI 已经记住了你的工作习惯、项目背景、各种工具的配置方式。这时候系统提示有新版本可以更新，你顺手跑了 npm install -g openclaw@latest。

更新完，重启 Gateway，打开对话，发现 AI 不认识你了——所有的对话历史消失，配置回到出厂状态，之前花时间调好的模型渠道、Custom Instructions、记忆文件全没了。

这种情况不常见，但一旦遇到就很烦人。根本原因通常是更新过程中配置文件被覆盖，或者新版和旧版某些配置写法不兼容，而不是更新本身有什么 bug。

核心原则只有一条：更新之前先备份。本文把整个升级流程过一遍，包括怎么检查破坏性变更、更新后怎么验证、以及出问题怎么回滚。顺带介绍怎么配置自动备份，彻底告别手动操作的烦恼。

一、先知道数据存在哪

动手之前搞清楚要保护什么，这是基本意识：

~/.openclaw/
├── openclaw.json              # 核心配置，模型、渠道、权限全在这
├── credentials/              # API Key、OAuth Token 等认证信息
├── agents/
│   └── main/
│       ├── sessions/          # 对话历史，JSONL 格式
│       └── workspace/         # 智能体工作区文件
├── skills/                   # 自定义安装的技能
└── logs/                    # 运行日志，可不备份

三样东西最重要：

openclaw.json — 你花时间配置的模型选择、渠道设置、权限规则、Custom Instructions，全在这个文件里。更新后如果这个文件被覆盖或重置，你需要从头把整套配置重新配一遍。重新配不复杂，但费时间。

credentials/ — 目录下存放的是各个模型的 API Key、OAuth Token 等认证信息。这些信息理论上可以从对应平台重新获取，但流程麻烦，特别是如果你的模型供应商后台有什么特殊审批流程的话，重新申请可能要等好几天。

agents/main/sessions/ — 对话历史文件，更新本身一般不会主动删除它，但某些破坏性变更可能会导致会话格式不兼容。没有这份历史，AI 就不记得之前你们聊过什么、做过什么项目。

其他目录像 skills 和 logs，按需备份即可，不是必须的。

二、更新前：一条命令完成备份

备份不需要什么复杂工具，一条 cp 搞定，关键是养成习惯：

# 完整备份整个目录，用当天日期命名，方便后续辨认
cp -r ~/.openclaw ~/.openclaw_backup_$(date +%Y%m%d)

# 验证一下是否成功
ls ~/ | grep openclaw_backup
# 应该看到类似 openclaw_backup_20260525

整个操作不超过 10 秒。备份路径建议放在用户主目录下，不要放在 ~/.openclaw/ 以内，万一要恢复的时候覆盖了原目录就麻烦了。

如果 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)/

# 如果你用了自定义的 Custom Instructions 或记忆文件
cp ~/.openclaw/agents/main/workspace/*.md ~/openclaw_config_backup_$(date +%Y%m%d)/ 2>/dev/null

这样备份量小很多，但丢了对话历史。

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

OpenClaw 的更新有两类：普通迭代（只加新功能，不改旧行为，升级最平滑）和破坏性变更（某些旧配置写法在新版里会报错，导致 Gateway 无法启动）。

每次更新前花两分钟看一下 Release Notes 里有没有标注 "Breaking Change"，这是能真正帮你避坑的操作：

# 用浏览器打开 GitHub Release 页面
open https://github.com/openclaw/openclaw/releases

# 或者直接查看当前安装的版本
openclaw --version

举一个实际影响过的破坏性变更案例。v2026.3.7 升级时，如果你的配置文件里同时存在 gateway.auth.token 和 gateway.auth.password 两个字段，升级后 Gateway 会拒绝启动，日志里会报类似 "conflicting auth fields" 的错误。遇到这种情况，必须先手动指定认证模式：

# 先检查当前认证配置是什么
openclaw config get gateway.auth

# 如果输出里同时有 token 和 password 两个字段
# 手动指定认证方式二选一
openclaw config set gateway.auth.mode token
# 或
openclaw config set gateway.auth.mode password

# 设置完之后再执行更新
npm install -g openclaw@latest

不同版本可能有不同的破坏性变更，养成查 Release Notes 的习惯，能省去很多麻烦。实在懒得每次都打开网页查，至少在遇到更新后 Gateway 起不来的时候，第一时间去 Release Notes 搜 "Breaking Change"。

四、执行更新

备份做完、破坏性变更检查完，才是真正执行更新的时候。不要跳过前两步直接跑更新命令，虽然大概率不会出问题，但一旦出问题没有备份就麻烦。

更新方式取决于你当初怎么装的：

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

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

# Docker 方式（用 docker compose 管理的情况下）
docker compose pull
docker compose up -d

如果用的是 Docker 方式，pull 完之后会自动用新镜像重建容器，只要你的数据目录做了持久化映射（也就是 docker-compose.yml 里 volumes 指向了宿主机目录），配置不会丢。如果忘了做持久化，那这次更新大概率会丢数据。

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

跑完更新命令不是结束，系统正常跑起来才是。马上做这三件事：

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

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

# 确认 Gateway 正常运行
openclaw gateway status

期望看到 Runtime: running 和 RPC probe: ok。如果 Gateway 没在跑，用 openclaw gateway start 手动启动。

第二件：运行 doctor 扫描配置

openclaw doctor

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

新版引入的配置迁移问题，doctor --fix 大多数时候能自动处理，不需要你手动改 openclaw.json。如果 doctor 报的是某个具体 skill 或渠道配置的警告，根据提示操作就行。

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

在聊天里发：

/status

如果返回了正确的模型名称和会话信息，说明一切正常，更新成功，配置也完整保留了。如果返回空或者报错了，就说明有问题，先检查一下 doctor 的输出。

六、出问题了怎么回滚

分两种情况处理，判断标准是：Gateway 能起来但配置乱了，还是新版本身就跑不起来。

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

有时候问题出在配置文件被部分覆盖，而不是新版本本身有什么问题。这种情况最常见，之前有用户反馈更新完 AI 记不住他了，但 Gateway 正常运行，多半就是这个原因。

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

# 重启 Gateway 让配置生效
openclaw daemon restart

# 再次验证
openclaw doctor

这样不需要降级版本，只把配置拿回来，新版本继续用。

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

如果确认是新版本本身有问题，比如新版有 bug 或者 Gateway 始终跑不起来：

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

# 找到上一个稳定版本号，比如 2026.3.23
npm install -g openclaw@2026.3.23

# 恢复备份的整个数据目录
cp -r ~/openclaw_backup_20260525/ ~/.openclaw/

# 重新安装并启动 Gateway
openclaw gateway install
openclaw daemon restart

# 验证
openclaw doctor
openclaw gateway status

完整回滚的时候注意，先恢复数据、再重启 Gateway，不要反过来操作，否则可能触发新版的配置校验逻辑再次覆盖现有文件。

七、配置自动备份，彻底省心

每次更新前手动备份听起来简单，但人总会忘。更好的办法是用 OpenClaw 自带的 Cron 机制设一个定时自动备份，一劳永逸。

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

解释一下每个参数的意思：

• --name 给这个定时任务起个名字
• --cron "0 3 * * 0" 是标准的 cron 表达式，代表每周日凌晨 3 点执行
• --tz "Asia/Shanghai" 指定时区，不用这个参数默认用 UTC
• --session "isolated" 在独立会话里执行，不占用主对话
• --message 里写你想让它做什么，这里让它执行备份命令然后回报结果
• --announce 让它把执行结果发到聊天里通知你

配置完之后每周自动跑一次，完成后直接发消息告诉你备份路径。你不需要记着这件事，也不需要手动操作。

如果更喜欢用系统原生的 crontab，也可以在系统层面配置：

crontab -e

添加这一行：

# 每周日 3 点执行备份，错误输出丢到 /dev/null 避免收到邮件通知
0 3 * * 0 cp -r ~/.openclaw ~/.openclaw_backup_$(date +\%Y\%m\%d) 2>/dev/null

两种方式效果一样，选一个顺手的用就行。