OpenClaw部署避坑指南：从依赖环境到真机联调的全链路实践

说个实话，我最近被 OpenClaw 折腾得够呛。这个项目不是不好用，而是它跟你平时装的普通软件完全不是一个路子。你拿pip install一套就想跑通，八成会卡在环境上。OpenClaw 是一个把大语言模型和机器人执行链路真正连起来的开源框架，核心是让 LLM 通过 skill 去调用 ROS2、Gazebo 或者真实机械爪上的动作，而不是简单做个聊天机器人。很多人问我的第一个问题就是“照着 README 为什么还是跑不起来”，其实 80% 的问题都出在依赖版本、部署拓扑和算力配置上，跟项目本身没太大关系。这篇文章就把我实际踩过、以及身边几个群友反复问过的坑集中写一遍，希望能让你少走点弯路。

1. 先认清 OpenClaw 到底是什么

1.1 别把它当成“一个软件”，它是一套控制链路

OpenClaw 从用户视角看是一个进程，但从架构上看至少包含四层：推理端负责跑大模型，调度层负责理解用户指令并选择 skill，执行层负责跟 ROS2/Gazebo 通信，硬件抽象层负责真正操作机械爪或底盘。很多人部署失败，是因为只装了调度层，ROS2 和 Gazebo 压根没起来，或者模型配好了但 skill 目录没挂载。这就好比你给一个人装了大脑，却没给他手脚，他当然什么都干不了。

最容易出现的误判，是看到“OpenClaw 已启动”就以为万事大吉。实际上后台可能有三四个独立服务要同时在线：模型服务、Agent 主进程、ROS2 节点、仿真器。任何一个没起来，前端界面照样显示连接成功，但实际发指令就是没有任何动作。所以我建议你先把整个链路拆开理解，不要把它当成一个整体去排查。

还有一点要提醒：OpenClaw 的 skill 是核心资产。每个 skill 本质是一段可执行动作描述，比如“夹取”“放下”“移动到坐标点”，LLM 负责把自然语言映射到 skill 名称和参数上。如果你发现模型总是答非所问，先别急着换模型，去检查 skill 列表是否加载成功，以及 skill 名称是否在模型 prompt 里可见。很多“模型不听话”的情况，其实是 skill 白名单没写好。

1.2 三种典型部署拓扑，先想清楚再动手

我见过最多的一类用户，是手里正好有一台 Windows 电脑、一部安卓手机，然后想一步到位让手机控制机械臂。这种想法没有错，但你得先搞清楚 OpenClaw 的各部分分别跑在哪。

第一种是纯仿真拓扑：一台 Ubuntu 或 WSL2 环境下跑 ROS2 Humble 和 Gazebo，OpenClaw 调度层也跑在同一台机器上，模型可以用 Ollama 本地跑，也可以接云端 API。这种组合成本最低，适合验证 skill 逻辑和坐标变换，完全不碰硬件。

第二种是手机控制端加 PC 仿真/真机：安卓手机用 Termux 跑 OpenClaw 的调度层，PC 或树莓派跑 ROS2 执行层和 Gazebo。这种方案适合远程调试，但你需要额外处理局域网通信、DDS 多播、端口连通等一系列网络问题。很多人在这一步卡住，不是 OpenClaw 的问题，而是 ROS2 的 DDS 特性本来就需要一定的网络基础。

第三种是真机部署：树莓派/Jetson 上跑 ROS2 执行层，手机或云端负责推理，机械爪通过串口或 USB 连接。这个方案最刺激，但坑也最多：串口权限、电机驱动、夹爪电流、坐标系标定，每一个都能让你折腾一晚上。

我给所有人的建议是：第一次接触，不要直接上真机。先用 Gazebo 把 skill 和坐标变换跑通，再考虑接硬件。仿真环境里出错，最多重启一下；真机环境里出错，轻则电机堵转，重则把机械结构搞坏。这个顺序能救你很多钱。

2. 安装部署里最容易踩的坑：版本、依赖与环境

2.1 依赖地狱：先解决 ROS2 Humble 与 Python 的组合

OpenClaw 的文档里通常会写“依赖 ROS2 Humble、Gazebo、Python 3.10+”，但这句话背后藏着一个很大的坑：ROS2 Humble 官方只支持 Ubuntu 22.04 系列，而 Python 版本又跟系统版本强绑定。如果你在 Ubuntu 20.04 上硬装 Humble，或者把系统默认 Python 从 3.8 换成 3.10，后面会出现一堆莫名奇妙的崩溃，比如symbol not found、module has no attribute这种。

我的建议是，ROS2 部分老老实实用 apt 安装官方构建版本，不要自己源码编译。源码编译不是不行，而是时间成本太高，而且你很难确定编译出来的版本跟 OpenClaw 依赖的版本完全兼容。Python 依赖则一定要用虚拟环境，不要在系统级 pip 里直接装。你可能会觉得“我装了几个包而已”，但那些包会把系统的dist-packages搞得一团糟，等你想起来已经晚了。

还有个特别容易忽略的点：每次运行 OpenClaw 之前，必须先 source ROS2 的环境变量。很多人把source /opt/ros/humble/setup.bash写进.bashrc就以为万事大吉，但在某些桌面环境中.bashrc并不会被加载。如果你从桌面快捷方式启动，可能就跑在一个完全没有 ROS2 环境变量的 shell 里。建议在启动脚本里显式写上 source 语句，并且把printenv | grep ROS打出来确认环境确实生效。

版本选择上，我也建议不要追最新的 main 分支。OpenClaw 这种迭代快的项目，main 分支可能每天都有变动，今天能跑，明天拉一下代码就挂了。尽量用 release tag，并且在本地固定版本号，至少保证这次跑通和下次跑通的是同一套代码。

2.2 Termux 部署手机版：别把它当成小 Linux 服务器

用 Termux 在安卓上跑 OpenClaw，听起来很酷，实际上踩坑点非常密集。首先你要搞清楚，Termux 是一个用户态环境，没有 root，也没有 systemd，它跟常说的“手机上的 Linux”完全是两回事。

第一个坑是包管理器。Termux 的包管理是pkg，底层是apt，但源和路径都跟 Debian/Ubuntu 不同。如果你照着网上某些教程直接敲apt install python3，装出来的东西可能跟 Termux 的 Python 环境不是一套。正确的做法是尽量只用pkg install来安装包，不要手动混用apt。同时要记住，Termux 的 Python 路径通常在/data/data/com.termux/files/usr/bin/python，不是你想象的那种标准路径。

第二个坑是编译工具链缺失。很多 Python 包在 Termux 上没有预编译的 wheel，只能现场编译。如果你没有装binutils clang make cmake ninja rust这一套工具，安装过程会报错或者卡在编译阶段。别问我怎么知道的，我曾经为了装一个依赖，在手机屏幕上盯了二十分钟编译日志，最后发现只是缺了个rust。

第三个坑是后台进程被杀。安卓系统为了省电，会回收后台进程。OpenClaw 的调度进程在 Termux 里跑着跑着就没了，这是常态。至少你要在 Termux 里用termux-wake-lock来防止休眠，同时想办法保持前台运行或使用 Termux:Boot 这类工具让它在后台存活。如果只是随手玩一下，那无所谓；如果是要做长时间任务，这个问题会非常恼人。

还有个很多人忽略的点：不要在手机上跑 Gazebo。手机的 CPU/GPU 跑 3D 仿真基本是灾难，而且 OpenClaw 手机版通常只负责任务调度和模型对接，真正仿真应该在 PC 或远端服务器上做。手机端跟 PC 端之间需要保证同一局域网，并且 ROS2 的 DDS 端口要能互相访问。很多时候你发现手机发指令 PC 没反应，第一件事不是看逻辑，而是 ping 一下通不通、防火墙是不是把 UDP 多播给拦了。

2.3 Windows Companion 配置最容易卡壳的 5 个点

Windows 上配置 OpenClaw 的 Companion 工具，是社区里问得最多的一类问题。严格来说，Companion 只是 Windows 端的一个辅助程序，用来做配置和管理通信，但它的坑特别集中，我列几个高频的。

第一个是 WSL2 网络模式。如果你把 ROS2 和 Gazebo 跑在 WSL2 里，而 Companion 跑在 Windows 原生侧，你会发现 localhost 根本不通。WSL2 默认有独立的虚拟网络，不能直接用localhost访问。解决方式是改用镜像网络模式，或者在 WSL2 里启动服务时绑定0.0.0.0，再通过 Windows 侧查到的 WSL IP 访问。

第二个是 Gazebo 的图形显示。WSL2 里启动 Gazebo 经常黑屏或闪退，多半是 X Server 的问题。新版 WSLg 一般能直接显示 GUI，但如果用的是旧版或自定义发行版，就需要手动配置 DISPLAY 环境变量，用 VcXsrv 这类工具来转发。每次启动都要确认 DISPLAY 是否设置正确，不然你会看到一个进程起来了，但窗口死活出不来。

第三个是端口填错。Companion 里让你填的连接地址，很多用户直接填了 ROS2 的 DDS 端口或者机器人状态端口，结果连不上。其实 Companion 要连的是 OpenClaw Agent 的 HTTP/WebSocket 服务端口，不是底层通信端口。建议看启动日志里 Agent 监听的是哪个端口，再原样填进去，不要猜。

第四个是防火墙拦截。ROS2 默认的 DDS 通信使用 UDP 多播，Windows 防火墙经常会拦多播包。最直接的判断方法：如果真机上的 ROS2 节点能看到 PC，但 PC 上的 Companion 看不到真机，先关掉防火墙测试一下，确认是防火墙问题再去加放行规则。

第五个是路径问题。你把项目放在带中文或者空格的路径下，编译时 colcon 经常会出莫名其妙的路径解析错误。这不是玄学，是构建系统对路径处理不友好。项目目录尽量全英文、无空格，放二级目录以下，能省一堆事。

3. 算力选择与模型配置：API 还是本地 Ollama？

3.1 模型算力不是只有 API 一条路

很多人第一次看到 OpenClaw，第一反应是“是不是必须花钱买 API 才能跑”。其实不是。OpenClaw 的模型接口一般做成 OpenAI 兼容格式，所以既可以用云端 API，也可以在本地用 Ollama 起一个推理服务。两者只是算力来源不同，OpenClaw 并不会强制你使用某一种。

如果选云端 API，优势是响应稳定、工具调用能力强、几乎不需要考虑显存，劣势是每次调用都有成本，而且指令数据会发送到第三方服务。适合快速验证项目，或者你手里已经有现成的 API key，想先跑通整个流程。

如果选本地 Ollama，优势是数据不出本机、免费、延迟可控，劣势是硬件要求高。我实测跑 7B 级别的模型，至少要 16GB 内存，如果有独立显卡会舒服很多。14B 模型在纯 CPU 机器上也能跑，但速度会比较慢，适合对实时性要求不高的场景。

你还可以把 Ollama 跑在局域网里的另一台 PC 上，手机 Termux 里的 OpenClaw 通过 HTTP 访问它，这样手机只做调度，算力由 PC 提供。这个方案比直接在手机上跑 Ollama 靠谱得多，因为手机的性能和散热都不适合长时间跑大模型。如果你看到有人用 Termux 在手机上跑 Ollama，不是不能跑，但别期待它能带动 7B 以上的模型，顶多跑跑 3B、4B 级别的，而且发热很严重。

还有一个容易被忽略的点：无论你是用 API 还是 Ollama，都要确保模型支持 function calling/tool calling。OpenClaw 需要模型输出结构化的调用参数，而不是一段自然语言。如果你用的模型不支持工具调用，OpenClaw 会接不住输出，表现为“指令理解了但动作不出来”。所以选模型不要只看聊天效果，先确认工具调用能力。

3.2 模型参数怎么调才不出乱码

模型配置这一块，参数没调好会非常难受。我见过最典型的情况是，模型输出了正确的 skill 名，但参数全是乱写，比如让机械爪移动到x=999。这不是模型笨，而是推理温度太高，模型在“自由发挥”。

我的实测经验是，temperature一定要调低，最好控制在 0.2 以下。OpenClaw 的核心场景是执行任务，不是创意写作，你不需要它发挥想象力。如果温度太高，它会给你编出不存在的坐标和角度，导致机器人动作异常。

max_tokens也要给足。因为模型需要输出一整段 JSON，如果你的上限只有 128，它可能说到一半就被截断了，整个调用直接失败。建议至少给 512，复杂任务给到 1024。top_p可以保持在 0.8 左右，但不要跟 temperature 同时拉太高。

在系统提示词里，最好明确要求“只能输出 JSON 格式的动作指令，不要解释，不要客套”。这句话能省很多事，因为 LLM 有时候会自作主张地在 JSON 前后加一段说明文字，OpenClaw 解析时就会出错。你可以在 prompt 里放一个 skill 白名单，比如列出的所有可用 skill 名称和参数格式，让模型只从白名单里选，能明显降低幻觉率。

如果你用的是本地 Ollama，还有两个启动参数值得注意：一是OLLAMA_HOST=0.0.0.0，这样允许局域网内的设备访问，不然默认只绑定127.0.0.1，手机端根本连不上；二是OLLAMA_NUM_PARALLEL=1，减少并发请求对显存的压力，避免 OOM。调这些参数不需要改 OpenClaw 代码，只是改环境变量后重启 Ollama 服务就行。

4. 实战过程中常见的运行时报错排查

4.1 机器人不动作：先查技能调度与权限

如果 OpenClaw 已经启动、模型也正常响应，但机器人就是不动，很多人会直接怀疑硬件坏了。我建议按下面的顺序排查，不要一上来就拆机。

先看日志里有没有skill not found。如果有，多半是 skill 目录没有挂载到 Agent 能找到的路径，或者 skill 文件名跟配置里的不一致。你可以在启动参数里指定 skill 目录，但一定要用绝对路径，用相对路径经常会因为工作目录不同而找不到。

再看 topic 有没有数据。启动 OpenClaw 之前，先单独运行ros2 topic list和ros2 topic echo /相关话题，确认 Gazebo 或者真机节点已经在发布数据。如果 topic 完全不存在，说明执行层没起来。很多时候你只启动了 OpenClaw，忘了启动 Gazebo，那动作当然是空的。

还要检查服务调用失败。ROS2 里很多动作是通过 service 执行的，如果日志报Failed to call service，用ros2 service list看一下服务名是否跟 OpenClaw 配置里的一致。因为命名空间不同，/gripper和/robot/gripper是两回事，对不上就会失败。

最后提醒一个容易被忽略的硬件问题：机械爪的夹持力参数。如果 skill 里默认夹持力太大，会把物体夹碎；太小，又会滑落。这个参数不是模型能猜出来的，必须在 skill 里针对具体物体做标定。拿到新机械爪，先做几次不同夹持力的测试，找到合适阈值，再让 OpenClaw 调用。

4.2 连接失败：端口、订阅主题、坐标系

连接类问题比逻辑类问题更隐蔽，因为你看到的报错往往是“连接超时”或者“节点未发现”，但根因五花八门。

最典型的是手机 Termux 连不上 PC 上的 Ollama。很多人明明在同一个 WiFi 下，却死活连不上。你先用curl http://PC的IP:11434试试，如果 curl 都通，说明网络没问题，问题在 OpenClaw 的配置地址写错了；如果 curl 不通，多半是 Ollama 只监听了本机，需要设置OLLAMA_HOST=0.0.0.0并检查防火墙。

Companion 看不到机器人状态，也经常被归结为“软件 bug”。其实多半是话题名带命名空间的问题。OpenClaw 默认可能订阅/gripper/state，但你的 ROS2 节点发布的是/robot/gripper/state，从顶层看很像，实际上完全对不上。用ros2 topic list对比一下，比闷头查配置快得多。

真机环境下串口权限是一个大坑。Linux 下访问串口设备需要用户属于dialout组，否则会报Permission denied。你可以用sudo usermod -aG dialout $USER把自己加进去，然后重新登录。调试阶段实在不想折腾权限，也可以临时chmod 666 /dev/ttyUSB0，但这不是长期方案，重启后权限会重置。

坐标系问题是最难察觉的一类。LLM 输出的坐标往往是自然语言里的“前方 10 厘米”这种描述，但 Gazebo 里的坐标系可能是以机器人基座为原点，或者机械爪的坐标系朝向了不同的方向。如果你发现动作执行了，但位置完全不对，先检查 skill 内部有没有做坐标变换，不要直接把 LLM 输出的数字原样发给执行层。这个坑在仿真里不明显，因为 Gazebo 里物体不会损坏，但真机上就会把机构撞坏，务必重视。

4.3 避坑速查表

我把上面这些常见问题整理成一个速查表，放在这里，遇到问题可以先对照看一眼。表格不能覆盖所有情况，但能帮你快速定位大方向。

最后一个个人建议：每次改完环境，不要急着跑正式任务。先用 OpenClaw 自带的自检或诊断脚本确认依赖、topic、模型连接三个关键点都是绿的，再开始干活。我踩过太多次“表面正常、实际某个依赖挂了”的坑，自检两分钟，能省下后面两小时的排查时间。OpenClaw 这项目本身不复杂，复杂度全在链条上，把链条理顺了，它就是一台听话的机器人助手。