前言
想象一下：你兴致勃勃敲了一行 npm install -g openclaw@latest，以为即将迎来人生巅峰，结果——Gateway 起不来了。
配置丢了，频道掉了，AI 不理你了。
你坐在屏幕前，开始怀疑人生。
别问我怎么知道的。
这就是为什么你需要在更新之前，先把该备份的东西备份好。而本文，就是来教你这个的。
---
零、如何确认当前安装方式
这是第一步，但上面漏掉了，补上。
你不知道自己装的啥？
openclaw --version
这会显示版本号，比如 OpenClaw 2026.4.23。
然后用这个命令看详细信息：
openclaw doctor
它会检测并告诉你当前是怎么安装的（npm / git / docker 等）。
还可以直接看文件：
# 如果这个路径存在，说明是 npm 全局安装 npm list -g openclaw # 看 Gateway 进程启动方式 ps aux | grep openclaw
另外，根据你当初用的命令也可以反推：
| 你当时敲的命令 | 安装方式 | |
|---|---|---|
| `curl -fsSL https://openclaw.ai/install.sh \ | bash` | 官方安装脚本 |
npm install -g openclaw@latest | npm 全局 | |
pnpm add -g openclaw@latest | pnpm | |
bun add -g openclaw@latest | bun | |
docker run ... | Docker | |
git clone ... 然后 pnpm link --global | 源码 |
搞不清楚的话，直接跑一遍 openclaw doctor，它会告诉你。
---
一、先搞清楚你用的是什么安装方式
更新这事儿，跟你当初怎么装的有很大关系。有人用 npm，有人用 Docker，有人用安装脚本，有人更硬核——直接从源码编译。
不同的安装方式，更新命令完全不一样。
你不知道自己装的啥？
openclaw --version
看看输出，然后对号入座：
| 安装方式 | 特征 | 如何更新 | |
|---|---|---|---|
| npm 全局安装 | npm i -g openclaw | npm i -g openclaw@latest | |
| 官方安装脚本 | `curl -fsSL https://openclaw.ai/install.sh \ | bash` | 再次跑一遍脚本 |
| Docker/容器 | 容器环境 | 重新 docker pull | |
| 源码编译 | 从 GitHub 拉代码 | git pull + 重新 build | |
| pnpm / bun | 用这些包管理器装的 | 对应命令 pnpm add -g openclaw@latest |
---
二、最推荐的更新方式：openclaw update
不管你用什么装的，有一个万能命令：
openclaw update
这玩意儿会自动检测你是什么安装方式，然后帮你搞定一切。检测、下载、重启服务，一条龙。
想预览一下但不真更新？
openclaw update --dry-run
想尝鲜 beta 版？
openclaw update --channel beta
简单粗暴，但管用。
---
三、不同安装方式，具体怎么操作
3.1 npm 安装（最常见）
# 更新到最新版 npm install -g openclaw@latest # 如果用 pnpm pnpm add -g openclaw@latest # 如果用 bun bun add -g openclaw@latest
装完之后运行一下：
openclaw doctor openclaw gateway restart
别跳过 doctor 这一步。 它会检查配置有没有问题、帮你迁移旧配置。很多更新后的奇怪 bug，其实一个 doctor 就能修。
---
3.2 安装脚本装的
curl -fsSL https://openclaw.ai/install.sh | bash
重新跑一遍脚本就好，它会自动处理 Node 和更新的事情。
如果不想重新走引导流程，加 --no-onboard：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
---
3.3 Docker / Podman
Docker 用户：
docker pull openclaw/openclaw:latest # 然后重启你的容器 docker compose down && docker compose up -d
Podman 用户同理，把 docker 换成 podman 就行。
注意： 如果你用的是宿主机挂载的配置文件（-v ~/.openclaw:/root/.openclaw 这种），容器更新不会影响你的配置。但如果你是把配置写死在镜像里的……你可能需要重新 onboard。
---
3.4 源码安装（硬核用户专用）
cd openclaw # 你克隆的目录 git pull origin main pnpm install && pnpm build && pnpm ui:build openclaw gateway restart
如果你想回滚到某个旧版本：
# 回到某个特定日期之前的最新 commit git fetch origin git checkout "$(git rev-list -n 1 --before="2026-01-01" origin/main)" pnpm install && pnpm build
---
四、为什么要备份？（血的教训警告）
更新本身不危险，危险的是你没备份。
OpenClaw 的状态目录 ~/.openclaw/ 里有什么？
- 配置文件 (
openclaw.json)——你所有的渠道配置、认证信息、Gateway 设置
- 认证文件 (
auth-profiles.json)——你的 API Key、OAuth 令牌
- 渠道状态——WhatsApp 登录态、Telegram 会话……这些丢了就得重新配对
- 会话历史——AI 记着你和它的所有对话
- 工作区文件——你的
MEMORY.md、USER.md、各种定制化的配置
想象一下：你更新完了，发现配置全空了，WhatsApp 要重新扫码，Telegram Bot 要重新申请。
恭喜你，获得了一次完整的从零配置体验。
这酸爽，谁经历谁知道。
---
五、如何备份（保姆级教程）
备份这件事，简单到离谱：
# 1. 先停 Gateway，防止更新过程中有文件写入
openclaw gateway stop
# 2. 打包整个状态目录
cd ~
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz .openclaw
# 3. 备份你的工作区（如果你有单独的工作区目录）
tar -czf openclaw-workspace-$(date +%Y%m%d).tar.gz .openclaw/workspace-writer就这样。两个压缩包，你的命就保住了。
备份在哪里？
- 移动硬盘 / U盘（物理备份）
- 云存储（iCloud、Dropbox、Google Drive）
- 另一个机器 via
scp
别就放在本机。硬盘是会坏的，电脑是会丢的。
---
六、更新后出问题了怎么办？
先别慌。大部分问题有标准排查流程。
第一步：诊断
openclaw status openclaw gateway status openclaw doctor openclaw logs --follow
这四个命令按顺序跑一遍，大部分问题会在这里暴露出来。
常见问题及解法
问题一：Gateway 起不来
openclaw gateway status
看到 Runtime: stopped？
- 检查端口是否被占用：
lsof -i :18789
- 检查配置文件是否损坏：运行
openclaw config validate
- 看看是不是 Node 版本不对：要求 Node 24（或 Node 22.14+）
问题二：更新后配置报错
日志里出现 Config auto-restored from last-known-good？
这是好事。OpenClaw 自动回滚到了上一次正常工作的配置。
如果当前配置确实有问题：
# 找到被替换掉的旧配置 ls -lt ~/.openclaw/openclaw.json.clobbered.* diff -u ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.clobbered.XXX
然后手动修一下，或者用 openclaw config set 逐条修复。
问题三：渠道全掉了
openclaw channels status --probe openclaw pairing list --channel <channel-name>
检查一下配对状态。有些渠道（尤其是 WhatsApp）更新后可能需要重新配对。
问题四：npm 安装后还是旧版本
# 确认装的位置 which openclaw npm list -g openclaw # 强制重新安装 npm install -g openclaw@latest --force
---
七、回滚：如果更新真的把你坑了
npm 安装的回滚
# 先查你想回滚到的版本 npm view openclaw version # 安装指定版本 npm install -g openclaw@<version> # 然后运行 doctor 并重启 openclaw doctor openclaw gateway restart
自动回滚
如果 OpenClaw 更新后 Gateway 启动失败，它会自动使用上次正常工作的配置。
但这不代表你的所有数据都安全——备份才是真正的安全网。
---
八、自动更新：懒人方案
如果你懒得手动更新，可以开启自动更新。
编辑 ~/.openclaw/openclaw.json：
{ "update": { "channel": "stable", "auto": { "enabled": true, "stableDelayHours": 6, "stableJitterHours": 12 } } }
stable频道：会在发布后延迟 6-12 小时自动更新（错开高峰）
beta频道：每小时检查一次，有新版本立即更新
beta 爱好者请慎重。 最新的不一定是最稳的。
---
总结
| 操作 | 命令 |
|---|---|
| 确认安装方式 | openclaw doctor |
| 检查版本 | openclaw --version |
| 推荐更新 | openclaw update |
| 备份 | tar -czf backup.tar.gz .openclaw |
| 诊断问题 | openclaw doctor |
| 查看状态 | openclaw gateway status |
| 回滚 npm | npm install -g openclaw@<version> |
| 开启自动更新 | 配置文件加 update.auto |
最后一句话：更新前备份，更新后 doctor。