企业官网建设流程全解析

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-backup

Termux（安卓）环境同理，用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 兼容接口的调用方式做了调整，所以升级后建议做两件事：

1. 确认 Ollama 服务还在运行，ollama serve没有意外退出。
2. 确认模型名称写法变了没有——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 -r

Windows 则建议关掉当前终端窗口，重新打开一个再试。别小看这一步，十个人里至少有两个人是因为这个原因白白重复了一遍升级流程。

4.2 启动失败时按照日志顺序排查

新版启动失败时，常见原因有三类，按检查顺序排列：

先把完整错误信息贴到终端——openclaw doctor或者启动时的输出里会有具体报错。重点看是否有"config validation failed"字样，如果出现就说明是配置文件校验没过；再看端口是否被占用，OpenClaw 默认监听端口如果被其他进程抢占了，启动也会失败，换个端口或者结束占用的进程即可；最后检查依赖版本，如果之前是长时间没升级，中间可能跨越了依赖大版本，源码和依赖对不上。

排错的通用思路是：不要看最后一行报错，重点看第一处标红的内容。最后一行往往是连锁反应的结果，源头还在前面。

4.3 想要卸载干净重装？先备份配置再操作

如果你实在排查不清楚，或者升级过程中弄坏了环境，最干净利落的方案是卸载重装。有热词专门搜"怎么卸载 openclaw"，这里给个不开玩笑的完整方案。

首先跑官方卸载命令：

openclaw uninstall

这个命令会移除主程序文件和启动项，但通常不会动你的配置目录和 skills。如果确定要彻底重来，再手动删掉残留目录：

rm -rf ~/.openclaw rm -rf ~/openclaw

Windows 下除了卸载程序，还要手动清理%USERPROFILE%\.openclaw和%APPDATA%\OpenClaw目录。Termux 下则是pkg uninstall openclaw加手动删除目录。

这里特别提醒：卸载前一定要确认备份已经做好，特别是密钥文件。很多人卸载时嫌麻烦没备份，结果想重装时发现 API key 已经找不回来了，等于从头配置。

4.4 升级后自动化任务不生效，检查后台服务是否用了旧路径

还有一个比较容易忽略的场景：如果你通过 systemd 服务或计划任务让 OpenClaw 开机自启，升级后会发现自动化任务可能不生效。原因是旧的 systemd 服务文件里写的 ExecStart 路径还指向旧版本目录。升级完成后记得执行：

systemctl daemon-reload systemctl restart openclaw

Windows 上如果是计划任务方式，也要重新编辑任务的执行路径。这个问题和 4.1 是同一个根源，都是"新旧路径没对齐"，只是发作地方不同。

这里再补充一个通用的提醒：升级前最好先看一眼官方版本的发布说明，上面通常会列清 breaking changes。我这次升级之所以顺利，就是提前发现 3.13 调整了配置校验规则，先把 config 改好再升的。如果直接盲目执行 update，大概率要在启动报错之后来回试错半小时。

我个人在实际操作中的习惯是，每次升级完先开一个终端跑openclaw doctor做自检，然后用一个熟悉的技能触发一次任务，确认核心链路通了以后再切到其他功能。这套流程虽说不复杂，但能帮你把升级后的排查成本压到最低。毕竟 OpenClaw 的玩法延展空间很大，从接 API 到配 Ollama 再到自定义 skills，每一步都值得慢慢调，别因为一次版本升级把兴致磨没了。