OpenClaw 3.13 发布那天我群里至少有三次出现同一个问题“怎么升”。有人直接git pull把仓库拉下来跑结果技能全部加载失败有人照着旧文档改配置结果模型接口 401还有人干脆把整个目录删了重新装折腾一晚上。说实话升级 OpenClaw 不是难事难的是在不破坏现有技能、不重配模型、不停机太久的前提下把版本切过去。这篇文章我尽量把 3.13 的升级路径讲清楚哪些人该升、怎么备份、三条部署方式对应的操作流程、以及升级后最容易踩的四个坑。看完你至少能少走一半弯路就算真出问题也知道怎么原路退回去。1. 升级前先摸底3.13 这版到底改了什么1.1 先判断“该不该升”OpenClaw 从早期版本开始就不是一个“读两篇文档就能跑”的项目。尤其 3.13 这种主版本号推进通常意味着技能定义格式、模型接入协议、配置 schema 都会动。我从 2.x 一路升上来最大的感受是每一次大版本升级爽的是新功能疼的是配置迁移。3.13 官方 Release Notes 里比较重要的改动集中在三个方向第一是技能Skill定义格式新增了入口、运行超时、错误重试策略这些字段第二是模型网关的接入方式老的关键字配置被收拢成结构化的provider model_id写法方便接 Ollama 这类本地模型第三是修掉了 ROS2 Humble 环境下 gazebo 仿真时的几个通信超时问题。如果你正好被仿真卡死或者想接本地模型这次升级值得做。如果你只是日常稳定跑着没碰到任何 bug我不建议当天就跟风升。判断标准其实很简单先看 Release Notes 里有没有“breaking change”列表再对着自己的使用场景打勾。你主要用技能编排、模型调用、ROS2 集成那 3.13 基本绕不开你只是把它当成一个 API 服务挂着那等一两个 patch 版本再升也不迟。我自己处理版本问题的习惯是升级前先花十分钟列一张“我到底在用哪些功能”的清单比直接动手改配置有用得多。1.2 备份清单一份备份单可以救你三次我在升级前会固定跑三件事一条都不能少。备份配置目录包括config/、skills/、.env以及 docker-compose 文件。用tar -czvf openclaw_backup_$(date %Y%m%d).tar.gz config skills .env一条命令打一个包然后扔到别的目录或网盘。备份自定义技能目录尤其是你自己写的技能。别指望 Git 分支能救你本地未提交的改动多了去了还有一堆调试用的临时文件丢了就是真丢了。记录当前版本号直接openclaw --version或者看镜像 tag。没有版本号做对照出问题后连回滚都不知道回哪里。如果你用的是 Docker 部署除了备份文件还可以用docker commit手动打个镜像快照。比如docker commit openclaw openclaw-backup:3.12.0这个快照就留在本地升级前心里就有底了。源码部署的话直接git stash或者单独建一个backup_before_313分支把当前工作区改动留个底。不要嫌麻烦这些操作平时不怎么占地方但升级失败时就是你的救命稻草。我见过太多人删掉旧配置文件的那一瞬间才后悔等反应过来已经晚了。2. 三条快速升级路线照着抄就行2.1 源码部署git 滚动升级怎么操作才安全源码部署的升级听起来简单git pull origin main一把梭实际执行起来很容易出问题。正常流程应该是这样# 1. 先切到稳定分支拉取所有更新和标签 git fetch --all --tags git status git checkout main git pull origin main # 2. 查看当前版本与最新版本之间的依赖文件差异重点看 requirements.txt git log --oneline v3.12.0..v3.13.0 -- dependencies/ # 3. 重新安装依赖这一步不要偷懒 python -m pip install -r requirements.txt npm ci # 如果前端/插件部分用到 Node 的话看到git status里有未提交改动的时候先别pull。要么git stash要么提交到临时分支。我见过有人直接拉代码把本地改的配置覆盖掉结果整个技能系统全乱了还得从备份里翻。依赖安装是最容易出事的环节。OpenClaw 对 Python 版本和 Node 版本都有下限要求如果你用的是系统自带的 Python版本可能偏旧。建议在虚拟环境或 conda 环境里做不要直接干到系统环境。装完依赖后先跑一遍自带测试或者如果有openclaw doctor这类检查命令就跑一次确认环境没问题再重启服务。还有一个容易忽略的点有些传递依赖会被自动升级到最新版导致行为不一致。建议把requirements.txt里的关键依赖锁定到 3.13 对应的版本区间别让 pip 自行放飞。实际操作中我一般会先把依赖装到一个干净的虚拟环境里跑通官方示例后再切回正式环境这样能过滤掉大半环境问题。2.2 Docker 部署换镜像不停数据Docker 部署的升级本质上就三步拉新镜像、确认挂载卷还在、重启容器。但实际执行时我见过太多人在“数据卷”上翻车。升级前先检查你启动容器时挂载了哪些卷docker inspect openclaw | grep -A5 Mounts重点看两个路径配置目录和技能目录。如果这两个目录没有挂载出来而是写死在容器里面那你升级新镜像的瞬间旧配置和技能就全没了。正确做法是启动容器时用-v把宿主机目录映射进去比如docker run -d \ --name openclaw \ -v /opt/openclaw/config:/app/config \ -v /opt/openclaw/skills:/app/skills \ -v /opt/openclaw/logs:/app/logs \ your-image:3.13.0升级时先拉新镜像再停止旧容器用同样的挂载参数启动新容器。注意不要docker rm掉旧容器旧容器还在你就能随时查看旧日志和旧配置甚至直接再启动做回滚。如果之前用的是docker-compose逻辑更简单把image: your-image:3.13.0改一下然后docker compose pull docker compose up -d。但注意核对 compose 文件里的环境变量和端口映射尤其是模型 API 地址或本地模型地址有没有写死旧版。比如你之前用的是 3.12 镜像里的内置默认地址升级后可能变成新默认值行为就变了。2.3 安卓/边缘端部署空间与模型文件是最大变数很多人在手机上或者树莓派这类设备上用 Termux 跑 OpenClaw这个场景比较小众但我还是要单独说。升级前先看磁盘剩余空间df -h看一下至少保证临时目录和依赖安装目录有 2GB 以上余量。Termux 这类环境最烦的就是空间不足装到一半报Space unavailable整个包管理器状态就乱了。另外如果你在边缘端挂了本地模型比如通过 Ollama升级 OpenClaw 之后模型文件一般不用动但模型服务地址和技能目录路径要重新确认。边缘端升级最稳妥的做法不是“就地增量升级”而是先备份 skill 目录再清空旧版本相关文件重新安装 3.13。相比电脑端手机上的升级成功率本来就低别抱着“增量升级”的心态硬试。我自己的经验是边缘端永远走“备份-清理-重装-验证”这条老路虽然慢但起码每次都能成功。3. 配置与技能迁移最容易被忽略的升级重灾区3.1 配置文件的兼容性处理大多数升级失败根本不是代码问题而是配置没有跟着新格式走。3.13 的配置 schema 有调整拿模型配置举例旧版可能是这种写法# 旧写法 api_key: sk-xxxx model: gpt-4o base_url: https://api.example.com新版更倾向于结构化写法# 3.13 推荐写法 model: provider: openai model_id: gpt-4o api_key_env: OPENAI_API_KEY base_url: https://api.example.com你在升级前最好去官方文档翻一翻 Migration Guide看看哪些字段被废弃、哪些字段改了名。直接拿旧配置启动新版本有时不会报错但很多功能会悄悄失效这才是最坑的——表面上看服务起来了实际上技能调度全走了默认参数。有一个技巧升级后先别急着切正式配置用旧的配置文件复制一份改名为config.old.yaml留着然后手动创建新配置跑一遍官方示例技能。如果示例技能正常再慢慢把旧配置里的自定义项搬过来。搬一项验证一项不要一次性全量迁移。我升级 3.12 的时候就吃过这个亏一次性搬了二十多个自定义项结果半天定位不到是哪个字段写错。3.2 模型服务与技能目录的重新绑定配置里最容易踩的模型相关坑不只是 API key。3.13 对模型网关做了调整以前你直接在配置里写一个模型 ID 就行现在可能需要显式声明 provider。如果你接的是本地 Ollama你还需要确认base_url指向的是 Ollama 的地址不要写成localhost。因为容器内部访问宿主机要写host.docker.internal或宿主机局域网 IP这个细节能卡住你半天。技能目录方面3.13 的技能格式加了字段旧技能可能还能加载但可能出现“技能能查到、却调用不起来”的现象。我自己的做法是把所有自定义技能过一遍对照新格式补字段。特别是超时时间和重试策略新版把这两个参数提到了技能定义顶层。如果你的技能依赖网络或机器人硬件响应建议把超时时间调大一点避免任务跑到一半被中断尤其是真实机械臂场景中断一次可能就要重新标定。4. 升级后的验证与回滚4.1 功能验收清单服务能启动并不代表升级成功我习惯按这份清单逐项验收核心服务状态openclaw status或看 docker logs 里有没有 fatal error、反复重启的日志。技能列表完整跑openclaw skill list确认自定义技能和官方技能都在数量对得上。模型连通性跑一个最小调用测试确认你常用的模型包括本地 Ollama能正常应答不报 401、不超时。ROS2 桥接验证如果你在仿真环境用启动 gazebo 场景跑一个简单动作看通信是否超时、话题是否正常发布。日志里有没有 Warning很多兼容性问题都是 warning 先冒出来的别忽略。任务执行链路拿一个最简单的“抓取-放置”任务完整跑一遍观察任务状态流转是否正常。升级后我会把验收结果简单记一条笔记。不是炫耀也不是交差而是方便下次升级或别人遇到同样问题时能快速对照“上次是正常的这次哪里变了”。4.2 如何优雅回滚升级最怕的不是失败而是失败了只能“重装系统”。回滚方式要看你的部署方式。Docker 部署最简单旧镜像没删直接再跑旧 tag 就行比如docker run ... your-image:3.12.0。如果加过docker commit快照那就更稳镜像回退和依赖版本完全锁死。源码部署也不难如果之前打了 taggit checkout v3.12.0后重新装依赖即可。麻烦的是配置已经改成了新格式旧版本读不了所以升级前那份备份配置的价值就体现出来了直接换回旧配置一切如初。有一点要特别注意如果你升级后创建了新的技能或任务数据而这些数据的存储格式是新的那回滚后可能读不了。所以要么升级前备份数据库或状态目录要么升级后在正式环境先用一两天观察不要马上把旧备份删掉。我一般会保留两个版本的备份至少一周内不回滚才会清理旧备份。5. 高频坑位实录这些问题我基本都踩过5.1 “gcc 升级了还是旧版本”这个话题几乎是源码部署用户的必踩坑。你明明升级了 gccgcc --version却还显示旧版本。这不是 OpenClaw 的问题而是 Linux 下常见环境问题新的 gcc 装到了/usr/local/bin但 shell 的PATH还指向前面的/usr/bin后者优先级更高。解决办法是确认安装路径后做软链接或者直接指定编译器路径。在升级编译型依赖之前先跑which gcc和gcc --version确认你要用的是哪一个。很多 C 扩展编译失败都是因为编译器和链接器版本不对应。关键是不要“看教程说装新版就装新版”装完要验证PATH顺序。还有一点升级完 gcc 后如果 Python 的 C 扩展还是报错可能需要pip cache purge清一遍旧缓存否则 pip 会复用已编译的旧扩展新版本就白装了。5.2 “Node 版本不对技能加载失败”OpenClaw 的部分组件尤其和前端或技能运行沙箱相关的部分依赖 Node.js。很多人在升级后遇到技能加载失败查下来是 Node 版本太低。Ubuntu 系统自带的 Node 可能是 12/14而 3.13 需要 18。这时候别去动系统 Node用 nvm 装一个新版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash nvm install 20 nvm use 20然后确认node -v和npm -v再重新安装前端相关依赖。两个坑提醒一下第一Termux 环境里 nvm 不一定好用可能直接用社区维护的nodejs-lts包更合适第二升级 Node 后记得清 npm 缓存旧依赖缓存非常容易伪装成新版本导致加载失败。我遇到过界面能打开、但技能列表始终为空的情况清完缓存重装依赖就好了。5.3 “模型调用总超时或 401”升级后模型调用失败最常见的三个原因一是 API key 对应的环境变量没传进去二是新版模型配置里识别不到 key 或 provider三是你把密钥写死在了旧配置里新配置没同步。排查思路是先在终端里手动执行echo $OPENAI_API_KEY或你设置的变量名确认环境变量存在再去日志里看具体报错。如果是 401大概率是密钥或 provider 不对如果是 timeout大概率是base_url地址问题。如果你用的是本地模型比如 Ollama先curl http://localhost:11434/api/tags确认服务在不在。容器里部署 OpenClaw 时localhost 指向容器自身不是宿主机所以要写host.docker.internal或局域网 IP。这个问题我用一次踩一次写出来就是帮你省一次排查时间。5.4 别点搜索引擎里的“升级页面”这次想特别提醒一下升级的时候千万别在搜索引擎里点“页面升级访问”之类的链接。OpenClaw 升级只认官方仓库和官方文档任何让你“访问最新入口”“每日更新跳转新域”的页面基本都是流量劫持或者钓鱼套路。尤其 3.13 发布这种热门节点新用户一搜“openclaw 升级”就容易点到广告链接。我的建议是把官方仓库地址收藏进浏览器书签任何时候只从收藏夹进入别从搜索结果点。这类问题跟技术无关但被坑一次真的会让人崩溃。我是见过有人下了个“升级包”结果整台电脑被装了一堆奇怪的浏览器插件。升级软件本身是为了解决问题不是为了给自己添堵来源靠谱比什么都重要。顺便整理一份升级常见问题速查表方便你遇到问题时快速定位问题现象可能原因排查方向解决建议技能列表为空Node 版本太低、npm 缓存未清理node -v、重装依赖用 nvm 升到 18 并清缓存模型调用 401API key 未传入或 provider 声明不对echo $API_KEY、查看日志检查环境变量和模型配置字段模型调用超时base_url 写错或本地模型不可达curl 测试模型网关容器内写host.docker.internal确认 Ollama 在运行编译依赖失败gcc 版本不对或 PATH 顺序有误which gcc、gcc --version调整 PATH 或软链接必要时清 pip 缓存旧配置启动不报错但功能异常配置 schema 不兼容对照 Migration Guide手动迁移配置逐项验证升级中断后服务起不来依赖不一致、文件残留查看启动日志优先用旧镜像回滚别急着清理备份6. 聊聊我自己的升级节奏最后说点我个人的习惯不一定适合所有人但至少可以给你一个参考。我现在的做法是不追每个小版本而是等一个主版本发布两周左右、社区反馈稳定后再升。升级前固定做三件事备份、读 Release Notes、跑一次官方示例。升级后一周内保留旧版本备份确认稳定再清理。这个节奏看起来很慢但反而很少出大问题。OpenClaw 这种更新频繁的开源项目新版本往往伴随着新功能和新的 breaking change急于跟风容易把自己变成小白鼠。真遇到必须升级的场景比如修复了影响你的 bug那就按文章里的流程走备份做扎实基本都能半小时内切换完毕。我实际用下来3.13 在 ROS2 Humble 仿真环境下的稳定性确实比 3.12 好不少值得花这一个小时去升级。