折腾 Openclaw 有一阵子了最近又把项目文档里的附录 A 翻了出来。说实话这份命令速查表在我手里比 README 还常用。Openclaw 的生态不像普通软件那样装完就完事它牵涉到 ROS2、Gazebo、模型推理、远程控制这些模块命令散落在不同工具里光靠记忆很容易漏。这篇文章就围绕这份速查表展开我会把高频命令、部署思路和踩坑记录一起整理出来尽量做到你照着敲就能把环境搭起来。先说结论如果你准备在 Windows、Ubuntu 或者安卓 Termux 上部署 Openclaw这份命令速查表是绕不开的。它不光是罗列命令还把环境检查、模拟器启动、Skill 调用、模型切换这些场景串在了一起。我会结合自己的实际使用经历把速查表里最核心的部分拆开讲。1. Openclaw 到底是什么为什么需要一份命令速查表1.1 Openclaw 是什么Openclaw 是一个开源的机器人控制与智能体项目主打用自然语言和技能Skill的方式去操控机械爪、移动平台一类的硬件。它不只是一个命令行工具而是一整套运行时底层通过 ROS2 与仿真器或实体硬件通信上层负责调度模型推理、技能编排、记忆存储这些能力。我用一个不太严谨但好懂的说法你可以把 Openclaw 理解成一个“机器人中间管家”。它替你接好大模型、控制指令、传感器数据这三者的关系。用户输入一句“把红色方块抓起来”Openclaw 会把它拆成任务、选一个对应的 Skill然后通过 ROS2 发送给 Gazebo 里的仿真机械臂或者发给真实硬件。它和很多只看 API 的项目不一样Openclaw 自己有一层控制逻辑这就让命令行和配置项变得非常多。实际部署过就会知道Openclaw 对环境的依赖很杂。常见组合是 ROS2 Humble Gazebo Node.js Ollama如果放在 Windows 上还要经过 WSL2 转一层。这么多组件拼在一起出问题时根本分不清是模型没启动、ROS2 节点挂了还是命令拼错了。附录 A 的命令速查表就是干这个用的。1.2 命令速查表解决的痛点先说痛点。Openclaw 的生态里命令并不都在同一个入口。ROS2 有自己的ros2命令Gazebo 有自己的启动参数模型服务要检查 Ollama 的状态而 Openclaw 的 CLI 又负责配置、Skill、内存管理。也就是说排查一个问题可能要横跨四五个工具每个工具的日志格式还不一样。没有一张速查表新手很容易陷在“命令找不到”的泥潭里。另一个痛点是环境切换。很多人在 Windows 下用 WSL2 跑 Openclaw在 Ubuntu 上跑出来的命令未必兼容安卓上如果选 Termux路径和权限又完全是另一套逻辑。速查表把不同平台的命令分门别类我在实际部署中最大的感受就是它不是让我少敲命令而是让我知道“当前这个场景该去哪一类命令里找答案”。同时Openclaw 的 Skill 机制也是个黑盒。Skill 不是写死的代码它可能是 YAML、Python 脚本或两者混合发布和安装都要走命令行。命令速查表里如果缺少skill list、skill install这类操作你连项目里已经有哪些能力都不知道。1.3 这份速查表适合谁如果你是第一次听说 Openclaw但已经碰过 ROS2 或者 Gazebo这份速查表能帮你把已有知识迁移过来。如果你完全没接触过也没关系只要按命令顺序敲先把环境跑起来再说。附录 A 特别适合以下三类人第一类是做机器人应用开发的。他们关心怎么快速在仿真环境里验证一个抓取流程速查表里的openclaw sim start和ros2 topic list能直接帮上忙。第二类是搞模型接入的。Openclaw 支持云端 API 和本地推理两种方式速查表里有专门的 runtime 切换命令解决了“到底能不能只用本地模型”这种高频问题。第三类是维护和排障的人。Openclaw 的日志分散在 CLI、ROS2 节点和模型服务三处附录 A 里整理了一组日志查看命令我每次排查卡死问题都会先过一遍。2. 部署前的环境准备与基础命令2.1 跨平台环境差异Openclaw 不是一个“双击安装”的软件它受底层 ROS2 版本影响很大。目前最常见的组合是 ROS2 Humble 配 Gazebo 经典版Ubuntu 22.04 上是原生体验最好的平台。Windows 上做开发也完全可以但建议把 Openclaw 装进 WSL2然后在 Windows 侧用 PowerShell 去管理 WSL 状态。我在 Windows 上部署时踩过一个很典型的坑openclaw doctor一直提示“无法安全验证”某个组件。一开始以为是网络问题后来才发现是 WSL2 的内核版本太老。当时在 PowerShell 里执行wsl --status输出显示默认版本是 1而不是 WSL2。Openclaw 的 Gazebo 仿真依赖 Linux 图形栈WSL1 根本满足不了。后来我用下面两条命令修复wsl --set-default-version 2 wsl --update建议你在开始部署前先做这一步。如果你用的是安卓 Termux那是另一套环境命令包管理器是pkg和 apt 不完全兼容但核心思路一样先确认 Node.js 和 Python 版本。2.2 安装命令与版本确认Openclaw 的安装方式主要是通过官方仓库提供的安装脚本。我试过的路径有两种一种是直接拉取脚本执行另一种是下载源码后手动npm install编译。普通人建议用脚本省事。在 Ubuntu 或 WSL2 环境里一般是这样curl -fsSL https://install.openclaw.dev | bash这个地址实际以仓库 README 为准脚本会帮你把 Node.js 依赖、Openclaw 核心包和一些基础配置目录建好。装完之后先确认版本openclaw --version如果命令不存在可能是安装目录没进 PATH。不用慌检查一下~/.openclaw/bin或者/usr/local/bin是否被加到了环境变量里。另外Openclaw 的 CLI 是基于 Node.js 的所以 Node 版本太老也不行。我建议至少 Node 18 以上。可以用node -v检查如果版本不够再用nvm切换到新版nvm install 20 nvm use 20在安卓 Termux 上命令会有些不同。比如安装 Node.js 用pkg update pkg install nodejs-lts之后同样是openclaw --version验证。只要 Node 环境没问题Openclaw 就能跑起来。2.3 验证环境是否健康环境装完不等于能直接用。Openclaw 自己提供了一个环境体检命令openclaw doctor这条命令会检查 Node 版本、ROS2 是否安装、Gazebo 能否调用、模型推理服务是否响应。我第一次跑的时候它输出了一堆警告其中有一条“SL2 环境异常”其实它指的是 WSL2 状态不对。如果你遇到类似情况先回到 PowerShell 执行wsl --status确认“默认版本”是 2。如果不是就按前面说的更新。除了系统环境模型服务也要单独验证。比如你配置了 Ollama可以检查curl http://localhost:11434/api/tags能返回 JSON 列表就说明模型服务正常。这一步很关键因为 Openclaw 启动后如果发现模型连接不上会反复重试表现就是 Skill 调用卡住但日志里没有明显错误。3. 命令速查表核心分类详解3.1 初始化与配置命令Openclaw 的配置不像普通软件那样全写在配置文件里很多设置需要靠命令写入。初始化一个项目目录用的是openclaw init my-robot这会生成一个标准目录里面包含skills/、config/、memory/这类子目录。我第一次用的时候还不太理解为什么要这样设计后来才明白Openclaw 把记忆、技能和运行时配置分开是为了让同一套代码能在不同机器人上复用。配置项修改用openclaw configopenclaw config set robot.name claw-01 openclaw config set runtime.modal ollama openclaw config set runtime.endpoint http://localhost:11434这种“键值对”的写法上手很快。配置改完之后需要重启相关服务才能生效。我经常犯的一个错是改完 endpoint 不重启然后模型加载一直沿用旧配置。查看当前配置用openclaw config list它会输出一个完整的配置树包括模型名称、Skill 默认目录、日志级别这些。排查问题的时候我都习惯先跑一遍config list确认当前生效的参数和自己预期一致。3.2 仿真与硬件控制命令Openclaw 无法单独模拟机器人它需要和 Gazebo 搭配。速查表里这一组命令是我用得最多的openclaw sim start --world warehouse openclaw sim status openclaw sim stop--world参数指定仿真场景warehouse是一个带传送带和货架的典型场景适合做抓取测试。启动之后你可以用 ROS2 命令查看话题数据ros2 topic list ros2 topic echo /camera/depth/points如果你的任务是从相机点云中识别目标物体第二条命令能实时看到点云消息很有用。Openclaw 和 ROS2 之间是通过桥接节点连接的。速查表里专门列出openclaw ros bridges它会显示当前哪些 ROS2 话题被映射到 Openclaw 的内部事件流。如果bridges输出为空说明 Gazebo 虽然启动了但 Openclaw 没有订阅到任何传感器数据。这是仿真模式下最常见的故障之一。控制机械爪时可以用ros2直接发布目标位置但更推荐的方式是让 Openclaw 的 Skill 来做。底层的 ROS2 命令适合调试不适合日常操作。3.3 Skill 技能管理命令Skill 是 Openclaw 最核心的抽象。一个 Skill 就是一项可复用的能力比如“抓取红色方块”“识别条形码”“回到充电桩”。管理 Skill 的命令在速查表里占了很大篇幅。查看已安装的 Skillopenclaw skill list安装一个新的 Skillopenclaw skill install ./skills/pick-red-block.yaml这里的 YAML 文件描述了 Skill 的触发条件、执行脚本和输入输出参数。我试过自己写一个简单的 Skill发现它比想象中简单核心就是定义好“当收到什么指令时运行哪个 Python 脚本”。卸载和更新也很直接openclaw skill remove pick-red-block openclaw skill update pick-red-block更新命令会拉取最新的 Skill 定义但不影响已经保存的记忆数据。我在迭代 Skill 的时候通常不会先卸载再安装而是直接update这样能保留历史参数。需要特别提醒一点Skill 名字不能带空格和特殊字符。我第一次就踩了坑把 Skill 命名为“Pick Red Block”结果skill install一直报错改成pick-red-block就一切正常了。3.4 模型与算力切换命令很多人在部署 Openclaw 时第一个疑问就是它是不是只能用云端 API实际上不是。Openclaw 支持把推理服务切换到本地模型只要这个服务提供 OpenAI 兼容接口即可。Ollama 就是最常见的本地方案。查看当前模型配置openclaw runtime list切换算力来源openclaw runtime set --local ollama openclaw runtime set --api openai切换完之后需要重启模型服务连接。我一般会执行openclaw runtime pingping能直接告诉你当前模型服务的响应时间。如果显示超时要么是 Ollama 没启动要么是 endpoint 地址写错了。另外查看可用模型名称可以用ollama list然后通过配置指定openclaw config set model.name qwen2.5:7b这里我踩过一个坑模型名写成了qwen2.5但 Ollama 里实际标签是qwen2.5:7b导致 Openclaw 一直加载失败。所以配置模型名前务必先ollama list看清楚 Tags。4. 实操全程记录从零搭建到跑通第一个 Skill4.1 环境自检与修复会话我拿实际经历给你串一遍完整流程。假设你刚装好 Openclaw第一步不是急着初始化项目而是先运行openclaw doctor我在 Ubuntu 22.04 上跑出来的反馈是Node 版本正常ROS2 Humble 缺失Gazebo 缺失Ollama 未启动。这种输出很常见不要慌。先补 ROS2sudo apt install ros-humble-desktop source /opt/ros/humble/setup.bash再装 Gazebosudo apt install ros-humble-gazebo-ros-pkgs最后确认 Ollamasystemctl start ollama ollama serve 这三步做完再执行openclaw doctor正常情况下警告会减少。如果还有 WSL 相关提示就回到 PowerShell 处理。4.2 初始化项目并配置运行参数自检通过后我创建了一个测试项目openclaw init demo-claw cd demo-claw openclaw config set robot.name DemoClaw openclaw config set runtime.modal ollama openclaw config set model.name qwen2.5:7b openclaw config set runtime.endpoint http://localhost:11434然后执行openclaw runtime ping这里多说一句runtime.endpoint不填的话Openclaw 会默认走云端 API很多人初期没有意识到这一点。如果你希望本地推理这四项配置缺一不可。4.3 启动 Gazebo 仿真并控制机械爪项目配置好以后我是这样启动仿真的openclaw sim start --world demo_world这个命令会在 Gazebo 里加载一个带有机械臂和方块的工作台。启动过程大约需要十几秒看到“Simulation ready”字样就说明成功了。然后我打开另一个终端检查话题有没有数据ros2 topic list输出里能看到/arm_joint_controller/commands和/camera/color/image_raw这类话题存在说明传感器和控制器都注册了。接下来我手动发一条目标位置测试机械臂是否响应ros2 topic pub /arm_joint_controller/commands std_msgs/msg/Float64MultiArray data: [0.1, -0.5, 0.3, 0.0, 0.0]这里的数据是关节角度具体取决于机械臂模型。如果不响先看 Gazebo 终端有没有报错或者执行openclaw sim status确保仿真器还活着。4.4 调用 Skill 完成一次抓取演示仿真机械臂能动之后就该让 Openclaw 的 Skill 上场了。我先安装了一个现成的抓取 Skillopenclaw skill install ./skills/pick-object.yaml openclaw skill list确认 Skill 存在后启动 Openclaw 的交互入口openclaw agent start然后输入请抓取蓝色方块Openclaw 会先调用模型判断意图再匹配到pick-objectSkill最后通过 ROS2 驱动机械臂。这个链路里任意一环断了都会卡住。这时候我会打开日志openclaw log tail -f core如果日志停留在“pending skill”说明 Skill 匹配到了但执行脚本没响应如果日志显示“model timeout”问题就在模型服务上。前者查 Skill YAML 的run字段后者查 Ollama 模型是否加载完整。我第一次跑通时模型加载花了将近三十秒属于正常现象。看到机械臂把方块抓起来放到指定位置后我做的第一件事就是把配置保存好避免下次重来openclaw config list my-config-backup.txt这个小习惯能省很多重装的时间。5. 常见问题排查实录5.1 Windows 下“无法安全验证”与 WSL2 异常在 Windows 上部署 Openclaw最常见的问题就是“无法安全验证”。这句话其实很模糊Openclaw 在调用某些 Linux 侧组件时如果发现 WSL 环境不稳就会给出这个提示。排查步骤我建议这样wsl --status wsl --list --verbose第一条看默认版本第二条看具体发行版状态。如果显示Stopped就先启动wsl --distribution Ubuntu-22.04进入 Linux 之后再跑一次openclaw doctor大部分情况下重新设置 WSL 默认版本就能解决wsl --set-default-version 2 wsl --updateWindows 上还容易漏一步PowerShell 的执行策略。如果你用脚本安装时遇到“禁止运行脚本”的报错用Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个只影响本地脚本安全影响很小。5.2 Node.js 版本冲突和 Ollama 模型加载失败Openclaw 对 Node 版本有一定要求但很多系统自带的 Node 都偏老。如果安装完成后命令找不到先跑node -v低于 18 就升级。用 nvm 是最稳妥的方式。我在 Ubuntu 上遇到过另一种情况openclaw config set model.name qwen2.5:7b设置了模型名但runtime ping仍然超时。后来排查发现Ollama 服务根本没起来。可以用ollama ps查看当前加载的模型。如果没有输出就手动启动ollama serve还有一种坑是 Ollama 模型还没下载完Openclaw 就开始调用。这种情况日志里会有“connect refused”的提示。先用ollama pull qwen2.5:7b确保模型完整下载再重启 Openclaw。下载过程比较慢建议先执行再去做其他配置。5.3 Termux 部署时的权限与路径问题在安卓上部署 Openclaw用的是 Termux。它和常规 Linux 环境差异很大最关键的是存储路径。Termux 默认的家目录在/data/data/com.termux/files/home外部存储需要额外授权。安装前先执行termux-setup-storage这会弹出系统授权窗口允许 Termux 访问共享存储。如果你要加载放在手机内部的 Skill 文件路径要用/sdcard/Download/xxx.yaml或者软链接到 Termux 目录。我第一次直接读/storage/emulated/0/下面的文件时遇到了权限拒绝改成/sdcard/才正常。Termux 下安装 Openclaw 依赖pkg update pkg install nodejs-lts python gitOpenclaw 本体仍然用install.openclaw.dev的脚本装。但 Termux 的 bash 环境和标准 Linux 有些差异如果脚本报错建议改用源码安装git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm link这种方式虽然慢一点但可预测性更高。5.4 关于“只能接入 API 算力”的误区很多人在决定部署前会问Openclaw 是不是只能用接入 API 的方式使用算力如果只能接云端 API那本地机器人项目一断网就废了。实际不是这样。Openclaw 的 runtime 支持切换既可以走云端大模型 API也可以走本地推理服务。只要本地服务提供 OpenAI 兼容接口Openclaw 就能对接。Ollama 是最省事的例子openclaw runtime set --local ollama openclaw config set runtime.endpoint http://localhost:11434还有一点算力不单指大模型。机械臂的运动规划、路径生成这些计算很多是在 ROS2 层完成的不经过模型推理。所以“只用 API 算力”这个说法本身就是片面的。速查表里专门有一组runtime命令就是为了降低这种误解。6. 我实际用过之后觉得值得补充的命令与习惯6.1 被忽略的高频命令附录 A 是基础但我用久了之后发现还有几个命令值得额外记住。第一个是openclaw memory clear这个命令用来重置机器人的记忆数据。调试时如果发现 Openclaw 总是引用旧信息先清理缓存再测试。注意它会删除所有保存的历史上下文生产环境别乱用。第二个是openclaw skill export pick-object导出现有 Skill 的定义。这个在写新 Skill 时特别有用可以拿现成模板做对照。比从零写 YAML 快很多。第三个是openclaw status它只输出一行汇总信息包含当前 imulation 状态、模型是否在线、Skill 数量。虽然doctor更详细但日常启动项目我只看status。6.2 日志查看与后台调试技巧Openclaw 的日志不像单文件服务那么简单它分布在几个模块里。我常用的几个查看命令openclaw log tail -f core openclaw log tail -f ros openclaw log tail -f skill如果某个 Skill 执行失败只看 core 日志不够还必须看 skill 日志。我习惯三个终端同时开一起滚动方便对应时间戳排查顺序。使用grep过滤也很实用openclaw log tail -f core | grep -i error当日志量很大时这个技巧能过滤掉噪音。我还建议把日志级别调低在配置里设置debugopenclaw config set log.level debug调试完记得改回info否则日志文件几小时就能撑爆磁盘。6.3 给新手的三个建议第一不要一上来就接实体硬件。先用 Gazebo 仿真把命令跑熟再考虑把ros2话题接到真实机械臂上。仿真环境里出现问题至少装置不会损坏。第二模型选择先求稳。不要一开始就追求 70B 大模型先用 7B 或 13B 的量化版跑通全链路。Openclaw 对推理延迟很敏感模型太大容易超时反而不好排查问题。第三养成记录命令的习惯。Openclaw 的配置项和命令很多我建议每个人维护一份自己的“常用命令笔记”。不用很正式就是记录你跑通过哪些命令、对应的是什么环境。因为你换了机器或者重装系统后这些记录能帮你一小时恢复环境而不是重新踩坑。我个人实际使用下来的体会是Openclaw 让人又爱又恨的地方就在这它把机器人控制的门槛降低了不少但需要亲手敲的命令又很多。附录 A 速查表帮我把这些命令从“记忆负担”变成了“查阅工具”速度和稳定性都上来了。如果你部署过程中卡在哪一步别急着怀疑硬件先对照速查表跑一遍doctor、status、runtime ping八成问题都能定位出来。