OpenClaw 智能体

OpenClaw进阶：完整升级实践指南（升级总结、完整流程、安装旧版本）

2026 年 3 月 5 日

OpenClaw快速迭代时代，这份升级指南帮你安全高效完成版本更新，避免数据丢失风险。核心内容： 1. 升级前的关键备份操作与注意事项 2. 三种不同配置主机的升级方案详解 3. 特殊场景下的降级与故障恢复方案

OpenClaw 目前迭代非常迅速（几乎每两天一个版本），建议定期进行升级，以获取新功能和安全补丁。

本篇总结并规范OpenClaw升级流程，参考以下步骤操作，以确保升级过程平滑、数据不丢失。

一、项目环境

1，项目地址

https://github.com/openclaw/openclaw

2，查看当前openclaw版本

openclaw --version

二、OpenClaw升级实践

1. 升级前备份（重要）

注意：一般升级不会破坏已有配置，但为了万无一失，强烈建议在升级前备份整个工作区！！！

# 创建备份目录

mkdir -p ~/openclaw_backup

# 备份整个 OpenClaw 配置目录

cp -r ~/.openclaw ~/openclaw_backup/openclaw-backup-$(date +%Y%m%d)

#打包备份（可选）

```bashtar -cjvf ~/openclaw_backup/openclaw-backup-$(date +%Y%m%d).tar.bz2 ~/.openclaw```

# 备份后查看备份文件

```bashls -l ~/openclaw_backup```

2. 执行升级

# 停止当前运行的网关服务（可选，但推荐）

```bashopenclaw gateway stop```

# 升级方式一：使用 npm 全局更新到最新版本（低配主机推荐）

```bashnpm i -g openclaw@latest```

说明1：此种方式升级最简单，适合低配的如：2c2g 的云主机升级；如果安装openclaw的主机配置较高，推荐采用 openclaw update 命令更新

说明2：npm升级方式也适用于升级到中间版本（非最新版本）、回退到原始版本（老版本）

# 升级方式二：使用一键安装脚本升级（备选升级方案）

说明：重新运行官方安装脚本也可以将openclaw升级到最新版

```bashcurl -fsSL https://openclaw.ai/install.sh | bash```

说明：如果其它升级出现中断导致失败，可重新执行一键安装脚本进行重新安装或升级（万能方法）

# 升级方式三：使用 `openclaw update` 命令（高配主机推荐）

#执行更新：自动检测并应用更新、自动重启

```bashopenclaw update```

注意：低配不建议采用此种方式更新，容易挂（cpu负载过高，更新会卡死，甚至主机都没法用了）

#预览更新：只显示更新步骤，不实际执行

```bashopenclaw update --dry-run```

#非交互式更新：跳过确认提示（适合自动化脚本场景）

```bashopenclaw update --yes```

#执行更新但不重启（手动重启）

```bashopenclaw update --no-restart```

#新手引导更新：

```bashopenclaw update wizard```

# 升级方式四：让openclaw机器人自己更新

当不在电脑前时，也可以让AI小助手帮完成更新升级操作，注意要求升级前备份，示例：

```shell你帮我更新openclaw版本，更新前注意备份```

说明：此步有一定风险，AI小助手使用openclaw update进行自动更新，如果升级失败可能导致AI小助手失联（断开链接），建议升级版本间隔小的时候使用。

#升级方式五：自动更新

更改Gateway配置设置自动更新（自动更新默认处于关闭状态）

```json{  "update": {    "channel": "stable",    "auto": {      "enabled": true,      "stableDelayHours": 6,      "stableJitterHours": 12,      "betaCheckIntervalHours": 1    }  }}```

#更新通道说明:

stable (默认)	稳定版，推荐生产环境使用beta	测试版，提前体验新功能dev	开发版，最新但可能不稳定

#可以在更新命令时候设置：

openclaw update --channel betaopenclaw update --channel devopenclaw update --channel stable

3. 升级检查与修复

新版本可能会对配置文件或数据格式进行调整，运行 openclaw doctor 自动检查和修复问题：

（1）运行 doctor 检查状态

openclaw doctor

（2）使用 --fix 参数进行修复（说明：没问题则无需执行）

openclaw doctor --fix

#检查状态

#更新gateway service配置（推荐选择yes）

说明：虽然doctor会尽量保留用户自定义设置，但此步也有一定风险，如果升级版本过大，且有手动修改过服务配置文件且不想被覆盖，可以选择No

#zsh集成（选择yes，没有使用zsh的忽略）

#完成检查，提示使用 openclaw doctor --fix 应用更改

#执行修复应用修改

4. 重启服务并验证

# 重启网关

openclaw gateway restart

# 查看版本确认升级成功

openclaw --version

# 查看日志，确保没有报错

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 访问 Web UI（测试功能是否正常）

三、版本回退（安装旧版本）

1，当前版本备份和卸载

#备份或直接删除当前配置目录

mv ~/.openclaw ~/openclaw_backup/.openclaw_new_bakup-$(date +%Y%m%d)# rm -r ~/.openclaw

# 卸载当前版本（可选，但推荐）

npm uninstall -g openclaw

# 清理 npm 缓存

npm cache clean --force

2，回退旧版本配置文件

# 恢复备份 OpenClaw 配置目录

cp -r ~/openclaw_backup/openclaw-backup-20260303 ~/mv ~/openclaw-backup-20260303 ~/.openclaw

3，回退旧版本

#查看历史版本

npm view openclaw versions

#安装历史版本

# 全局安装指定版本npm install -g openclaw@<你要安装的版本号># 安装指定历史版本（例如 2026.2.15）npm install -g openclaw@2026.2.15

4. 回退后迁移与修复

# 运行 doctor 检查状态

openclaw doctor

# 使用 --fix 参数进行修复（说明：没问题则无需执行）

openclaw doctor --fix

5. 重启服务并验证

# 重启网关

openclaw gateway restart

# 查看版本确认升级成功

openclaw --version

# 查看日志，确保没有报错

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 访问 Web UI，发送一条消息测试功能是否正常

四、问题总结

问题1：origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)

解决：OpenClaw 升级后，为了加强安全防护，引入了更严格的访问控制策略。新版本不再允许通过非回环地址（即非 127.0.0.1 或 localhost）直接访问控制界面（Control UI），需要显式地在配置文件中声明允许访问的来源（allowedOrigins）

#配置 allowedOrigins

vi ~/.openclaw/openclaw.json

{  "gateway": {    // ... 其他配置    "controlUi": {      "allowedOrigins": [        "http://localhost:18789",        "http://127.0.0.1:18789",        "http://局域网IP:18789",        "http://公网IP:18789"      ]    },    "bind": "lan" // 绑定模式  }}

# 配置后重启

openclaw gateway restart

问题2：control ui requires device identity (use HTTPS or localhost secure context)

解决：根据页面提示，如果通过内外网IP且以HTTP方式访问，需要设置 gateway.controlUi.allowInsecureAuth: true (仅限令牌)。

#允许在不安全的 HTTP 下进行认证

{  "gateway": {    // ... 其他配置（如 bind, port 等）    "controlUi": {      "allowInsecureAuth": true    },    "auth": {      "mode": "token",      "token": "网关token"    }  }}

#命令设置方式

openclaw config set gateway.controlUi.allowInsecureAuth true#修改后重启网关openclaw gateway restart

说明：升级到 2026.3.2 发现设置`gateway.controlUi.allowInsecureAuth: true`后问题仍然存在

参考：https://docs.openclaw.ai/web/control-ui#insecure-http

#进一步解决：增加 dangerouslyDisableDeviceAuth: true 配置

openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true# 配置后重启openclaw gateway restart

立即咨询 JOTO

JOTO 提供覆盖企业智能体规划与搭建、AI 平台私有化部署、RAG 知识工程、AI 安全治理、FDE 驻场共创及持续运营优化的全周期 AI 落地服务，帮助企业把验证中的 AI 能力转化为安全、可控、可持续迭代的生产力。联系 JOTO 获取 AI 落地咨询

想把这些做法用到你的业务里?

留下你的场景和痛点,我们帮你判断从哪一步开始。

联系我们

OpenClaw进阶：完整升级实践指南（升级总结、完整流程、安装旧版本）

立即咨询 JOTO

想把这些做法用到你的业务里?

开启企业级 AI 落地

填写需求单