OpenClaw 更新迁移卸载教程，版本升级和重装处理指南

OpenClaw 长期运行之后，更新、迁移和卸载往往比第一次安装更容易出问题。原因很简单，这时候你手里已经不只是一个 CLI，而是一整套正在工作的系统，包括：

• Gateway 服务
• 状态目录
• 模型认证
• 渠道登录会话
• Dashboard 访问配置

一旦处理顺序不对，影响的就不只是“程序能不能启动”，而是你之前已经跑通的整套环境会不会被打乱。

所以这篇不讲泛泛原则，重点讲三件事：

1. 更新前先做什么
2. 迁移时哪些东西一定要保
3. 卸载时哪些能删，哪些别乱动

更新前先做三件事#

无论你准备升级版本、修复损坏环境，还是迁移到新机器，开始前都建议先做这三步：

1. 备份状态目录

最先要保住的不是 CLI 安装文件，而是状态目录。通常优先考虑备份：

~/.openclaw

这里往往包含：

• 配置
• 认证信息
• 渠道会话
• Gateway 运行相关状态

如果你直接重装程序，却没保住这部分内容，体验上很可能就等于重搭一套系统。

2. 运行 doctor

官方最推荐先跑：

openclaw doctor

因为它不仅能检查状态，还能帮助你判断当前环境更适合：

• 修复
• 迁移
• 还是重新安装

不要跳过这一步。很多人一上来就删目录，最后反而把本来还能修的环境搞得更乱。

3. 看 Gateway 当前状态

再补一条非常值得先做的检查：

openclaw gateway status
openclaw status --deep

这两步的意义是：

• 确认服务现在是不是活着
• 确认系统当前还有没有明显结构性问题

如果更新前就是异常状态，更新后问题通常只会更难分辨。

什么时候更适合“更新修复”，而不是“迁移重装”#

如果你遇到的是下面这些情况，通常更适合先按修复思路走：

• 升级后行为异常
• 服务没被正确接管
• Dashboard、渠道、模型状态突然不一致
• 运行环境基本还在，只是局部出问题

这类场景里，更推荐的顺序是：

1. 先跑 openclaw doctor
2. 再看 openclaw gateway status
3. 再看 openclaw logs --follow

不要一上来就判断“必须重装”。

升级时最重要的验证顺序#

如果你已经更新完成，最值得按下面顺序验证：

1. openclaw --version
2. openclaw gateway status
3. openclaw status --deep
4. openclaw dashboard
5. 再检查模型和渠道是否仍然正常

这套顺序的好处是，你能快速判断：

• 新版本 CLI 是否真的装上了
• Gateway 是否还能正常运行
• 系统整体健康状态是否正常
• 控制台能不能进入

如果这 4 步都没问题，再去验证 Telegram、WhatsApp、模型 provider，会更清楚。

迁移时真正要带走什么#

迁移最常见的误区，是以为只要在新机器上把 CLI 装好就算完成。其实真正决定迁移是否成功的，通常是这些：

• 状态目录
• 模型认证信息
• 渠道登录状态
• Gateway 相关配置
• 你的工作习惯和已有环境配置

所以迁移时最重要的一句话是：

先保状态，再动程序。

哪些迁移场景最常见#

最常见的迁移场景通常有这几类：

从本地电脑迁到 VPS

适合：

• 你已经完成本地验证
• 现在想把 Gateway 长期在线化

从旧主机迁到新主机

适合：

• 你准备更换服务器
• 原机器环境太旧
• 想统一运维结构

从临时环境迁到长期环境

适合：

• 一开始只是随手试
• 现在准备正式使用

无论哪种场景，重点都不是“程序怎么安装”，而是“旧状态怎么保留”。

迁移到新主机的推荐顺序#

如果你准备换机器，我建议按这个顺序：

1. 在旧机器上备份 ~/.openclaw
2. 在旧机器上运行一次 openclaw doctor
3. 在新机器上安装 CLI
4. 再恢复状态目录
5. 启动并验证 Gateway
6. 最后再验证模型、Dashboard 和渠道

这个顺序的核心目的是把“程序安装”和“状态恢复”拆开，这样一旦出问题更容易判断是哪一层。

什么时候才考虑直接重装#

只有在下面这些情况里，直接重装才更有意义：

• 运行环境已经混乱到很难修复
• 服务残留过多
• 你本来就打算放弃旧环境
• 你明确知道旧状态不想保留

但即使如此，也建议先把状态目录完整备份出来，再决定要不要真的抛弃。

因为很多时候你以为自己不需要旧状态，后面才发现：

• 渠道会话还要重登
• provider 还要重配
• 某些配置值忘了之前怎么设

卸载前先想清楚两件事#

卸载 OpenClaw 时，最重要的是先分清：

1. 你是只想删程序
2. 还是连状态目录都不再保留

这两种操作影响完全不同。

只删程序

适合：

• 你准备重新安装
• 你想保留配置和登录状态

程序和状态一起清理

适合：

• 你明确不再需要旧环境
• 你想彻底重建一套全新系统

在没想清楚前，不要直接删状态目录。

卸载或重装前的推荐检查#

在真正执行卸载前，建议至少先确认：

openclaw doctor
openclaw gateway status

同时确认你已经知道：

• 当前状态目录在哪里
• 里面哪些内容后面还会用到
• 是否还需要保留模型认证和渠道会话

如果这些你都说不清，就还不适合直接做“彻底删除”。

最常见的错误做法#

这几种做法都很容易出问题：

• 一出问题就先删 ~/.openclaw
• 没有备份就直接重装
• 程序和状态目录一起删掉，之后才发现要重登所有渠道
• 升级后不做任何验证，直接继续用

真正稳的做法永远是：

• 先备份
• 先诊断
• 先验证
• 最后才决定删不删