OpenClaw升级详细图文指南

OpenClaw 目前还处于“1.0”之前的快速迭代阶段，新功能和性能优化会像流水一样频繁发布。换句话说，保持更新是体验最新特性、拿到安全补丁、获得性能提升的关键。下面这份图文指南，帮你平稳、安全地完成 OpenClaw 的更新，少踩坑。

更新前的准备

动手更新之前，花几分钟做点准备，能省掉不少后顾之忧。主要就两件事：备份关键数据、搞清楚自己的安装方式。

备份你的个性化配置

虽说更新过程通常挺安全，但备份总没坏处。OpenClaw 的核心用户数据都在 ~/.openclaw/ 目录下。建议重点备份这三样：

• 配置文件：~/.openclaw/openclaw.json，里面存着网关和各项功能的配置。
• 凭证信息：~/.openclaw/credentials/ 目录，连接 WhatsApp、Telegram 这类服务的认证信息都在这里。
• 工作区：~/.openclaw/workspace，有些技能（Skills）生成或使用的数据会存放在这。

明确你的安装方式

知道 OpenClaw 是怎么装上的，才能选对更新方法。通常就两种：全局安装和源码安装。

搞清楚安装方式，接下来就能对号入座了。

官方推荐的更新方法

不管你是哪种安装方式，官方最推荐的路径是重新跑一遍网站上的一键安装脚本。这个脚本很智能：它会自动检测你现有的安装，直接做“就地升级”（upgrade in place），不会删除你的配置（macOS 系统下实测没问题）。

curl -fsSL https://openclaw.ai/install.sh | bash
执行完这条命令，安装程序会帮你处理后续所有事，需要的时候还会自动跑 openclaw doctor 来做修复和迁移。

如果不想更新后再看一次初始设置向导（onboarding），可以加个 --no-onboard 参数：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

对于源码安装的用户，想要让安装器用 git 来更新的话，可以这样：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

这条命令会尝试执行 git pull --rebase，不过前提是你的代码仓库是干净的（没有未提交的修改）。

不同安装方式的更新指南

如果不想用一键安装脚本，也可以根据安装方式手动更新。

更新全局安装的 OpenClaw

用 npm 或 pnpm 全局安装的话，更新很直接。打开终端，挑一条命令执行：

使用 npm：
npm i -g openclaw@latest

使用 pnpm：
pnpm add -g openclaw@latest

这两个命令都会从软件源拉取最新稳定版 OpenClaw 并覆盖当前版本。

更新源码安装的 OpenClaw

对于从 git 仓库克隆的源码安装，官方强烈建议用 OpenClaw 自带的更新命令：

openclaw update

这条命令封装了一套安全更新流程，它会自动做以下事情：

1. 检查当前工作区是否干净。
2. 切换到配置的更新通道（默认是稳定版）。
3. 从远程仓库拉取最新代码。
4. 安装或更新项目依赖。
5. 重新构建项目和控制台界面（Control UI）。
6. 运行 openclaw doctor 做配置检查和迁移。
7. 默认还会自动重启网关服务。

如果想更新后手动重启，加个 --no-restart 参数：

openclaw update --no-restart

当然，也可以完全手动走 git 流程，效果跟 openclaw update 差不多，但步骤多一些：

git pull
pnpm install
pnpm build
openclaw doctor

更新后必须执行的检查

不管用哪种方法完成了更新，强烈建议跑一下 openclaw doctor 命令。这相当于给更新上了道“保险”，它的设计目标就是修复、迁移和发警告：

openclaw doctor

openclaw doctor 通常会做这些事：

• 把旧配置项迁移到新格式。
• 检查并修复文件权限问题。
• 审核安全策略，对风险较高的开放设置发出警告。
• 检查系统服务（如 systemd 或 launchd）配置是否是最新的。

跑完这个命令，仔细看看输出信息，这是确保更新后 OpenClaw 稳定运行的关键一步。

重启网关服务

更新完代码和配置，得重启网关服务才能让变更生效。用 openclaw 命令行工具就能方便地管理网关：

openclaw gateway restart

这条命令会正确停止当前运行的网关，然后用新代码启动它。

其他相关命令也很实用：

openclaw gateway status
# 停止网关
openclaw gateway stop
# 查看实时日志
openclaw logs --follow

如果更新出现问题

有时候更新可能会带来预料之外的问题。这时候，回滚到上一个稳定版本是个有效的临时方案。

版本回滚（全局安装）

全局安装的用户，通过 npm 或 pnpm 可以直接安装指定旧版本。先用 npm view openclaw version 看看最新版本号，然后选一个更早的版本安装。比如想回滚到 0.8.0 版本：

npm i -g openclaw@0.8.0

装完之后别忘了再次跑 doctor 和重启网关：

openclaw doctor
openclaw gateway restart

版本回滚（源码安装）

源码安装的用户可以借助 git 回滚到任意历史提交。比如回滚到某个日期之前的最新提交：

git checkout "$(git rev-list -n 1 --before="2026-01-01" origin/main)"

切换到旧代码后，需要重新安装依赖并重启服务：

pnpm install
pnpm build
openclaw gateway restart

等下次想再更新时，切换回主分支拉取最新代码就行：

git checkout main
git pull

遇到难以解决的问题时，运行 openclaw doctor 并仔细阅读输出信息，通常能找到线索。官方的 Discord 社区也是寻求帮助的好去处。