教程 · 维护
OpenClaw 升级、回滚与彻底卸载
OpenClaw 自带升级、回滚和卸载命令，但能退回旧软件包，不等于能撤销已经发生的数据迁移。各渠道现在指向哪一版，见《OpenClaw 稳定版、测试版、长期支持版装哪个，更新渠道怎么切换》；动手当天用 npm view openclaw dist-tags 和官方发布记录查最新版本。
- 发布日期
- 更新日期
升级前：备份配置、凭据和工作数据
升级可能迁移配置和数据库。升级时自动留下的配置副本、迁移原件和旧软件包各有用途，但都不是完整备份。用下面的命令创建并校验一份归档，然后看它打出的报告里有没有你实际在用的状态目录和放在别处的工作区：
mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify顺手记下当前版本号，回滚时要用：
openclaw --version # 记下这个号，万一要退回归档里有你的 API key 和渠道凭据，放的位置要跟 ~/.openclaw 一样小心，别丢进公共网盘。
怎么升级 OpenClaw：openclaw update 的用法和先别升的两种情况
不管你当初是用一键脚本、npm 还是源码装的，升级都是同一条命令。它会自己识别安装方式、拉最新版、跑一遍 openclaw doctor 体检、再把后台的 Gateway 重启：
openclaw update怕它做什么没数，先预演一遍，它只打印计划不真动：
openclaw update --dry-run两种情况先别升。一是状态目录放在 FUSE 挂载上的，比如 NAS 映射进 Docker 的目录：有用户报告这种情况下更新会在 Doctor 那一步失败（#163179），修复（#164123）截至 2026 年 10 月 7 日还没进 latest 指向的 2026.9.8，见 OpenClaw 2026.9.8 更新说明里 FUSE 状态目录的一节。二是源码安装的：有一条还没关闭的报告（#166300），更新后旧会话被自动续上，见 2026.9.8 更新说明里源码安装旧会话的一节。
升完跑一条最小任务验证它还正常：
openclaw gateway status
openclaw dashboard
# 控制台里给它一句：建个 hello.txt 写一行再读回来最小任务通过后，还要检查原来的渠道、定时任务和会话历史；定时任务用 openclaw automations list --all 列出来看，带 --all 才包括已停用的。更新中途失败时先保存报告，保留它点名的恢复目录，按报告和官方恢复指引处理；状态没弄清之前别反复重装，会把排查要用的现场盖掉。报告里的原因码各自怎么处理，看 OpenClaw 更新失败的原因码对照。
想固定在某个版本不动怎么做
固定版本要管住三处：装的是哪一版、保存的渠道是哪条、自动更新开没开。发布渠道会一直往前走，光选一条保守的渠道，装着的版本以后还是会变。普通安装和 Docker 的做法不同。
普通安装：先装指定版本
openclaw update --tag <版本号> --dry-run
openclaw update --tag <版本号>--tag 只管这一次：它换掉的是这一回要装的包，保存的渠道不变，之后的更新、自动检查和 openclaw update status 仍然按保存的渠道走。保存的渠道是 extended-stable 的，--tag 不能和它同用，指定确切版本时要按官方指引加 --channel stable，装完跑 openclaw update status 看一眼当前渠道。
普通安装：再看它会不会自己升
装完以后还会不会自动升，取决于渠道和自动更新的设置。按官方自动更新文档，各项管的范围是：
update.auto.enabled：管 Gateway 的自动更新，默认是关的。没开过它，Gateway 不会自己装新版，要你运行openclaw update才升。update.checkOnStart：管更新检查。设成false会关掉所有自动更新检查和更新提示，功能统计也一并关掉，update.auto.enabled是true时也一样。OPENCLAW_NO_AUTO_UPDATE=1：环境变量，同样关掉自动检查和自动应用。extended-stable渠道：只给更新提示，从不自动应用。它只支持包安装，源码安装用不了。
渠道和自动更新的开关，在控制台的 Settings → Updates 里也能改。有一处要单独看：长期运行的打包版无头 node（前台的 openclaw node run 和装成服务的 node）默认会自动更新，不归 update.auto.enabled 管；要它不动，在 node 那台机器的配置里把 nodeHost.autoUpdate.enabled 设成 false，上面的 update.checkOnStart: false 和 OPENCLAW_NO_AUTO_UPDATE=1 对它也有效。
不求固定、只想更新得慢一点的，用 openclaw update --channel extended-stable。它会记住这个渠道，渠道指向的版本以后还会变，新版本要自己运行 openclaw update 才装。切到 beta 之前做好备份，之后能不能降回来要看状态格式。
Docker 方式：镜像标签写死版本号
镜像别用 :latest，用带版本号的标签，写成 ghcr.io/openclaw/openclaw:<版本号>（标签不带 v 前缀，GitHub 上的发布标签带 v）。要升才手动改标签。
2026.9.8 改了什么，见2026.9.8 更新内容与升级失败的处理办法。
回滚：先确认旧版本能否读取现有状态
能不能退回去，要看旧版本读不读得了现在的配置和数据库。先预演；更新器因为 schema 或配置太新而拒绝时，别绕过这道检查。
旧版本读得了现在的数据：用 --tag 退回去
# 看看有哪些版本
npm view openclaw versions --json
# 先预演，再真退
openclaw update --tag <你记下的旧版本号> --dry-run
openclaw update --tag <你记下的旧版本号>更新器会校验目标版本、问你是否确认降级，然后重启并检查 Gateway。保存的渠道是 extended-stable 的，先看固定版本一节里 --tag 那条提醒。
旧版本读不了现在的数据怎么办：用升级前的备份恢复
格式不兼容、状态损坏，或者要找回旧数据，就得用备份恢复。把当前状态和更新报告另存一份，用 openclaw gateway stop 停掉 Gateway，其他会写这些目录的进程也停掉，然后按官方恢复指引，用和旧版本匹配、校验过的那份备份恢复。恢复会盖掉备份之后的所有变化，要留的新数据提前拷出来。
Docker 装的
# 把镜像标签指回旧版本，重建容器
docker compose down
# 改 compose 里的 image 标签为旧版本号，然后
docker compose up -d挂载卷里留着数据，也留着新版做过的数据迁移，所以 Docker 一样要看旧版本读不读得了现有状态；读不了就用和旧版本匹配的备份恢复。别用删卷的办法来“修好”启动问题。
一键脚本、npm、源码这三种装法都优先用 openclaw update 来退，直接用 npm 换包不会走同一套恢复流程。确认会话和原来的任务都恢复之前，别清理更新报告留下的恢复原件。
彻底卸载 OpenClaw：卸载命令和手动清理清单
龙虾自带卸载命令，会按顺序把后台服务、状态目录、工作区、桌面端都清掉。先预演看它打算删什么，再真删：
# 只看不删
openclaw uninstall --dry-run --all
# 确认无误再来真的
openclaw uninstall --all想留着工作区（你的 SOUL.md、记忆、产出文件）只删别的，就去掉 --all，按提示只勾 service / state / app 这几项——默认就会保留工作区目录。
万一 openclaw 命令已经没了、后台服务却还在跑，按这份手动清单走：
- 停服务、删服务：Linux / WSL 上它是 systemd 用户级服务。
macOS 上对应的是 launchd：systemctl --user disable --now openclaw-gateway.service rm -f ~/.config/systemd/user/openclaw-gateway.service systemctl --user daemon-reloadlaunchctl bootout gui/$UID/ai.openclaw.gateway，再删~/Library/LaunchAgents/ai.openclaw.gateway.plist。 - 删状态目录：这一步清掉大头（配置 + 凭据 + 会话 + 默认工作区一起没）。要留工作区的话先把它挪出去。
rm -rf ~/.openclaw - 删命令行本体：按你当初的装法选一条。
npm rm -g openclaw # npm 装的 pnpm remove -g openclaw # pnpm 装的 - 删本地模型文件：本地模型单独占地，不用了一并删（路径看你当初拉到哪）。
- 撤权限授权：之前给龙虾的文件/系统访问授权，到系统设置里撤掉。
- Docker 用户：换成删容器、删镜像，再删龙虾自己的数据卷。先打开你的 compose 文件，看清楚龙虾挂了哪些卷，要留的数据先备份，再逐个删。别图省事用
docker volume prune：它清的是整台机器上所有没被引用的匿名卷，不只是龙虾的，而且默认删不到命名卷。docker compose down docker rmi ghcr.io/openclaw/openclaw:<你用的标签> docker volume ls # 对照 compose 文件，找出龙虾用的卷 docker volume rm 卷名 # 确认归属后逐个删
走完这几步，龙虾自己的东西就基本清掉了。Node、Git 这些通用环境可以留着，它们不是龙虾专属的。
常见问题
- 升级 OpenClaw 会把我的配置和数据弄丢吗？
- 升级可能迁移配置或数据库。升级前用 openclaw backup create --verify 创建并校验备份，看报告里有没有状态目录、凭据和实际在用的工作区。Docker 的挂载卷也要备份：卷留着，新版做过的数据迁移也留着。
- 升级后龙虾跑不起来了，怎么退回旧版本？
- 用 openclaw update --tag 旧版本号 --dry-run 预演。旧版本读得了现有状态的，按更新器的提示确认回退；读不了的，要用升级前校验过的备份配上对应的旧版本来恢复。降级软件包或 Docker 镜像不会把配置和数据库的迁移倒回去。
- 怎么把 OpenClaw 卸得一点不剩？
- 照本页彻底卸载一节做：备份要留的数据，跑 openclaw uninstall --dry-run --all 看删除计划，没问题再跑 openclaw uninstall --all。命令已经不可用，或者是 Docker 装的，按同一节的手动清单逐项清：停掉并删除后台服务、删 ~/.openclaw、卸命令行本体、删本地模型文件、撤系统授权；Docker 是删容器、镜像和龙虾自己的数据卷。别的应用还在用的模型文件和共享卷别删。