夜雨聆风写给：想升级 OpenClaw 但怕踩坑的朋友
难度：零基础也能看懂
支持系统：Windows / macOS / Linux
来源：真实升级经验，2026年3月25日刚实测
先说个真实的场景
前两天，我的搭档升级 OpenClaw，按网上教程敲了命令，以为升级成功了。
结果第二天发现：
- • 飞书机器人没响应了
- • 记忆功能报错了
- • 网页界面卡得打不开
一问原因，升级的时候没停服务，边跑边升，把配置文件搞乱了。
升级 OpenClaw 最怕的不是"升级失败"，而是"看起来成功了，其实半瘫痪了"。
这篇文章，就是要让零基础的小白也能照着做、不踩坑。
你需要知道的 3 件事（升级前必看）
1. 升级前一定要先"关掉"再升级
这就像给电脑换内存条——得先断电，不然容易烧主板。
升级 OpenClaw 也是，必须先停掉网关服务，再升级。
操作很简单：
打开命令提示符（Win+R → 输入 cmd → 回车），依次输入：
# Windows
openclaw gateway stopmacOS / Linux：
# macOS / Linux
openclaw gateway stop停稳了再升级，升级完了再启动。
2. OpenClaw 有两套"家"，别搞混
OpenClaw 的程序装在 npm 的全局目录，但你的配置、数据、插件都存在另一个地方。
三个系统的目录位置：
| 系统 | 程序目录（npm全局） | 配置目录（.openclaw） |
|---|---|---|
| Windows | C:\Users\你的用户名\AppData\Roaming\npm | C:\Users\你的用户名\.openclaw |
| macOS | /usr/local/lib/node_modules 或 ~/.npm-global | ~/.openclaw |
| Linux | /usr/lib/node_modules 或 ~/.npm-global | ~/.openclaw |
类比一下：
- • 程序目录像是"汽车品牌4S店"（官方统一的）
- • 配置目录像是"你家车库"（你自己用的）
升级程序去4S店，升级配置去你家车库。
3. 升级完≠能用，一定要做"4轮检查"
很多人以为命令行显示升级成功就完事了。
不对。要依次检查这4项：
| 检查项 | Windows命令 | macOS/Linux命令 |
|---|---|---|
| OpenClaw版本 | openclaw --version | openclaw --version |
| 网关是否在线 | openclaw gateway status | openclaw gateway status |
| 飞书插件 | openclaw plugins inspect openclaw-lark | openclaw plugins inspect openclaw-lark |
| 飞书连通性 | openclaw feishu-diagnose | openclaw feishu-diagnose |
4项全绿，才算升级成功。
三系统升级方式（Windows / macOS / Linux）
Windows 升级
# 第1步：停网关
openclaw gateway stop
# 第2步：升级主程序
npm i -g openclaw@2026.3.23-2
# 第3步：升级飞书插件（如有）
openclaw plugins upgrade openclaw-lark
# 第4步：启动网关
openclaw gateway startmacOS 升级
# 第1步：停网关
openclaw gateway stop
# 第2步：升级主程序
sudo npm i -g openclaw@2026.3.23-2
# 第3步：升级飞书插件（如有）
openclaw plugins upgrade openclaw-lark
# 第4步：启动网关
openclaw gateway start注意：macOS 可能需要加
sudo来获取管理员权限。
Linux 升级
# 第1步：停网关
openclaw gateway stop
# 第2步：升级主程序
sudo npm i -g openclaw@2026.3.23-2
# 第3步：升级飞书插件（如有）
openclaw plugins upgrade openclaw-lark
# 第4步：启动网关
openclaw gateway start注意：如果用 Deepin、UOS 等国产Linux系统，可能需要额外配置字体和依赖库。
每一步的检查与复核（防坑关键）
以下是每个升级环节可能出现问题的地方，以及如何自查和解决。
环节1：停网关服务
标准动作：
openclaw gateway stop可能出现的问题：
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 提示"gateway not running" | 本来就没运行 | 不用管，直接升级 |
| 提示"Permission denied" | 权限不足 | Windows用管理员运行，macOS/Linux加sudo |
| 等了很久没反应 | 可能卡住了 | Ctrl+C 取消，用 taskkill（Windows）或 kill（macOS/Linux）强制结束 |
Windows强制结束：
taskkill /F /IM node.exemacOS/Linux强制结束：
killall node环节2：升级主程序
标准动作：
npm i -g openclaw@2026.3.23-2可能出现的问题：
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 提示"文件被占用" | 网关没停干净 | 重新停一次，或强制结束node进程 |
| 提示"EACCES"权限错误 | npm没有写权限 | macOS/Linux加sudo |
| 下载很慢或失败 | npm源在国内访问慢 | 切换到国内镜像：npm config set registry https://registry.npmmirror.com |
| 提示"UNKNOWN ERROR" | npm版本太旧 | 先升级npm：npm i -g npm |
国内加速（可选但推荐）：
npm config set registry https://registry.npmmirror.com
npm i -g openclaw@2026.3.23-2环节3：启动网关
标准动作：
openclaw gateway start可能出现的问题：
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 提示"port already in use" | 端口被占用 | 查一下哪个进程占用了端口（Windows: netstat -ano | findstr :18789） |
| 启动后立即退出 | 配置文件有错误 | 看日志，日志路径在 ~/.openclaw/logs/ |
| 启动很慢 | 首次初始化正常现象 | 等1-2分钟，超时再排查 |
环节4：版本验证
标准动作：
openclaw --version预期结果： 显示的版本号应该和你安装的版本一致。
常见问题：
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 显示旧版本号 | npm缓存问题 | npm cache clean --force 再重装 |
| 提示"command not found" | PATH没配置好 | 检查npm全局目录是否加入系统PATH |
6个真实踩过的坑（附解决方案）
这些都是这次升级中真实遇到过的，不是理论坑。
坑1：没停服务就升级，文件被占用了
现象：
- • 升级命令卡住不动
- • 提示"文件被占用"
- • 升级完版本号变了，但运行的是旧进程
原因：OpenClaw 正在跑的时候，文件被锁定了，npm 无法替换。
解法：
openclaw gateway stop
# 等3秒
openclaw --version # 确认停了
npm i -g openclaw@2026.3.23-2
openclaw gateway start坑2：飞书诊断显示"不健康"，其实是配置残留
现象：
- • 插件明明装好了
- • 但诊断命令显示 UNHEALTHY
原因：配置文件里有一个"幽灵账户"——旧的账户信息没删干净，但已经没有有效凭证了，它在那儿干扰判断。
解法：
打开 ~/.openclaw/openclaw.json（Windows: C:\Users\你的用户名\.openclaw\openclaw.json），找到 channels.feishu.accounts，把里面没有凭证的 default 账户删掉，保存，重启网关。
坑3：插件显示"已加载"，但运行时报错
现象：
- • 插件状态显示 loaded
- • 但功能完全不能用，日志里一堆红字
原因：插件代码引用的"工具包"位置变了，代码还是旧的，找不到正确的模块。
解法：需要更新插件代码中的引用路径（涉及开发操作，不建议小白自己搞，建议重装插件或等插件作者更新）。
经验：看到"loaded"不够，要看运行日志里有没有红色报错。
坑4：配置文件里不小心存了密钥
现象：
- • 把真实的飞书密钥直接写进了配置文件
- • 可能在下一次备份、分享时泄露
解法：
- • 升级或修改服务后，立刻检查配置文件
- • 确保里面没有真实 token、secret
- • 用环境变量来存密钥，不要硬编码
坑5：网页很卡，不一定是坏了
现象：
- • 网页打开慢
- • 命令行界面也卡
原因有两层：
- 1. 启动时要初始化记忆插件、飞书插件等很多东西，第一打开本来就慢
- 2. 命令行实时刷新大量日志，系统控制台渲染会拖慢
解法：
- • 清理浏览器缓存
- • 把网关改成"安静模式"，不往命令行输出日志
- • 后台运行，不要一直开着命令窗口
坑6：自定义过服务配置，又无脑"修复"了
现象：
- • 运行
openclaw doctor --repair - • 结果把自己写的自定义脚本覆盖了
- • 服务反而不能用了
解法：
- • 如果你之前做过"隐藏启动"等自定义配置
- •
doctor --repair会把你定制的脚本覆盖成默认模板 - • 这不是故障，是你把自己的配置弄丢了
- • 有自定义需求的话，慎用
--repair
升级后验收清单（照着打勾）
第一轮：基础检查
openclaw --version
openclaw gateway status看到版本号对上了、RPC probe 显示 ok，就过了第一关。
第二轮：飞书检查
openclaw feishu-diagnose看到凭证完整、API连通、权限通过就OK。
注意：DEGRADED（降级）不一定不能用，先看具体警告内容。
第三轮：记忆检查（如果有）
openclaw plugins inspect memory-lancedb-pro看到 Status: loaded 且没有新的红色报错就OK。
第四轮：实际测试
让机器人回复一条消息：
- • 记忆插件：发一句话，等10秒，再问相同问题，看它能不能记住
- • 飞书：发一条消息，看机器人有没有响应
推荐的标准升级顺序
每次升级都照这个顺序来，最稳：
第1步：备份！备份！备份！
第2步：记录当前版本（截图也行）
第3步：停网关
第4步：升级 OpenClaw 主程序
第5步：升级飞书插件
第6步：启动网关
第7步：跑版本检查
第8步：跑飞书诊断
第9步：跑记忆检查（如果有）
第10步：打开网页测试小白最容易犯的8个错
- 1. 不停服务直接升级
- 2. 只看版本号，不看网关是否真启动
- 3. 只看插件 loaded，不看日志有没有报错
- 4. 忽略配置文件里的旧账户残留
- 5. 把
.openclaw和 npm 目录搞混 - 6. 把真实密钥写进脚本文件
- 7. 发现网页卡就反复重装插件
- 8. 自定义过服务后又无脑
doctor --repair
一句话总结
升级 OpenClaw 的正确姿势 = 先停服务 → 再升级 → 再检查 → 最后打开网页。
Windows / macOS / Linux 三平台通用，就这么简单，但80%的人踩坑都是因为省了"停服务"这一步。
温馨提醒：升级有风险，操作前务必备份。
如果升级后出现问题，不要反复重装，先查日志。