OpenClaw 3.13 发布也有一阵子了社区里聊得挺热闹但后台私信里问得最多的不是新功能好不好用而是我到底该怎么升。仔细想了想这也不奇怪。OpenClaw 这工具跟普通软件不一样安装路径本身就五花八门——有人用官方安装脚本装的有人走 Windows Companion 图形界面有人是在安卓 Termux 里折腾的还有人拿它配 Ollama 跑本地模型。升级方式要是照搬一种翻车的概率不小。我自己的环境里同时跑着 Windows 和 Linux 两套 OpenClaw前几天刚把两个节点都升到了 3.13中间踩了几个不太容易察觉的坑也顺手把配置和 skills 都做了迁移。这篇就当是个人升级记录把从备份到实操、再到升级后排查的完整流程梳理一遍。不管你当初是怎么部署的照着这个思路走基本能一次搞定省得在群里到处问人。1. 升级前先搞明白这次升级动了什么为什么容易翻车很多朋友拿到新版本第一反应就是直接跑更新命令跑完发现服务起不来然后开始怀疑人生。其实 OpenClaw 这种工具升级失败九成不是命令错了而是旧配置和新版本对不上。1.1 3.13 的核心变化集中在这几块先说这次版本改动比较大的地方。根据发布说明和社区反馈3.13 主要动了三块东西第一是 skills 加载机制。新版本把技能skills的加载方式改了以前你塞进 skills 目录的脚本只要是 .md 文件就能被识别现在要求必须带 YAML front matter而且元数据里的 name、description 字段格式更严格了。也就是说你以前直接复制到目录里就能用的那些技能升级后很可能被静默跳过不是报错就是压根不加载非常隐蔽。第二是配置文件的校验逻辑。3.12 时代配置写错了只给 warning还能继续跑3.13 直接改成 error 级别启动时校验不过就拒绝运行。听着更严了但说实话对长期维护是好事——很多奇怪的问题其实就是配置文件里藏了个远古的错别字。第三是模型接入层的统一。以前 OpenClaw 接各家 API 的方式比较分散OpenAI 一套写法、Claude 一套写法、本地 Ollama 又是另一套写法。3.13 把 provider 配置抽象成了统一的接口格式意味着升级后你原来的模型配置大概率需要手动迁移格式变了服务不会帮你自动改写。这三块改动其实是一个共同思路让项目更规范化、更利于后续维护。但对于已经在跑旧版本的老用户就意味着升级不是简单的覆盖文件而是需要动动配置。所以第一步不是急着升级而是先明确自己当前用的什么版本、什么方式部署的、配置放在哪个位置。1.2 升级前务必备份的三样东西每次升级之前我都会提醒自己备份不是可选项是必选项。特别是 OpenClaw 这种配置和技能分散在多个目录的工具漏掉一个可能就得重新配半天。至少要备份以下三个目录配置主目录Linux/macOS 下一般在~/.openclaw/Windows 下在%USERPROFILE%\.openclaw\。里面存放的 config 文件、密钥信息、用户偏好都在这里。skills 目录通常位于配置目录下的skills/子目录或者你自定义的OPENCLAW_SKILLS_DIR环境变量指向的位置。这里面是积累的私有技能丢了很可惜。自定义的 personas 或 prompts 模板如果你自定义过角色设定或指令模板记得一并备份升级时这些文件虽然不会自动删除但有时会因为格式兼容问题被闲置。备份命令很简单Linux/macOS 下直接打包cp -r ~/.openclaw ~/openclaw-backup-$(date %F)Windows 下在 PowerShell 里执行Copy-Item -Recurse $env:USERPROFILE\.openclaw $env:USERPROFILE\openclaw-backupTermux安卓环境同理用cp -r就行。备份好之后下一步才是真正的升级操作。2. 各平台快速升级实操Windows、Linux、Termux 各有各的招OpenClaw 的部署方式比较自由所以升级路径也不完全一样。先说结论官方安装脚本其实已经内置了升级能力只要你在安装时保留了更新通道一条命令就能完成。但不同平台加上不同安装方式细节上还是有不少差异。2.1 通用命令先检查更新再执行升级不管你是什么平台如果当初是用安装脚本装的、而且没有手动关闭自动更新OpenClaw 本身就带了一套 OTA 升级机制类似于手机系统里的在线更新客户端定时向版本服务器查询最新版本号发现本地落后就走内置的下载流程。所以最快最稳妥的升级方式是直接在终端里跑openclaw update --check这一步先看能不能发现 3.13 新版。如果返回结果正常接着执行openclaw update这个命令会自动检测当前安装位置、下载新版文件、保留配置目录并触发平滑重启。实操中我建议先开一个独立终端跑这条命令不要夹在正在进行的长任务里执行避免进程被中断引发数据异常。如果跑完发现版本号没变先别慌这是本节第 4.1 小节要展开讲的经典坑——大概率不是升级失败而是终端缓存或 PATH 环境变量还指着旧路径。2.2 Windows 平台的两种升级方式Windows 上的情况稍微复杂些因为大家装 OpenClaw 通常走的是官方推荐的 OpenClaw Windows Companion 图形工具。这个工具本身带有检查更新按钮位置一般在设置页的About或者Update标签下点击后会自动下载安装包完成后按提示重启服务即可。如果你当初是直接命令行安装的 Windows 版本手动升级更简单。去官方发布页面下载最新的 Windows 压缩包解压后覆盖之前的安装目录即可。覆盖前记得三点先停止正在运行的服务别在进程占用文件时强行替换。不要覆盖配置文件目录一般是安装目录外层或用户目录下只替换程序文件。覆盖后运行openclaw --version确认版本号。顺带提醒一句Windows 下升级不要用管理员权限强行写系统盘OpenClaw 装到用户目录下最省心权限问题少升级也通畅。2.3 Linux/macOS 命令行升级我在 Linux 服务器上部署时用的是官方安装脚本升级走的是 git pull 加重新安装依赖的组合。如果你当初是通过克隆仓库方式安装的升级步骤如下cd ~/openclaw git pull origin main ./install.sh update这里的install.sh update会重新拉取依赖并检查系统环境。如果只执行了git pull而没跑安装脚本可能会出现代码已经是新的、但依赖库还是旧的情况这种半升级状态最容易出诡异问题。基于 git 方式安装的话还有个细节要留意如果你本地改过源码git pull可能会提示冲突。升级前先git stash暂存修改升级完再git stash pop。个人经验是尽量别改源码内部逻辑OpenClaw 的自定义能力已经通过配置和 skills 开放出来了改源码既不利于升级也容易埋坑。2.4 安卓 Termux 部署的升级要点热词里有人搜如何用termux安装openclaw手机版下载步骤说明在手机上部署 OpenClaw 的朋友真不少。Termux 环境里升级有一个关键区别必须先升级 Termux 本身的基础包再升级 OpenClaw否则很容易遇到依赖库版本不匹配的问题。Termux 下推荐顺序pkg update pkg upgrade -y cd ~/openclaw git pull origin main ./install.sh update手机上跑 OpenClaw 本来就更吃资源升级期间建议保持屏幕常亮不要切后台不然进程被系统杀掉可能留下半更新状态。另外 Termux 从官方仓库获取包的网络路径有时不稳定如果pkg update卡住可以换个时间段再试或者在 termux-change-repo 里切换镜像源这个不算 OpenClaw 的问题是 Termux 本身的环境配置。2.5 用 Ollama 本地部署时的升级提醒另一个比较常见的部署组合是OpenClaw Ollama也就是用本地模型跑推理不走云端 API。升级 OpenClaw 本身不会动 Ollama但新版本对 OpenAI 兼容接口的调用方式做了调整所以升级后建议做两件事确认 Ollama 服务还在运行ollama serve没有意外退出。确认模型名称写法变了没有——Ollama 里的模型访问地址格式在新版中统一为http://localhost:11434/v1如果你之前配的是旧地址/api之类要做相应修改。这两步看着不起眼实测评测下来很多人都在这上面报错报错信息还不是特别直观容易被带偏。3. 升级后的配置迁移与 skills 适配别让旧配置拖垮新版本升级完成之后很多人就忙着去试新功能了结果跑到 models 或者 skills 的地方直接报错。这里面的问题从根上说就是配置格式没跟上。3.13 对配置和技能的规范要求收紧了不少所以升级后的第一件事不是玩新功能而是先做适配。3.1 配置文件迁移旧格式会被标记但不会自动转换我在 3.13 升级完成后第一次启动日志里看到一行提示大意是当前配置文件使用的字段格式是 legacy将在未来版本移除。这就是新版本对旧配置的兼容策略不会直接帮你改但会通过告警提醒你逐步迁移。具体来说3.13 把模型接入的 provider 配置收敛成了统一格式如果你用的是云端 API那新的配置长这样model: provider: openai api_key_env: OPENCLAW_OPENAI_KEY model_name: gpt-4o-mini base_url: https://api.openai.com/v1如果你之前是分别写了openai_api_key、openai_base_url这种散装字段升级后建议手动整理成上面的统一格式否则后续想切换模型时会发现参数互相覆盖非常难受。另外3.13 对配置文件的校验严格到一个多余空字段都会报错的程度。如果你升级后启动失败先别改代码用openclaw config check或直接看启动日志找到具体是哪一行校验没过多半是少了缩进、多了多余冒号这类小问题。3.2 skills 技能包的升级与兼容检查这次升级中我个人最关注的就是 skills 机制。新版对技能包的要求整体抬高了一个档次所有技能脚本开头必须有 YAML front matter且至少包含name、description、version三个字段。没有任何元数据的旧技能新版直接忽略。升级后第一时间执行openclaw skills list看看哪些技能还在哪些已经被跳过。如果你的技能确实因为缺少元数据被跳过补一个文件头就好了格式参考--- name: web_search description: 搜索互联网并返回摘要 version: 1.0.0 ---补齐后重启服务或执行openclaw skills reload就能重新加载。另外3.13 还引入了技能热加载特性这意味着你改完 skills 文件不需要重启整个 OpenClaw只要触发一次 reload 就能生效。这在调试技能时非常爽不用再反复启动服务白白浪费时间了。3.3 模型接入层调整本地与云端兼顾如果你像我一样本地 Ollama 和云端 API 都在用3.13 的模型接入方式会要求你做出选择——多 provider 现在是在配置里并列写的而不是以前那样靠注释切换。并列配置的好处是你想换模型时只需要改model_name和provider两个字段不用再注释一大段配置。坏处是如果两个 provider 的 key 环境变量命名冲突新版会直接报错而不是悄悄覆盖。建议统一使用OPENCLAW_LLM_API_KEY这种清晰命名或者给每个 provider 配上独立的环境变量前缀避免相互干扰。4. 升级遇到问题怎么排查版本不变、启动失败、卸载重装的完整思路升级这件事最怕的不是报错而是报错报得莫名其妙。我把升级过程中遇到的几个高频问题整理成速查表按顺序排查基本都能解决。4.1 升级完成后版本号显示旧版本多半是 PATH 的锅这个问题几乎每轮版本更新都会出现对应的典型场景就是命令提示符里跑 openclaw --version结果还是 3.12。很多人第一反应是升级没成功其实不用急着重新升级大概率是 shell 会话中还缓存着旧命令路径。排查方法很简单Linux/macOS 下执行which openclaw看看解析到的路径。如果你升级后安装目录变了而 PATH 环境变量还指向旧路径那自然读到的还是旧版本。解决办法是刷新一下路径缓存旧终端直接关掉重开或者执行hash -rWindows 则建议关掉当前终端窗口重新打开一个再试。别小看这一步十个人里至少有两个人是因为这个原因白白重复了一遍升级流程。4.2 启动失败时按照日志顺序排查新版启动失败时常见原因有三类按检查顺序排列先把完整错误信息贴到终端——openclaw doctor或者启动时的输出里会有具体报错。重点看是否有config validation failed字样如果出现就说明是配置文件校验没过再看端口是否被占用OpenClaw 默认监听端口如果被其他进程抢占了启动也会失败换个端口或者结束占用的进程即可最后检查依赖版本如果之前是长时间没升级中间可能跨越了依赖大版本源码和依赖对不上。排错的通用思路是不要看最后一行报错重点看第一处标红的内容。最后一行往往是连锁反应的结果源头还在前面。4.3 想要卸载干净重装先备份配置再操作如果你实在排查不清楚或者升级过程中弄坏了环境最干净利落的方案是卸载重装。有热词专门搜怎么卸载 openclaw这里给个不开玩笑的完整方案。首先跑官方卸载命令openclaw uninstall这个命令会移除主程序文件和启动项但通常不会动你的配置目录和 skills。如果确定要彻底重来再手动删掉残留目录rm -rf ~/.openclaw rm -rf ~/openclawWindows 下除了卸载程序还要手动清理%USERPROFILE%\.openclaw和%APPDATA%\OpenClaw目录。Termux 下则是pkg uninstall openclaw加手动删除目录。这里特别提醒卸载前一定要确认备份已经做好特别是密钥文件。很多人卸载时嫌麻烦没备份结果想重装时发现 API key 已经找不回来了等于从头配置。4.4 升级后自动化任务不生效检查后台服务是否用了旧路径还有一个比较容易忽略的场景如果你通过 systemd 服务或计划任务让 OpenClaw 开机自启升级后会发现自动化任务可能不生效。原因是旧的 systemd 服务文件里写的 ExecStart 路径还指向旧版本目录。升级完成后记得执行systemctl daemon-reload systemctl restart openclawWindows 上如果是计划任务方式也要重新编辑任务的执行路径。这个问题和 4.1 是同一个根源都是新旧路径没对齐只是发作地方不同。这里再补充一个通用的提醒升级前最好先看一眼官方版本的发布说明上面通常会列清 breaking changes。我这次升级之所以顺利就是提前发现 3.13 调整了配置校验规则先把 config 改好再升的。如果直接盲目执行 update大概率要在启动报错之后来回试错半小时。我个人在实际操作中的习惯是每次升级完先开一个终端跑openclaw doctor做自检然后用一个熟悉的技能触发一次任务确认核心链路通了以后再切到其他功能。这套流程虽说不复杂但能帮你把升级后的排查成本压到最低。毕竟 OpenClaw 的玩法延展空间很大从接 API 到配 Ollama 再到自定义 skills每一步都值得慢慢调别因为一次版本升级把兴致磨没了。