OpenClaw本地部署全指南：从WSL2环境验证到Ollama与ROS2联动

在Windows上第一次跑OpenClaw，我就卡在了一个看起来和项目本身毫无关系的地方：安装完WSL2后，启动脚本直接报无法安全验证WSL2环境。当时我第一反应是去翻OpenClaw的文档和仓库，翻了半天没找到针对性答案，最后绕回PowerShell里执行wsl --status才定位到原因。这篇内容我不打算只贴一份命令列表，而是想把从Windows到安卓、从Ollama到ROS2的完整部署过程，以及每个环节为什么要这么做的判断，都留个记录，免得下回重装系统时又踩一遍。

OpenClaw是一个本地优先的AI智能体框架，不是网页聊天框那种东西。它更像一个能自主调用工具的数字管家：你给它一个目标，它自己拆步骤、选方案、调用可用的工具链，甚至操作你的文件、浏览器、机器人。最近圈子里讨论比较多的几个点——WSL2环境验证失败、Node.js版本、Ollama本地模型、ROS2和Gazebo机器人仿真、安卓Termux部署——我这次全都试了一遍，下面按部署顺序逐个说。

1. 先搞清楚OpenClaw是什么：它不是一个聊天机器人

第一次听说OpenClaw的人，很容易把它和ChatGPT网页版混为一谈。实际上两者的定位完全不同：ChatGPT给的是"答案"，OpenClaw给的是"执行"。它核心的能力是任务规划 + 工具调用 + 多端协同。你可以把它想象成一个管家，你告诉它"把下载目录里的PDF按文件名整理到对应文件夹"，它不会给你一段Python让你自己跑，而是自己调用文件系统工具、写好脚本、执行完再向你汇报结果。如果你开启了对应权限，它甚至在完成后还能主动帮你清理临时文件。

1.1 它解决的痛点

我以前用过不少Agent类项目，最大的痛点是工具链割裂。有的Agent只能调用浏览器，有的只能调用终端，有的只能在固定平台上跑。OpenClaw的skill机制把它们统一了：每个能力都是一个skill，按名称、描述、参数声明注册到框架里，智能体根据用户目标的意图自动选择该调哪个skill。这套设计和ROS2的action通信逻辑很像，节点之间不关心对方内部实现，只关心接口和能力。所以它既能跑在PC上管文件，也能跑在机器人板卡上控制机械臂，因为底层接入方式对上层Agent是透明的。

另外一点是数据可控。纯API方案意味着你的对话、代码、文档指针都要经过第三方服务器，这对很多开发者和企业来说是不可接受的。OpenClaw可以在完全不联网的情况下工作，本地模型搞定绝大多数简单任务；只有遇到复杂多跳推理时，才按你的配置走云端API。这让它很适合被嵌入到内网工具链或嵌入式设备里。

1.2 算力来自API还是本地：一个很常见的疑问

在社区里看到有人问"openclaw只能用接入api的方式使用算力吗"，这里我可以直接回答：不是。OpenClaw支持三种算力来源，可以单独用，也可以混合：

• 本地Ollama：通过Ollama运行Qwen、Llama等开源模型，完全离线，数据不出设备。
• 本地推理框架：如果你有NVIDIA显卡，还可以接TensorRT、llama.cpp这类后端，把延迟压得更低。
• 云端OpenAI兼容API：把base_url指向任意兼容OpenAI接口的服务商或自建网关，适合需要大模型上限的场景。

最实用的做法其实是混合：日常任务走本地小模型，识别到复杂需求时自动切换到云端大模型。下面第3章我会给出我自己的混合配置示例，把fast model和slow model分开，效果很明显。

2. Windows + WSL2：第一步就卡了大多数人

OpenClaw的官方安装方式里，Windows平台推荐走WSL2，而不是在原生Windows上直接跑。原因是它依赖不少Linux生态工具，尤其是后续接ROS2、Gazebo、串口设备时，Linux环境会省掉90%的兼容性问题。我见过很多人装到一半就放弃，基本卡在三类问题上：WSL2环境验证失败、Node.js版本不对、以及搞不清Windows Companion到底是干嘛的。

2.1 "无法安全验证WSL2环境"排查链路

这是我这次遇到最典型的坑。OpenClaw启动脚本会检查WSL2环境，如果检测到异常，就会提示无法安全验证WSL2环境，并让你"请在powershell中运行wsl --status"。这个提示本身是有误导性的，因为wsl --status只是告诉你当前状态，不会帮你修。但排查链路确实是从这条命令开始的。

按下面顺序排查，大部分问题十分钟内能解决：

1. 先看状态。在PowerShell里执行wsl --status，确认输出里的默认版本是不是2，以及内核版本是否过旧。如果显示内核版本太低，直接跑wsl --update更新。
2. 检查Windows功能是否完整开启。这步最容易忽略。需要两个功能同时开启：适用于Linux的Windows子系统和虚拟机平台。管理员权限下执行：

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

   执行完必须重启系统，别想着省这一步。
3. 确认虚拟化没被锁死。打开任务管理器，性能选项卡，CPU，右下角看"虚拟化"是否显示"已启用"。如果没启用，需要进BIOS把Intel VT-x或AMD-V打开。很多笔记本出厂默认关着，这也是"无法安全验证"的隐性来源。
4. 检查系统安全设置。在部分Windows 10/11版本上，内存完整性（内核隔离）会干扰WSL2启动。如果你已经开启虚拟化、功能也都装了，还是报错，可以临时关闭内核隔离再试一次。关闭路径在Windows安全中心 -> 设备安全性 -> 内核隔离。
5. 设置默认版本。最后再执行一次：

   wsl --set-default-version 2

我那次的问题出在第2步：之前只装了一部分WSL组件，虚拟机平台没勾，导致wsl --status给出的信息看起来正常，但OpenClaw做安全校验时却失败了。后来我把dism命令完整跑完，重启，问题就消失了。

2.2 为什么要装Node.js 18+以及版本选择的讲究

OpenClaw本体依赖Node.js运行时，这也是很多人搜索"node.js官网下载openclaw"的原因——他们其实要被下载的是Node.js，不是OpenClaw。官网下载地址是nodejs.org，选LTS长期支持版，我推荐20或22，不要装带有奇数版本号（如21、23）的Current版本，因为部分原生依赖可能还没跟上。

装完验证一下：

node -v npm -v

如果你是Windows环境，装完WSL2后在WSL内执行OpenClaw安装命令，不要在Windows侧直接装：

npm install -g openclaw

如果npm装包比较慢，可以设置国内镜像：

npm config set registry https://registry.npmmirror.com

装完后先跑一次openclaw init初始化用户目录。这个命令会创建~/.openclaw/配置目录，后续所有配置都在这里。不要一上来就改全局配置，先让它生成默认文件再说。

2.3 Windows Companion到底是干嘛的，怎么配

热词里一直有"openclaw windows companion 怎么配置"，很多人被这个名词搞懵。Companion不是OpenClaw必需的服务，它是Windows下的一个桌面辅助进程，负责提供托盘图标、全局快捷键、语音唤醒、剪贴板监听这类桌面系统能力。如果你只是在终端里跑任务，不配也行；但如果你想像国内某些演示那样用语音给智能体下达指令，Companion就很有用。

以我当前的配置为例，配置写在~/.openclaw/config.yaml里：

companion: enabled: true address: "127.0.0.1:7933" features: - tray - hotkey - clipboard

Companion启动后，会在本地7933端口监听，OpenClaw主进程通过这个端口把桌面事件转发给工具层。配置好在Windows侧运行openclaw-companion，再在WSL里运行openclaw serve，两边就能握手。注意端口不要被其它程序占用，如果起不来，优先检查防火墙是不是把入站拦了。

3. Ollama本地模型接入：绕过纯API依赖

现在社区里聊OpenClaw，几乎必提Ollama。原因是Ollama把本地模型变成OpenAI兼容API的这一步太省事了，OpenClaw可以直接把它的endpoint当API填进去，但你实际上用的是自己的显卡。这个组合既保留本地部署的隐私和离线能力，又不需要为每个Agent项目单独写模型推理代码。

3.1 为什么我优先推荐Ollama而不是直接买API

对我个人来说，选择Ollama的核心理由是可预测的成本和离线能力。API按token计费，聊几轮长对话就烧掉几美分，一天调试下来看着账单肉疼；本地模型虽然前期要花时间装，但跑起来后是固定成本。更重要的是，我在调试ROS2机器人时经常要改代码、反复跑仿真，如果每次都要把控制指令传到云端再等返回，延迟和不确定性会让人崩溃。本地Ollama的响应延迟在几百毫秒级，偶尔还能完全断网工作，这个体验差别很实际。

另外一个容易忽视的点是隐私。涉及机器人控制、家目录文件扫描、剪贴板内容这类数据，绝不适合往第三方API发。OpenClaw的定位本来就是本地优先，配Ollama才算是把完整链路打通。

3.2 从拉模型到配置OpenClaw的完整步骤

在Windows上，Ollama同样推荐跑在WSL2里，不过它也有Windows原生版本。如果你后续要接ROS2，建议统一放WSL2里，省得路径冲突。

安装Ollama，Linux/WSL2下用官方脚本：

curl -fsSL https://ollama.com/install.sh | sh

拉取模型：

ollama pull qwen2.5:7b

中文场景我比较推荐Qwen系列，无论是理解中文指令还是生成中文内容，都比同量级的Llama稳定。如果想加强代码或工具调用能力，再加一个：

ollama pull llama3.1:8b

启动Ollama服务后，验证接口是否通：

curl http://localhost:11434/v1/models

能返回JSON列表就说明OpenAI兼容端点已经就绪。然后在OpenClaw配置里填：

llm: provider: openai-compatible base_url: "http://localhost:11434/v1" api_key: "ollama" model: "qwen2.5:7b"

api_key随便填一个非空字符串就行，Ollama不会校验。关键是base_url末尾的/v1不能丢，因为OpenClaw走的是OpenAI API协议路径。

3.3 混合算力：同一套配置里走本地和云端

如果你想保留云端兜底，OpenClaw是支持双模型配置的。我当前的做法是：

llm: fast: provider: openai-compatible base_url: "http://localhost:11434/v1" api_key: "ollama" model: "qwen2.5:7b" slow: provider: openai-compatible base_url: "https://api.yourprovid er.com/v1" api_key: "sk-xxxxxxxx" model: "gpt-4o-mini"

fast模型处理日常工具调用和简单问答，延迟低且免费；slow模型只在任务复杂到需要更强推理时才启用。这个方案特别适合在我这种"一半时间调试机器人、一半时间写文档"的工作流里使用，既保住速度，又保住了复杂任务的上限。社区里那个"只能用接入api的方式使用算力吗"的疑问，在这里可以明确解开：算力来源完全取决于你的配置。

4. 与ROS2 Humble和Gazebo联动：把智能体接进机器人仿真

这个部分对应热词里的"rosclaw openclaw ros2 humble gazebo"。说实话，把OpenClaw接进ROS2是我这次折腾里最有意思的一段。之前它只是个能操作电脑的Agent，接上ROS2之后，它就变成了能通过自然语言控制机器人运动的"机器人指挥官"。

4.1 rosclaw到底解决什么问题

rosclaw是OpenClaw在ROS2环境下的适配包，相当于一个把智能体的skill翻译成ROS2 action/goal的桥。为什么需要这一层？因为ROS2生态里的控制链路是基于topic、service、action的，和Agent天然不兼容。你让大模型直接发/cmd_vel几何消息它不会，但让rosclaw把"前进两米"变成标准速度指令就容易得多。

实际在Gazebo里，rosclaw的作用是把自然语言任务映射为机器人可执行的目标。例如你告诉OpenClaw"把台上第一个红色方块放到目标区域"，rosclaw会先调用感知skill获取物体位姿，再规划机械臂运动轨迹，最后通过ROS2 action把轨迹发给Gazebo里的机器人模型。整个过程你可以在终端里看到每一步的决策记录，调试时有很强的掌控感。

4.2 在Gazebo仿真里跑通一个抓取任务的配置参考

我在自己的环境里用的是ROS2 Humble + Gazebo Classic 11的组合。安装ROS2 Humble桌面版后，Gazebo会跟着装好。接着我建了一个ROS2工作空间，把rosclaw放进去编译：

mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src git clone https://github.com/your-rosclaw-repo/rosclaw.git cd ~/ros2_ws colcon build --symlink-install source install/setup.bash

colcon build --symlink-install的好处是修改Python代码后不用重新编译，符号链接直接生效，对调试特别友好。

然后启动Gazebo仿真：

ros2 launch rosclaw_demo gazebo.launch.py

另开一个终端，启动OpenClaw的skill服务：

openclaw skill serve --ros2

最后在OpenClaw交互界面发指令。这里我想提醒几个坑：

• 必须source环境变量。每次新开终端都要source /opt/ros/humble/setup.bash和source ~/ros2_ws/install/setup.bash，不然ros2和rosclaw命令都找不到。可以写进~/.bashrc省心。
• Gazebo模型路径。如果你自己导入过自定义机器人模型，记得把模型目录加进GAZEBO_MODEL_PATH环境变量，否则仿真环境加载时一片空白，你还会以为是OpenClaw坏了。
• skill描述要写明确。rosclaw要根据skill描述判断是否适合接管某个任务，如果你的skill描述写得含糊，它会拒绝调用或调用错误，这在机器人场景里比本地文件操作危险得多。

我在Gazebo里跑了大概一周，最明显的感受是：结构化任务里，本地7B模型的指令遵循能力完全够用，甚至比云端模型更稳定，因为控制指令的格式固定，模型不需要太多自由发挥空间。

5. 安卓手机上的OpenClaw：Termux部署的喜与忧

把OpenClaw装到手机上，听起来很折腾，但实际用起来确实有它的价值。我在旧安卓机上装了一台，用蓝牙或局域网连接，当临时控制面板用，比抱着电脑到处跑轻便多了。不过移动端部署有它独特的坑，尤其是Termux环境，我先给出一套可复现的步骤，再聊聊限制。

5.1 Termux安装OpenClaw的具体操作

首先在手机上装Termux，然后执行：

pkg update && pkg upgrade pkg install nodejs-lts git python

OpenClaw本体依然是npm包：

npm install -g openclaw openclaw init

如果要用到ROS2或串口等能力，Termux里还需要额外的依赖，但基础安装到此就能跑起来了。

需要拉取本地模型的话，Termux里其实很难跑，因为Ollama在Android上没有官方支持，且ARM手机算力有限。我的做法是：手机版OpenClaw不跑模型，只作为远程客户端，通过局域网连到PC或服务器上的Ollama。在配置里把base_url指到PC的局域网IP：

llm: provider: openai-compatible base_url: "http://192.168.1.100:11434/v1" api_key: "ollama" model: "qwen2.5:7b"

注意PC的Ollama服务要监听局域网地址，启动时用：

OLLAMA_HOST=0.0.0.0 ollama serve

手机和PC连同一个Wi-Fi即可。如果跨网段，还要在路由器或防火墙放行11434端口。

5.2 移动端的算力、续航与skill扩展建议

手机版OpenClaw的定位应该是轻量控制端，而不是重算力节点。电池和发热是最大的物理约束。有一次我在手机上跑了一段长任务规划，连续调用skill操作文件，不到二十分钟机身就明显发热，果断切回远程模式。

但这不代表手机版没有深度玩法。我给它配了不少skill，比如读取短信验证码（需要Termux API权限）、发送通知、查日历、控制家里网络设备。用OpenClaw的skill机制在手机上做"自然语言开关灯"这类应用非常顺手，因为Agent本身是在本机跑的，调用Termux API不需要云服务器。

另外提醒一下，Termux里大量编译C/C++依赖时会很痛苦，建议别在手机上源码编译不明包，优先用pkg仓库里的预编译版本。遇到npm包需要node-gyp编译时，先确认该包是否有ARM64的二进制，否则装到一半卡在编译上会非常难受。

6. 把OpenClaw调教顺手：Skill配置与我的最终组件清单

到这里主流程基本跑通了。最后这部分说说怎么让OpenClaw真正符合你的使用习惯，核心就是skill扩展。我认为一个Agent框架好不好用，80%取决于skill生态的丰富度和编写体验。

6.1 Skill的最小配置与编写要点

OpenClaw的skill本质上是一个带声明的脚本包。默认放在~/.openclaw/skills/下，每个skill一个目录，最少包含一个声明文件和一份可执行入口。我写了一个简单的示例目录结构：

~/.openclaw/skills/ └── my_file_sorter/ ├── skill.yaml └── run.sh

skill.yaml内容：

name: my_file_sorter version: 1.0.0 description: 按照扩展名整理指定目录下的文件，并输出整理结果。 arguments: - name: directory required: true type: string entry: run.sh

run.sh负责实现具体逻辑。然后执行：

openclaw skill reload

就能在OpenClaw的skill列表里看到它。这里有一个我踩过的坑：描述字段一定要详细写清楚触发场景。智能体靠描述判断这个skill何时该用，如果你写得太简略，比如只写"整理文件"，它可能在一次需求里根本不知道该调用它。我把描述写成"当用户要求把指定目录下的文件按扩展名分类到子目录时，使用此技能"，命中率立刻提高。

6.2 我的最终配置清单

供刚上手的人参考，我把目前稳定的环境版本和对应用途列个表：

组件	版本/选择	说明
Windows	11 23H2	WSL2体验最好，10 22H2也可
WSL2	2.0.9+	必须wsl --update到较新版本
Node.js	20 LTS	稳定，避免奇数版
OpenClaw	最新稳定版	npm全局安装
Ollama	0.3.x	WSL2内运行
本地模型	qwen2.5:7b	中文场景，指令遵循好
ROS2	Humble	配Gazebo Classic 11
手机端	Termux + Node.js LTS	作为轻量远程控制端

核心配置文件~/.openclaw/config.yaml里我会保持最简，把fast/slow双模型、Companion、skill目录写清楚即可。不要塞太多不用的配置项，每次升级版本都可能遇到默认值变化，配置越精简，迁移越轻松。

6.3 一个很容易被忽略的权限问题

最后分享一个我之前栽过跟头的细节：npm全局安装OpenClaw时，不要直接sudo npm install -g openclaw，否则后续全局模块权限混乱，require不到包时会非常痛苦。更稳的做法是设置用户级npm全局目录：

mkdir -p ~/.npm-global npm config set prefix ~/.npm-global

然后把~/.npm-global/bin加入PATH。这样所有npm包都装在自己的用户目录下，权限问题彻底消失。我在WSL和Termux里都这么配，重装系统迁移也方便，只要备份好~/.npm-global和~/.openclaw就能快速恢复。

我在实际使用中最意外的收获，是本地模型在Gazebo这类结构化环境里的表现会比纯文本任务时稳定得多。控制指令格式固定，模型不需要太多创造性发挥，7B的Qwen就应付得很好。这也让我更坚定地认为，OpenClaw这类本地优先框架，最适合的场景不是泛泛而谈的聊天，而是那些"指令边界清晰、执行路径可控、数据需要留在本地"的真实工作。如果你也在折腾部署，先把WSL2环境彻底修好，再一步步接Ollama和rosclaw，这条链路走通之后，你会得到一个真正能干活、而不是只会聊天的智能体。