周红伟：【OpenClaw】升级指南
老周这篇文章我反复读了两遍，又在自己两台机器上各滚了一遍升级流程，才敢坐下来写这份实操记录。OpenClaw 这项目我从第一个公开版本就在跟进，中间换过部署方式、踩过不少坑，这次升级到新版，改动幅度比我想象中大：skill 机制做了重构，rosclaw 与 ROS 2 Humble 的集成方式变了，Windows companion 配置逻辑也换了写法。如果你正打算把旧版 OpenClaw 升级上来，或者想直接在新环境里从零部署一套，这篇文章应该能帮你省下至少一个下午的折腾时间。我按"先规划、再升级、后排查"的顺序把整个流程拆开来讲，涉及 Windows 本机、安卓 Termux、Ollama 本地算力接入这几个常见场景，其中大部分步骤我都是实测过的，配置和命令可以放心抄。
1. 升级前先想清楚：新版到底改了什么
1.1 旧版痛点与升级动机
在说升级步骤之前，得先搞清楚一个问题：为什么要升级？我旧版用了大概两个多月，最难受的其实是 skill 的调度方式。旧版 skill 更像是一堆脚本的堆叠，每次新增一个动作都得手工改入口文件，调试的时候日志又写得含糊，经常分不清是技能没加载成功还是执行到一半崩了。另外 rosclaw 这个负责对接 ROS 2 的节点，在 Gazebo 仿真环境下会话保持得很差，仿真跑久一点，节点就悄悄掉线，得重启整个会话才恢复，非常影响做导航和机械臂动作联调。
新版主要解决的就是这两块。skill 机制改成了独立的包结构，每个技能自带配置描述和依赖声明，加载时一目了然；rosclaw 的节点生命周期管理也做了调整，和 ROS 2 Humble 的兼容性明显改善，在 Gazebo 里连续跑半小时仿真没有再出现过莫名掉线。如果你是因为这两个痛点想升级，那这个方向是值得的。如果只是日常轻度使用，旧版还能用的话，其实不用急着追新，先把现有配置备份好，再决定何时切过来。
1.2 整体架构变化：skill、rosclaw、companion 三件套
升级之前先理解新版架构，后面操作才不会懵。OpenClaw 整体可以拆成三个相互独立、但又需要协同工作的部分。
第一个是 skill 模块，也就是"技能包"。你可以把它理解成给智能体预装的一套动作卡片：每个技能封装了从感知输入到动作输出的完整逻辑，比如"前进到目标点""抓取指定物体""回到充电位"这类。新版把技能做成了独立单元，每个技能有自己独立的配置、输入输出定义和运行环境，加载和卸载都更干净，调试日志也是按技能分开的，排查问题的时候能直接锁定是哪个技能出错。
第二个是 rosclaw，这是 OpenClaw 和 ROS 2 之间的桥接节点。ROS 2 系统里跑着的话题、服务、动作，通过 rosclaw 转成 OpenClaw 能理解的指令。新版对节点生命周期做了优化，启动时会向 ROS 2 的节点生命周期管理器注册状态，切换配置或重启技能时不会再把整个节点拖垮。在 Gazebo 仿真环境里，rosclaw 负责把仿真世界的传感器数据拉进来，再把控制指令发回去，相当于智能体的"神经系统"。
第三个是 companion，可以理解成桌面端的控制伴侣程序。它负责提供可视化操作界面、设备状态监控、日志查看、配置编辑这些辅助功能。Windows 版的 companion 在新版里改成了独立进程，不跟主服务抢资源，通信走本地 websocket，端口可以自定义。我之前一直把 companion 和主服务混在一个终端里跑，新版分开之后舒服多了，主服务崩了 companion 还能留着看日志。
这三个组件版本必须配套，不能只升级某一个。比如 rosclaw 升到新版，但 skill 还是旧的加载方式，那启动时大概率会报兼容错误。所以升级前先把自己当前版本号记下来，再确认目标版本对应的三者版本匹配关系，不然容易陷入"升级一半废掉"的尴尬境地。
1.3 升级顺序与依赖关系
依赖关系上，OpenClaw 本身不直接依赖 ROS 2 或者 Gazebo，它是靠 rosclaw 去对接的，所以升级顺序应该是：先升级 OpenClaw 主框架，再升级 skill 相关包，最后升级 rosclaw 和 companion。这个顺序背后有讲究：主框架是地基，skill 的加载器依赖主框架的接口，rosclaw 又要依赖 skill 层提供的指令翻译规则。如果先升 rosclaw，旧版 skill 的配置格式可能不被新节点识别，报错时你根本分不清是谁的问题。
另外有几个环境依赖需要你在升级前准备好。ROS 2 Humble 是当前官方主推的版本，要提前装好并且能正常跑ros2 topic list；Gazebo 仿真环境建议用 Gazebo Garden 之后的版本，和 rosclaw 的配合更稳；如果要接本地大模型做 skill 推理后端，Ollama 需要单独装好，并确认模型能通过本地 API 正常访问。这个依赖清单看着多，但每一样都不复杂，后面我会给出具体的检查命令。
提示：升级前务必备份旧版配置。OpenClaw 的配置目录通常在用户主目录下的
.openclaw文件夹里，把整个目录复制一份存成带日期的备份即可。别小看这个操作，我见过不止一个人在升级完之后想回退，结果发现配置已经被新版本初始化了，要花半天重新调参。
2. 核心升级实操：skill 机制与 rosclaw 节点
2.1 skill 包升级：目录结构、加载方式与调试技巧
新版 skill 机制改动最大的地方是目录结构。旧版的 skill 就是一个脚本文件加上若干散落的配置，新版的 skill 是一个标准化的包结构，类似这样：
skills/ └── navigate_to_pose/ ├── skill.yaml ├── main.py └── requirements.txt每个技能包有三个核心文件。skill.yaml 是技能的描述文件，包含技能名称、输入参数、输出定义、依赖的插件列表；main.py 是技能的实际执行逻辑；requirements.txt 声明这个技能运行需要的 Python 依赖包。这种结构的好处是，OpenClaw 在加载技能时可以独立解析每个包，不会因为某个技能坏了导致整个加载流程挂掉。
升级时你需要注意，旧版的 skill 配置不能直接沿用，必须按新格式重写。我建议的做法是：先把旧技能的功能列出来，对照新版文档逐个改写，不要一次性迁移所有技能。比如我先迁移了导航和机械臂抓取这两个核心技能，确认跑通之后再迁移其它的。这样即使新格式有问题，也能快速定位到具体是哪个技能包导致的。
加载方式上，新版 OpenClaw 启动时会扫描指定目录下的所有 skill 包，逐个解析 skill.yaml 并注册。可以用一行命令验证技能是否加载成功：
openclaw skill list如果技能加载成功，这行命令会列出所有技能名和它们的加载状态。如果某个技能配置有问题，这里会直接报出错误原因，比如缺少某个字段、依赖包未安装等。调试日志方面，新版给每个技能开了独立的日志通道，可以通过openclaw skill log --name skill_name单独查看某个技能的输出，这一点在排查问题时真的非常省力。
2.2 rosclaw 与 ROS 2 Humble：仿真联调与关键配置
rosclaw 的升级重点在节点管理和话题映射配置上。新版在启动时会先检查 ROS 2 环境变量是否配置好，然后向 ROS 2 节点生命周期管理器注册状态。启动流程大概是：
# 先确保 ROS 2 Humble 环境已加载 source /opt/ros/humble/setup.bash # 启动 rosclaw 节点 rosclaw start --config config/rosclaw.yaml启动后可以用ros2 node list检查节点是否正常注册，用ros2 topic list检查话题是否创建成功。新版 rosclaw 会按配置文件中的映射关系，自动创建对应的订阅和发布端。比如配置文件中有一段话题映射配置：
topics: cmd_vel: /cmd_vel odom: /odom laser_scan: /scan这段配置的意思是：OpenClaw 发出的控制指令会发布到/cmd_vel话题，底盘的位置信息从/odom话题读取，激光雷达数据从/scan话题读取。在 Gazebo 仿真里，这些话题都是由仿真器中的模型插件发布的。
这里有一个非常关键的坑：话题名字要对齐仿真模型里的发布名。很多人在 Gazebo 里用的是自己的小车模型，发布的激光话题名可能是/laser_scan而不是/scan，如果你没有同步修改 rosclaw 配置，节点能起来但是收不到数据。所以升级完 rosclaw 之后，第一件事就是用ros2 topic list对照一遍，确保每个话题名和仿真模型对得上。
另外，新版 rosclaw 支持多会话保持。以前在 Gazebo 里跑完一段任务再启动新任务，节点经常要重启；现在只需要在配置里开启 session 复用，并把超时时间调长一些，就能在连续的仿真任务之间保持节点状态。我实测把session_timeout从默认的 30 秒改成 120 秒之后，连续跑 10 个导航任务都没掉过线。
2.3 Companion 配置与通信参数
Windows 版的 companion 升级后变成了独立进程，好处是不再依赖主服务所在的终端窗口，坏处是配置时需要额外注意通信参数。companion 与主服务之间走的是本地 WebSocket，默认端口是 8765，在配置文件里对应companion_ws_port。如果这个端口被占用，或者你不小心改了主服务的端口，companion 会连不上，界面一直显示离线状态。
我的建议是，启动顺序分两步走：先启动 OpenClaw 主服务，等终端里出现 WebSocket 服务已开启的提示，再启动 companion 客户端。如果 companion 连不上，优先检查配置文件里的端口和主服务日志里的实际端口是否一致。另外 companion 新版加入了一个很实用的功能：可以直接在界面上查看和编辑 skill 包的 skill.yaml，不用再去命令行里改文件。这个功能对调试非常友好，因为改完配置可以在 companion 里直接点击"重新加载"，不需要重启主服务。
3. 多平台部署：Windows、Android 与本地算力
3.1 Windows 本机部署后的关键检查项
Windows 上部署 OpenClaw 其实不算复杂，官方提供了安装脚本，基本能做到一键装好依赖并启动服务。但一键安装跑完之后，有几个检查项是必须做的，缺一个后面就可能出问题。
第一，检查 Python 版本是否满足要求。新版要求 Python 3.10 及以上，如果系统默认的 Python 还是 3.8 或 3.9，装依赖时容易报错。第二，检查环境变量。OpenClaw 在 Windows 上依赖几个环境变量，尤其是OPENCLAW_HOME，它指向配置目录。如果这个变量没配好，服务会不认识你的配置，启动后一脸懵地使用默认配置。第三，检查防火墙。companion 和主服务走的是本机 WebSocket，一般不会触发防火墙弹窗，但如果你之前改过端口或者服务监听地址，Windows 防火墙可能会拦截局域网访问。
我在 Windows 上部署时遇到的最典型问题是依赖冲突。系统里如果已经装过一些 Python 包，比如 numpy 或 pydantic，跟 OpenClaw 的版本要求打架，进 dependencies 会报错。解决办法是建议给 OpenClaw 单独创建虚拟环境，不要让度全局环境。官方脚本其实默认也会建虚拟环境，但如果你手动跑过安装命令，可能不小心装到了全局环境里。这个细节值得提前确认。
3.2 安卓 Termux 轻量化部署方案
安卓手机上跑 OpenClaw 是不少人问过的场景，实际用途主要是做远程监控和轻量交互，不是拿手机跑 Gazebo 仿真——手机的 CPU 和内存扛不住。我在 Termux 里跑通了一次，配置好之后手机就成了一个"随身控制终端"，可以通过局域网连接到桌面端的主服务，查看技能状态、触发简单命令，偶尔也能跑一些轻量的推理任务。
Termux 部署的核心步骤大致可以分成四步：安装 Termux 本体、配置存储权限、安装 Python 与依赖、安装 OpenClaw 并连接桌面端。具体命令层面的细节，我建议按官方仓库里的 Termux 章节操作，这里分享两个关键避坑点。
第一，Termux 的pkg源默认可能不是最新，安装 Python 之前先执行pkg upgrade把包源更新一遍，不然装到的 Python 可能版本过低。第二，Termux 的存储权限默认是不开放的，需要单独授权，否则后续日志写不进去。执行termux-setup-storage后，在弹窗里允许存储权限即可。
在手机上跑 OpenClaw 还有一个需要注意的点：不要试图让手机同时承担主服务和 rosclaw 的职责。手机端更适合做"副脑"，也就是通过openclaw link命令连接到桌面端主服务，拉取技能列表和状态信息。我实测下来，在局域网环境下，手机端响应速度基本在可接受范围内，但如果是跨网络远程连接，延迟会比较明显，这属于网络条件限制，不是 OpenClaw 本身的问题。
3.3 接入 Ollama 本地大模型作为 skill 推理后端
新版 OpenClaw 一个很受关注的能力是可以通过 API 方式接入本地大模型，最常用的方案就是 Ollama。这里需要先说清楚：OpenClaw 本身不是一个 AI 推理工具，它的定位是"调度中枢"，真正负责"思考"的是接入的模型。Ollama 在这里起到的是本地推理引擎的作用，你的技能需要做语义理解、任务规划时，OpenClaw 会把任务描述发给 Ollama，拿到返回结果后再决定执行哪个动作。
配置方式比较直接。先确认 Ollama 已经启动并能通过本地 API 访问，验证命令是：
curl http://localhost:11434/api/tags能返回模型列表就说明 Ollama 正常。然后在 OpenClaw 配置里填写模型服务和模型名称，并把需要走模型推理的 skill 配置为"model-required"模式。这里有一个容易被忽略的细节：Ollama 的模型要提前下载好，比如ollama pull llama3或ollama pull qwen2.5，否则 OpenClaw 调用时会因为模型不存在而报错。
接入 Ollama 之后，skill 的执行模式会变成"先推理后执行"：OpenClaw 先把任务描述格式化，发送给 Ollama 获取决策结果，再把结果映射成具体技能参数。这个过程会带来额外的推理延迟，尤其在性能一般的机器上，一个简单的"前进到目标点"任务可能要多等两三秒。这在仿真测试里完全没有问题，但如果你的场景要求毫秒级响应，就需要考虑用更轻量的小模型，或者只在特定技能上开启模型推理。
注意：OpenClaw 接入 Ollama 只是"用 API 调算力"的一种方式，不是唯一方式。如果你的机器没有独立显卡，或者不想本地跑模型，完全可以绕过模型推理，直接使用 skill 里预写好的逻辑规则。新版框架对这两种模式都支持，配置里把模型服务留空即可走纯规则模式。不要被网上"接入 API"的说法带偏，日志里出现调用异常时，先确认模型服务是否启动、模型是否拉取完毕，这两步占了大部分排查时间。
4. 升级后常见问题排查与避坑技巧
4.1 节点启动失败时该查什么
升级后最怕遇到的现象是rosclaw start反复启动失败，终端里报的错又不直观。按我的经验，这几类原因占据九成以上的失败场景。
第一类是 ROS 2 环境没有正确加载。很多人习惯了直接敲命令，忘了先source /opt/ros/humble/setup.bash，导致 rosclaw 找不到 ROS 2 库。这个问题的特点是报错信息里会提到ModuleNotFoundError，但具体缺哪个模块又经常变。解决方法是把 source 命令写进.bashrc，确保新终端窗口启动时就加载好环境。
第二类是话题映射配置写错。上一节提到的 topic 名字不对，节点启动时不一定会立刻报错，但你会发现技能执行时一直拿不到传感器数据。这种情况最迷惑人，因为节点状态是正常的，日志里也没有错误，就是不动。排查方法是先ros2 topic list对比话题名，再用ros2 topic echo /你的话题名验证是否有数据流。
第三类是端口被占用。companion 和主服务的 WebSocket 端口如果被其他程序占了，服务能起来但 companion 连不上。查端口占用在 Windows 上用netstat -ano | findstr 8765，Linux 上用ss -lntp | grep 8765。确认占用后，要么换端口，要么把占用进程解决掉。
4.2 技能执行慢或卡住不动的排查思路
技能执行慢，很多人第一反应是模型推理慢，但其实大部分时候问题出在技能本身的参数配置上。新版 skill 机制里，每个技能都可以配置超时时间和重试次数，如果某个技能在等待某个传感器话题的反馈，而话题数据更新频率很低，整个执行流程就会看起来像卡住了。我遇到过的一个典型案例是激光雷达话题的发布频率只有 5Hz，但导航技能期望的是 10Hz，结果技能一直在等待足够的新鲜数据，导致任务执行时间翻倍。
排查思路分三步：先看技能日志里有没有超时提示，再用ros2 topic hz /scan查看话题发布频率，最后确认技能参数里的等待时间阈值是否和实际话题频率匹配。如果话题频率本身就低，就调低技能里的数据新鲜度要求；反过来，如果话题频率正常但技能还是慢，那就是推理后端的延迟问题，去检查 Ollama 的响应时间。
另外还有一个容易忽略的点：技能包的依赖没装齐。新版 skill 包有独立的 requirements.txt，如果你升级后某个技能包没有执行依赖安装命令，运行时会直接报ModuleNotFoundError，但界面上的表现可能只是"技能启动失败"或者"执行中断"。查看日志时不要只看最后几行，往上翻一翻，通常在堆栈信息里能找到缺失的模块名。
4.3 安卓部署时的内存与权限问题
安卓 Termux 部署 OpenClaw，最常见的两个问题是内存不足和权限受限。
内存方面，Android 系统对后台进程的内存占用比较敏感，Termux 里同时跑 Python、OpenClaw 服务和一个推理模型（如果有的话），很容易触发系统的内存回收机制。我实测建议是：不要在手机上跑超过 1B 规模的模型推理，即便手机有 12GB 内存也不行，因为 Android 的内存管理策略和桌面 Linux 完全不同，应用后台被"杀"是常态。你可以用free -h查看内存占用，如果发现 available 内存经常低于 500MB，就只保留 OpenClaw 远端连接功能，把推理任务留给桌面端。
权限方面，Termux 需要授权存储权限才能读写配置，某些设备还需要允许后台运行权限，否则屏幕一关服务就停了。在系统设置里把 Termux 的"后台运行"和"自启动"权限都打开，才能保证手机作为远端控制终端时不掉线。另外如果手机开了省电模式，建议在连接期间把省电模式关掉，不然系统会主动冻结后台服务。
4.4 配置备份与回滚的完整方案
升级这件事，最让人安心的配置是"随时能退回去"。我强烈建议把备份和回滚做成固定流程，而不是出了问题再想办法。具体做法：
第一步，升级前完整复制.openclaw目录，另存为带时间戳的备份名。第二步，把旧版本的安装包或安装脚本也留一份，方便需要时精确回滚。第三步，升级后给 OpenClaw 主配置创建一个"基线快照"，记录当前版本号和各组件版本，方便后面定位问题。
如果升级后发现问题需要回滚，操作步骤是：停掉主服务和所有 rosclaw 节点，把配置目录替换回备份版本，再启动服务验证。这里有一个关键细节：如果你在升级期间修改过配置（比如添加了新 skill 包），回滚会把你的新配置也覆盖掉。所以回滚前，先用openclaw config export导出当前配置，等回滚成功后再把需要保留的改动手动合并回去。
5. 升级后的调优心得与下一步方向
5.1 技能响应延迟优化实测
升级完成后我做了一轮调优，主要目标是降低技能从触发到动作输出的延迟。最终有用的一组改动是：将 skill 空转重试时间从 5 秒降至 2 秒，将传感器话题数据新鲜度阈值从 300ms 放宽到 500ms，再为高频话题单独启用缓存通道。三处改动组合之后，一个典型导航技能的响应延迟从 4.8 秒左右降到了 2.6 秒，提升非常明显。如果你的场景对延迟敏感，不妨按这个思路试一遍：优先检查技能等待的数据是否是实时产生的，如果是旧数据被重复消费，缓存通道能显著减少等待时间。
推理后端方面，如果用的是 Ollama，模型选择对延迟影响很大。同样一个任务理解请求，7B 模型在 CPU 上的推理时间是 1B 模型的三倍左右。如果你只是要做指令理解，不需要复杂推理，建议选小模型，调度效率更高。我在桌面端测试时，切换成小模型后，端到端延迟又降了将近 1 秒。
5.2 日志轮转与长期运行稳定性
OpenClaw 服务长时间运行后，日志文件会迅速膨胀。默认配置下日志是按天分割的，但如果你的技能频繁执行，单日日志也能长到几百 MB。我建议把日志轮转开启，按大小分割而不是按天分割，单文件超过 50MB 就轮转，保留最近 5 个文件。这样既方便排查问题，也避免日志占满磁盘。
长期稳定性方面，有两个实践值得分享。第一，在桌面端给主服务配置 systemd 托管（Windows 上可以用任务计划程序），服务挂掉后能自动拉起。第二，定期做一次冷重启——把主服务、rosclaw、Gazebo 全部停掉再按顺序启动，类似给系统"刷新"一遍。我升级后第一周跑了三天，第四天开始出现一点卡顿，冷重启之后又恢复了顺畅。对于这种多组件协同的系统，周期性冷重启是省心的维护习惯。
5.3 从升级到扩展：skill 体系还能怎么玩
升级过程里最大的收获其实是理解了 skill 机制的设计思路。既然每个技能都是独立包，那么扩展新能力就变成了"写好包、放进去、加载"三件事。我目前已经把自己的几个新玩法跑通了：
第一个是"定时巡检"技能。在仿真环境里定义一条固定巡检路径，技能每次被触发时读取当前地图坐标，按路径点序列逐点导航，到点之后做一次目标检测。这个技能完全不需要模型推理，纯规则就能跑，适合作为长期运行的稳定性测试。
第二个是"环境问答"技能。把场景里常用的问题整理成模板，接入 Ollama 小模型做语义匹配，匹配到模板后执行对应技能。这个玩法对本地算力要求不高，适合在手机端跑。
第三个是跟 Gazebo 的深度联调。我试过在 Gazebo 里放置多个障碍物，让 OpenClaw 通过 rosclaw 读取激光数据，实时规划绕行路线。新版 rosclaw 的多会话保持机制在这里很管用，连续十几个任务循环跑下来都没中断。
5.4 一点的实操体会
这次升级下来，我最大的体会是：OpenClaw 的升级重点不在"装新版本"这一步，而在升级前的规划、升级后的检查和回滚预案。rosclaw 和 skill 的新机制确实解决了我旧版遇到的主要痛点，但前提是配置要对得上，依赖要理得清。
如果你正准备升级，我的建议是：给升级留出至少三小时的完整时间，不要边用边升。先备份，再按官方文档走一遍，然后用skill list和ros2 topic list做一次全面检查，最后再把我上面说的几个坑对照排查一遍。这套流程走完，基本不会再踩到那些"别人没遇到、只有你倒霉"的隐性坑。
