这几天 OpenClaw 的热度确实高得离谱GitHub 上星星涨得飞快群里的截图一张接一张。但我翻了翻大家的讨论发现一个现象真正动手部署成功的人和下载了安装包再也没打开过的人比例大概一比一。不是这项目不好用而是大部分人卡在了最基础的环境问题上还没见到安装界面就放弃了。我自己把 Windows、Linux、安卓三条路都完整跑通了踩了不少坑也把官方文档里没写清楚的部分补齐了。这篇就把保姆级流程一次性讲透从原理到实操从环境准备到避坑争取让不同基础的读者都能顺利跑起来。1. 先搞清楚 OpenClaw 到底是个什么项目很多人看到全网爆火就冲进来了但说实话连 OpenClaw 解决什么问题都没搞明白就直接部署后面大概率会碰壁。我建议先花两分钟理解这个项目的定位再动手不迟。1.1 为什么叫 OpenClaw它解决了什么痛点OpenClaw 本质上是一个可以将大模型能力接入本地工作流的执行框架。你可以把它理解成一个中间调度层—— 上层对接大模型服务下层对接你本地的脚本、Skills、工具链中间负责把自然语言指令拆解成可执行的动作。举个例子你告诉它帮我把桌面上所有 PDF 转成文字并汇总成一张表格它会自动调用相应的 Skill经过路径解析、任务规划、执行命令三个环节最后把结构化结果返回给你而不是像聊天机器人那样只给你一段建议。这正是它现在这么火的核心原因它让模型从会聊天变成了能干活。1.2 架构概览Node.js、WSL、大模型 API 三者怎么配合OpenClaw 的实际结构并不复杂理解以后排错会容易很多。整体来看它分为三层运行层基于 Node.js 构建负责进程管理、配置读取、日志输出环境层在 Windows 上依赖 WSLWindows Subsystem for Linux提供 Linux 兼容环境很多底层命令、路径解析、Shell 操作都要在 WSL 里完成算力层通过调用大模型 API比如 OpenAI、Ollama 本地模型、或者是兼容接口获取推理能力OpenClaw 本身不训练模型。这三层缺一不可。Node.js 管执行WSL 管环境API 管智能。如果你之前配过 ROS、Gazebo 这类机器人仿真环境你会发现这套认知模型几乎是通用的——OpenClaw 在各行各业项目里都有应用案例比如在 ROS2 Humble Gazebo 仿真项目中被当作调度层来串联任务脚本可以明显感觉到这套架构的设计思路在很多场景里都适用。注意OpenClaw 本身不内置任何破解或绕过大模型服务限制的能力它的角色只是把标准 API 调用变成一个本地可操作的流程。不同来源的模型服务接入方式各有差异正规使用请只接入你拥有合法权限的服务。2. 部署前的环境准备这步走错后面全是坑我在各种群里回答过很多部署问题九成以上都出在环境准备阶段。版本不对、没开虚拟化、装错发行版这些小问题会在后面安装时集中爆雷。这里把几个最容易出问题的环节一次说清。2.1 Node.js 版本怎么选官网下载为什么总有人搞错OpenClaw 对 Node.js 版本有要求务必使用 18 LTS 或 20 LTS 版本。别贪新去下载最新的奇数版本那个版本号是 Current 版部分依赖包对它的兼容性还不够理想我自己实测在新版上跑某 Skill 时出现过偶发卡死的情况换回 20 LTS 就稳定了。官网下载nodejs.org其实很直接但有一个细节特别容易坑到人进入官网首页看到 LTS 字样的大按钮直接点那是稳定版安装时一路 Next 没问题但安装完后必须重启终端否则 PATH 不刷新你敲node -v还是提示找不到命令验证方法打开终端输入node -v如果输出版本号且以v18或v20开头说明安装成功。提示千万不要手动改系统 PATH 环境变量装 Node.js 时默认选项已经写好了画蛇添足反而容易把原有的 Java、Python 相关路径搞乱。2.2 Windows 上 WSL 环境怎么装以及无法安全验证 WSL2 环境的根源网上大量报错无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status我排查了很多案例后发现根源基本是同一个WSL 内核组件缺失或版本不匹配。正确做法是打开 PowerShell管理员模式依次执行# 启用 Windows 的 WSL 功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台WSL2 必需 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑然后更新 WSL 内核 wsl --update # 查看当前状态 wsl --status如果执行完wsl --status仍然提示异常第一时间检查是否开启了Windows 虚拟机监控程序平台。在启用或关闭 Windows 功能里把VirtualMachinePlatform和Windows 虚拟机监控程序平台都勾上重启后再试。很多人在第一步就漏了后者导致 WSL2 始终无法正常启动。另外如果你是第一次使用 WSL装完内核后还需要执行# 设置默认版本 wsl --set-default-version 2之后在 Microsoft Store 里安装 Ubuntu 22.04或你自己习惯的版本首次启动会要求设置用户名和密码这个用户名和密码后面进入系统时要用牢记就好。2.3 Ollama 部署 OpenClaw 时本地模型和 API 的取舍Ollama 的用途是本地化运行模型很多教程喜欢推荐它因为它不用付费、不用公网 API至少在配置好的情况下可以完全本地化运行。但你要清醒地知道OpenClaw 对算力的要求吃得很紧本地小模型比如 7B 参数的量化版能不能撑起复杂 Skill 的执行看场景。我个人的建议是如果你的机器内存小于 16GB不要跑 7B 以上量化模型否则每次调用都会像老牛拉车如果只是简单任务写文案、格式转换Ollama 通通能搞定可玩性已经足够如果涉及网页搜索、复杂推理、多步骤工具调用老老实实接标准 API响应质量和速度都不是本地小模型能比的。配置 Ollama 时先跑ollama pull拉取模型然后确认ollama serve正常监听了11434端口最后在 OpenClaw 配置文件中把模型服务地址写成http://localhost:11434。注意OpenClaw 和 Ollama 在局域网内不同设备上互相调用时要确认模型服务有没有监听0.0.0.0默认只监听本地这个是很多人配置半天调不通的原因。3. 各平台部署实操步骤把准备环节走完后真正的安装就要开始了。这里我按平台拆分每个平台都有独立的环境特征踩过的坑也不太一样。3.1 Windows 部署流程以及 Companion 的作用Windows 的部署简单理解就是WSL Node.js OpenClaw 核心的组合。官方现在还推广一个 Windows Companion配套辅助工具作用是在 Windows 侧提供文件监听、剪贴板同步、开机自启等能力让 OpenClaw 在 Windows 上更贴近原生应用体验。大致顺序是这样装好 WSL 和 Ubuntu参考 2.2 节在 WSL 里安装 Node.js 18/20 LTS用 SSH 或直接在 VSCode 的 WSL 终端里拉取 OpenClaw 源码在项目目录执行npm install这一步会自动安装依赖复制.env.example为.env填入模型 API 的 Key运行bash install.sh完成初始化最后在 Windows 侧安装 Companion 并启动和服务建立连接。有一个细节要注意Companion 和 WSL 里的服务是通过 localhost 回环通信的。出现连不上的情况时先检查 Windows 防火墙是否拦了进程弹窗时记得点允许再检查服务端的监听地址是不是127.0.0.1而不是::1因为 Node.js 在 WSL 里有时默认解析到 IPv6 的 localhost。3.2 Linux 服务器上怎么部署最稳如果你打算长期跑我会建议直接用 Linux 服务器不折腾 WSL稳定性和资源占用都更可控。这里我用的是 Ubuntu 22.04 为例# 1. 系统更新安装 curl 和 git sudo apt update sudo apt install -y curl git build-essential # 2. 安装 Node.js 20用 nodesource 源 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 3. 验证 node -v npm -v # 4. 克隆项目 git clone [你的项目地址] cd openclaw # 5. 安装依赖 npm install # 6. 初始化配置 cp .env.example .env vim .env # 填入各类 API Key # 7. 安装并启动 bash install.sh部署在服务器上有几个容易被忽略但影响很大的细节用 systemd 管理常驻进程不要用nohup裸跑。我会写一个简单的 systemd unit 文件这样开机自动拉起、崩溃自动重启日志也能统一看防火墙只开放必要的端口比如管理面板端口模型 API 端口留在内网就好不对外暴露定期看日志journalctl -u openclaw -f是排查问题的最快路径。3.3 安卓部署Termux实际可运行的方案安卓上用 Termux 部署 OpenClaw 是很多人感兴趣的场景。实话实说手机性能有限这套方案更适合随身携带个测试环境不适合当生产节点跑重活。基础条件一台 Android 7.0 的手机Termux 从 F-Droid 或官方渠道安装不要用 Play 商店版那个版本维护滞后权限也受限内存建议 8GB 以上。操作步骤# 1. 更新源 pkg update pkg upgrade # 2. 安装必要软件 pkg install -y nodejs-lts git openssh python # 3. 获取项目 git clone [你的项目地址] openclaw cd openclaw # 4. 安装依赖这一步可能很慢建议用国内镜像 npm 源 npm install --registryhttps://registry.npmmirror.com # 5. 复制配置 cp .env.example .env vim .envTermux 版本的两点提醒省电策略要关闭很多手机上 Termux 一进后台就被系统杀掉部署的服务随之断掉需要在系统电池优化里把 Termux 设为不优化网络权限要留意Termux 首次启动时系统会弹网络权限申请千万别拒绝拒绝后 npm install 能跑但连不上远端仓库报错还很莫名其妙。我不建议用手机跑大规模自动化任务但当测试环境、临时执行简单 Skill、或者远程管理服务器时Termux 版本的 OpenClaw 已经足够用了。4. ROSClaw在 ROS2 Gazebo 环境里的进阶联动在最高频的搜索词里rosclaw openclaw ros2 humble gazebo占了很大比重。这其实不是另一个软件而是 OpenClaw 的一种应用形态—— 被集成进 ROS2 机器人项目里作为任务调度与自然语言入口有人习惯把这种联动方案称为 ROSClaw。我个人测试这套联动时最大的体会是OpenClaw 的价值不在 ROS 框架内部而在于把自然语言指令和ROS 行动指令之间的桥梁搭了起来。4.1 ROS2 Humble Gazebo 环境下如何集成前提ROS2 Humble 已经安装好并且能跑通 Gazebo 的官方示例。在此基础上集成步骤大致分成三步让 OpenClaw 能调用 ROS2 的 CLI 工具在 WSL 或 Linux 环境中确保source /opt/ros/humble/setup.bash被写入 shell 启动文件这样 OpenClaw 每次执行命令时都能找到ros2、gazebo等命令为 OpenClaw 编写 ROS2 相关的 Skill比如检查仿真世界是否启动读取机器人里程计数据发布速度指令这些 Skill 本质上就是封装了ros2 topic pub或ros2 topic echo等命令的脚本把模型 API 接入调度流程用户用自然语言说让机器人往前平移 0.5 米OpenClaw 解析语义后触发对应的 SkillSkill 内部执行ros2 topic pub /cmd_vel geometry_msgs/Twist这类操作。4.2 联动时最容易被忽视的环境变量问题把这两套系统拼在一起最常遇到的坑就是环境变量不一致。你手动在终端里测试ros2 topic list没问题但 OpenClaw 通过脚本调用时就提示找不到命令原因就是子进程没有继承 ROS 的环境变量。OpenClaw 的 Skill 执行器在启动子进程时并不会主动加载/opt/ros/humble/setup.bash所以你的 Skill 脚本里要显式 source 一下。写成这样#!/bin/bash source /opt/ros/humble/setup.bash source ~/ros2_ws/install/setup.bash ros2 topic echo /odom --once另外Gazebo 仿真环境中如果同时开了多个世界ros2 topic list的输出会带命名空间前缀Skill 里写死话题名就容易找不到。建议在 Skill 里先动态查询再执行或者用通配匹配话题名别硬编码。5. 从零到一跑通后的常见部署报错排查这一节是整篇的精华。我在群里替人排查过的所有装了没法用问题归纳起来就是下面几个。一个个过基本能解决绝大多数情况。5.1 最典型的报错链路从 WSL 到安装脚本最典型的报错链路从 WSL 到安装脚本无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status这条出现的频率最高。根据我的经验这一般意味着 WSL 的内核套件没装完整。你可以按下面的流程彻底检查一遍按Win R输入cmd回车执行wsl --status看输出了什么。如果显示默认分发版相关字样说明内核已就绪如果提示未安装支持虚拟机平台的 Windows Hypervisor这类字样回到 2.2 节检查功能开关执行wsl -l -v确认发行版版本号是 2 而不是 1如果是 1执行wsl --set-version Ubuntu-22.04 2手动转换转换过程如果卡在正在进行转换很久不动通常是虚拟机平台没开启导致的关闭多余安全软件后重启再试。node: command not found在 WSL 的 PATH 里找不到这个看着简单实际坑很多。WSL 里安装 Node.js 后如果 PATH 没有自动加载最常见的原因是安装脚本写入的路径在/etc/profile.d或~/.bashrc中冲突了。执行echo $PATH看看有没有/usr/bin如果没有说明 PATH 被覆盖了在~/.bashrc末尾追一行export PATH/usr/local/bin:$PATH再source ~/.bashrc。Error: Cannot find module 类报错这类是 npm 依赖没装好。常见原因有两个一是执行npm install时网络波动导致部分包没有完整下载删掉node_modules和package-lock.json用国内镜像源重装二是 Node.js 版本与依赖的本地原生模块不兼容把 Node 换回 LTS 版本就好了。Skill 调用后无响应如果你的环境都正常但是下发指令后 Skill 像石沉大海优先去查日志看 Skill 进程是否真正被拉起其次看是否是模型服务本身给了空响应拿 curl 直接调模型 API 试一下就知道。最容易忽略的是你部署了 Ollama也部署了 OpenClaw但OpenClaw 配置里填的模型名和 Ollama 里拉取的名字不一样一个叫llama3配置里写成llama3:8b就会静默失败。5.2 重装 OpenClaw 的正确姿势避免二次踩坑很多时候反复失败是因为旧环境没清理干净残留的配置文件和依赖会干扰新安装。第一次安装按Win R输入cmd回车确认wsl -l -v能正常看到发行版列表哪怕只有一行说明信息也行确认/etc/lsb-release或/etc/os-release里的内容可以正常读取直接在当前终端执行python3 --version只要输出版本号就表示环境已就绪切换到项目目录执行bash install.sh脚本会读取系统信息并开始安装。升级补救先备份已有配置主要是~/.openclaw/config.json和 skills 目录下载新版本安装包或更新脚本覆盖旧版本执行升级后先用openclaw doctor做环境体检它会把异常项列出来异常项逐个解决后再重启服务。从旧环境迁移拷贝整个.openclaw目录在目标机器上核对依赖版本特别是 Node.js 大版本要和旧机器一致先跑一次 dry-run 迁移测试如果官方提供了 migrate 命令的话直接跑openclaw migrate --dry-run确认无错误后正式迁移迁移完跑一遍全功能冒烟测试。5.3 部署完成后的自检查项部署完成不等于万事大吉建议按下面的清单过一遍很多问题其实在自检阶段就能发现openclaw doctor全绿才算环境健康任一 Skill 跑一次真实调用验证能返回预期结果日志里没有 ERROR 级别的异常堆栈重启 WSL 或重启机器后服务能自动拉起在另一台设备上通过局域网访问管理面板验证网络层没问题。这套检查做完基本可以确定部署是稳的。我自己现在每换一台机器部署 OpenClaw都会先跑一遍这条链路省掉了很多来回试错的功夫回头再处理真正需要动脑的问题。6. 算力接入方式的核心认知与 API 配置建议热词里有一个问题值得单独聊聊OpenClaw 只能用接入 API 的方式使用算力吗 答案是不是它支持多种算力接入方式但 API 方式最省心、最通用。6.1 本地模型、API 和混合模式的选择标准从算力来源角度OpenClaw 可分三条路线路线算力来源适合场景需要留意的地方API 线各家大模型服务的标准 API想快速上手跑通、追求稳定输出的场景需要拥有合法可用的服务权限按量计费本地线Ollama 等本地推理引擎数据敏感、离线环境、长期测试机器配置要求高小模型能力有限混合线日常用本地复杂任务切 API低成本兼顾复杂任务的综合场景配置稍复杂需要写条件路由逻辑我个人用量不大时主要用本地 7B 模型跑文本类小任务复杂流程才切 API。这样每月花不了几个钱响应速度也在可控范围内。6.2 配置 API 时的关键注意点配置 API 的坑主要集中在环境变量上OpenClaw 的.env文件里每个字段的键名必须与官方模板完全一致比如许多模型服务要求的键名是OPENAI_API_KEY或ANTHROPIC_API_KEY前后多了空格都会静默失败代理服务格式如果公司或学校网络环境下需要走代理访问模型服务HTTP_PROXY和HTTPS_PROXY需要填全只填一个会有部分请求走到直连从而超时各个大模型服务的兼容性不同如果 OpenClaw 官方没收录你使用的服务商可以试试按 OpenAI 兼容协议配置一个自定义 base URL多数情况下能通。提示切忌在公开仓库、聊天截图里暴露自己的 API Key泄露后造成的损失只能自己承担。启用使用配额与预算告警是保护自己的第一道防线。7. 从部署到用好OpenClaw 实战进阶建议当你成功部署、跑通一个 Skill 之后下一步就是如何把它用顺真正嵌入日常工作流。最后这部分说说我的深度实践经验。7.1 Skills 机制怎么玩以及如何避免把目录搞乱OpenClaw 的 Skills 机制是整个项目的灵魂。每个 Skill 本质上是一个独立目录里面有描述文件、执行脚本和依赖清单。OpenClaw 会根据描述文件来判断当前自然语言指令应该触发哪个 Skill。建议每个 Skill 一个目录内部文件尽量独立依赖的外部命令写到描述文件里注明避免别人拿到你的配置跑不起来。我自己的目录结构习惯是这样~/.openclaw/skills/ pdf-to-text/ DESCRIPTION.md run.sh web-search/ DESCRIPTION.md run.py requirements.txt >
OpenClaw 保姆级部署教程：全平台环境准备与 ROS2 集成实战
这几天 OpenClaw 的热度确实高得离谱GitHub 上星星涨得飞快群里的截图一张接一张。但我翻了翻大家的讨论发现一个现象真正动手部署成功的人和下载了安装包再也没打开过的人比例大概一比一。不是这项目不好用而是大部分人卡在了最基础的环境问题上还没见到安装界面就放弃了。我自己把 Windows、Linux、安卓三条路都完整跑通了踩了不少坑也把官方文档里没写清楚的部分补齐了。这篇就把保姆级流程一次性讲透从原理到实操从环境准备到避坑争取让不同基础的读者都能顺利跑起来。1. 先搞清楚 OpenClaw 到底是个什么项目很多人看到全网爆火就冲进来了但说实话连 OpenClaw 解决什么问题都没搞明白就直接部署后面大概率会碰壁。我建议先花两分钟理解这个项目的定位再动手不迟。1.1 为什么叫 OpenClaw它解决了什么痛点OpenClaw 本质上是一个可以将大模型能力接入本地工作流的执行框架。你可以把它理解成一个中间调度层—— 上层对接大模型服务下层对接你本地的脚本、Skills、工具链中间负责把自然语言指令拆解成可执行的动作。举个例子你告诉它帮我把桌面上所有 PDF 转成文字并汇总成一张表格它会自动调用相应的 Skill经过路径解析、任务规划、执行命令三个环节最后把结构化结果返回给你而不是像聊天机器人那样只给你一段建议。这正是它现在这么火的核心原因它让模型从会聊天变成了能干活。1.2 架构概览Node.js、WSL、大模型 API 三者怎么配合OpenClaw 的实际结构并不复杂理解以后排错会容易很多。整体来看它分为三层运行层基于 Node.js 构建负责进程管理、配置读取、日志输出环境层在 Windows 上依赖 WSLWindows Subsystem for Linux提供 Linux 兼容环境很多底层命令、路径解析、Shell 操作都要在 WSL 里完成算力层通过调用大模型 API比如 OpenAI、Ollama 本地模型、或者是兼容接口获取推理能力OpenClaw 本身不训练模型。这三层缺一不可。Node.js 管执行WSL 管环境API 管智能。如果你之前配过 ROS、Gazebo 这类机器人仿真环境你会发现这套认知模型几乎是通用的——OpenClaw 在各行各业项目里都有应用案例比如在 ROS2 Humble Gazebo 仿真项目中被当作调度层来串联任务脚本可以明显感觉到这套架构的设计思路在很多场景里都适用。注意OpenClaw 本身不内置任何破解或绕过大模型服务限制的能力它的角色只是把标准 API 调用变成一个本地可操作的流程。不同来源的模型服务接入方式各有差异正规使用请只接入你拥有合法权限的服务。2. 部署前的环境准备这步走错后面全是坑我在各种群里回答过很多部署问题九成以上都出在环境准备阶段。版本不对、没开虚拟化、装错发行版这些小问题会在后面安装时集中爆雷。这里把几个最容易出问题的环节一次说清。2.1 Node.js 版本怎么选官网下载为什么总有人搞错OpenClaw 对 Node.js 版本有要求务必使用 18 LTS 或 20 LTS 版本。别贪新去下载最新的奇数版本那个版本号是 Current 版部分依赖包对它的兼容性还不够理想我自己实测在新版上跑某 Skill 时出现过偶发卡死的情况换回 20 LTS 就稳定了。官网下载nodejs.org其实很直接但有一个细节特别容易坑到人进入官网首页看到 LTS 字样的大按钮直接点那是稳定版安装时一路 Next 没问题但安装完后必须重启终端否则 PATH 不刷新你敲node -v还是提示找不到命令验证方法打开终端输入node -v如果输出版本号且以v18或v20开头说明安装成功。提示千万不要手动改系统 PATH 环境变量装 Node.js 时默认选项已经写好了画蛇添足反而容易把原有的 Java、Python 相关路径搞乱。2.2 Windows 上 WSL 环境怎么装以及无法安全验证 WSL2 环境的根源网上大量报错无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status我排查了很多案例后发现根源基本是同一个WSL 内核组件缺失或版本不匹配。正确做法是打开 PowerShell管理员模式依次执行# 启用 Windows 的 WSL 功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台WSL2 必需 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑然后更新 WSL 内核 wsl --update # 查看当前状态 wsl --status如果执行完wsl --status仍然提示异常第一时间检查是否开启了Windows 虚拟机监控程序平台。在启用或关闭 Windows 功能里把VirtualMachinePlatform和Windows 虚拟机监控程序平台都勾上重启后再试。很多人在第一步就漏了后者导致 WSL2 始终无法正常启动。另外如果你是第一次使用 WSL装完内核后还需要执行# 设置默认版本 wsl --set-default-version 2之后在 Microsoft Store 里安装 Ubuntu 22.04或你自己习惯的版本首次启动会要求设置用户名和密码这个用户名和密码后面进入系统时要用牢记就好。2.3 Ollama 部署 OpenClaw 时本地模型和 API 的取舍Ollama 的用途是本地化运行模型很多教程喜欢推荐它因为它不用付费、不用公网 API至少在配置好的情况下可以完全本地化运行。但你要清醒地知道OpenClaw 对算力的要求吃得很紧本地小模型比如 7B 参数的量化版能不能撑起复杂 Skill 的执行看场景。我个人的建议是如果你的机器内存小于 16GB不要跑 7B 以上量化模型否则每次调用都会像老牛拉车如果只是简单任务写文案、格式转换Ollama 通通能搞定可玩性已经足够如果涉及网页搜索、复杂推理、多步骤工具调用老老实实接标准 API响应质量和速度都不是本地小模型能比的。配置 Ollama 时先跑ollama pull拉取模型然后确认ollama serve正常监听了11434端口最后在 OpenClaw 配置文件中把模型服务地址写成http://localhost:11434。注意OpenClaw 和 Ollama 在局域网内不同设备上互相调用时要确认模型服务有没有监听0.0.0.0默认只监听本地这个是很多人配置半天调不通的原因。3. 各平台部署实操步骤把准备环节走完后真正的安装就要开始了。这里我按平台拆分每个平台都有独立的环境特征踩过的坑也不太一样。3.1 Windows 部署流程以及 Companion 的作用Windows 的部署简单理解就是WSL Node.js OpenClaw 核心的组合。官方现在还推广一个 Windows Companion配套辅助工具作用是在 Windows 侧提供文件监听、剪贴板同步、开机自启等能力让 OpenClaw 在 Windows 上更贴近原生应用体验。大致顺序是这样装好 WSL 和 Ubuntu参考 2.2 节在 WSL 里安装 Node.js 18/20 LTS用 SSH 或直接在 VSCode 的 WSL 终端里拉取 OpenClaw 源码在项目目录执行npm install这一步会自动安装依赖复制.env.example为.env填入模型 API 的 Key运行bash install.sh完成初始化最后在 Windows 侧安装 Companion 并启动和服务建立连接。有一个细节要注意Companion 和 WSL 里的服务是通过 localhost 回环通信的。出现连不上的情况时先检查 Windows 防火墙是否拦了进程弹窗时记得点允许再检查服务端的监听地址是不是127.0.0.1而不是::1因为 Node.js 在 WSL 里有时默认解析到 IPv6 的 localhost。3.2 Linux 服务器上怎么部署最稳如果你打算长期跑我会建议直接用 Linux 服务器不折腾 WSL稳定性和资源占用都更可控。这里我用的是 Ubuntu 22.04 为例# 1. 系统更新安装 curl 和 git sudo apt update sudo apt install -y curl git build-essential # 2. 安装 Node.js 20用 nodesource 源 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 3. 验证 node -v npm -v # 4. 克隆项目 git clone [你的项目地址] cd openclaw # 5. 安装依赖 npm install # 6. 初始化配置 cp .env.example .env vim .env # 填入各类 API Key # 7. 安装并启动 bash install.sh部署在服务器上有几个容易被忽略但影响很大的细节用 systemd 管理常驻进程不要用nohup裸跑。我会写一个简单的 systemd unit 文件这样开机自动拉起、崩溃自动重启日志也能统一看防火墙只开放必要的端口比如管理面板端口模型 API 端口留在内网就好不对外暴露定期看日志journalctl -u openclaw -f是排查问题的最快路径。3.3 安卓部署Termux实际可运行的方案安卓上用 Termux 部署 OpenClaw 是很多人感兴趣的场景。实话实说手机性能有限这套方案更适合随身携带个测试环境不适合当生产节点跑重活。基础条件一台 Android 7.0 的手机Termux 从 F-Droid 或官方渠道安装不要用 Play 商店版那个版本维护滞后权限也受限内存建议 8GB 以上。操作步骤# 1. 更新源 pkg update pkg upgrade # 2. 安装必要软件 pkg install -y nodejs-lts git openssh python # 3. 获取项目 git clone [你的项目地址] openclaw cd openclaw # 4. 安装依赖这一步可能很慢建议用国内镜像 npm 源 npm install --registryhttps://registry.npmmirror.com # 5. 复制配置 cp .env.example .env vim .envTermux 版本的两点提醒省电策略要关闭很多手机上 Termux 一进后台就被系统杀掉部署的服务随之断掉需要在系统电池优化里把 Termux 设为不优化网络权限要留意Termux 首次启动时系统会弹网络权限申请千万别拒绝拒绝后 npm install 能跑但连不上远端仓库报错还很莫名其妙。我不建议用手机跑大规模自动化任务但当测试环境、临时执行简单 Skill、或者远程管理服务器时Termux 版本的 OpenClaw 已经足够用了。4. ROSClaw在 ROS2 Gazebo 环境里的进阶联动在最高频的搜索词里rosclaw openclaw ros2 humble gazebo占了很大比重。这其实不是另一个软件而是 OpenClaw 的一种应用形态—— 被集成进 ROS2 机器人项目里作为任务调度与自然语言入口有人习惯把这种联动方案称为 ROSClaw。我个人测试这套联动时最大的体会是OpenClaw 的价值不在 ROS 框架内部而在于把自然语言指令和ROS 行动指令之间的桥梁搭了起来。4.1 ROS2 Humble Gazebo 环境下如何集成前提ROS2 Humble 已经安装好并且能跑通 Gazebo 的官方示例。在此基础上集成步骤大致分成三步让 OpenClaw 能调用 ROS2 的 CLI 工具在 WSL 或 Linux 环境中确保source /opt/ros/humble/setup.bash被写入 shell 启动文件这样 OpenClaw 每次执行命令时都能找到ros2、gazebo等命令为 OpenClaw 编写 ROS2 相关的 Skill比如检查仿真世界是否启动读取机器人里程计数据发布速度指令这些 Skill 本质上就是封装了ros2 topic pub或ros2 topic echo等命令的脚本把模型 API 接入调度流程用户用自然语言说让机器人往前平移 0.5 米OpenClaw 解析语义后触发对应的 SkillSkill 内部执行ros2 topic pub /cmd_vel geometry_msgs/Twist这类操作。4.2 联动时最容易被忽视的环境变量问题把这两套系统拼在一起最常遇到的坑就是环境变量不一致。你手动在终端里测试ros2 topic list没问题但 OpenClaw 通过脚本调用时就提示找不到命令原因就是子进程没有继承 ROS 的环境变量。OpenClaw 的 Skill 执行器在启动子进程时并不会主动加载/opt/ros/humble/setup.bash所以你的 Skill 脚本里要显式 source 一下。写成这样#!/bin/bash source /opt/ros/humble/setup.bash source ~/ros2_ws/install/setup.bash ros2 topic echo /odom --once另外Gazebo 仿真环境中如果同时开了多个世界ros2 topic list的输出会带命名空间前缀Skill 里写死话题名就容易找不到。建议在 Skill 里先动态查询再执行或者用通配匹配话题名别硬编码。5. 从零到一跑通后的常见部署报错排查这一节是整篇的精华。我在群里替人排查过的所有装了没法用问题归纳起来就是下面几个。一个个过基本能解决绝大多数情况。5.1 最典型的报错链路从 WSL 到安装脚本最典型的报错链路从 WSL 到安装脚本无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status这条出现的频率最高。根据我的经验这一般意味着 WSL 的内核套件没装完整。你可以按下面的流程彻底检查一遍按Win R输入cmd回车执行wsl --status看输出了什么。如果显示默认分发版相关字样说明内核已就绪如果提示未安装支持虚拟机平台的 Windows Hypervisor这类字样回到 2.2 节检查功能开关执行wsl -l -v确认发行版版本号是 2 而不是 1如果是 1执行wsl --set-version Ubuntu-22.04 2手动转换转换过程如果卡在正在进行转换很久不动通常是虚拟机平台没开启导致的关闭多余安全软件后重启再试。node: command not found在 WSL 的 PATH 里找不到这个看着简单实际坑很多。WSL 里安装 Node.js 后如果 PATH 没有自动加载最常见的原因是安装脚本写入的路径在/etc/profile.d或~/.bashrc中冲突了。执行echo $PATH看看有没有/usr/bin如果没有说明 PATH 被覆盖了在~/.bashrc末尾追一行export PATH/usr/local/bin:$PATH再source ~/.bashrc。Error: Cannot find module 类报错这类是 npm 依赖没装好。常见原因有两个一是执行npm install时网络波动导致部分包没有完整下载删掉node_modules和package-lock.json用国内镜像源重装二是 Node.js 版本与依赖的本地原生模块不兼容把 Node 换回 LTS 版本就好了。Skill 调用后无响应如果你的环境都正常但是下发指令后 Skill 像石沉大海优先去查日志看 Skill 进程是否真正被拉起其次看是否是模型服务本身给了空响应拿 curl 直接调模型 API 试一下就知道。最容易忽略的是你部署了 Ollama也部署了 OpenClaw但OpenClaw 配置里填的模型名和 Ollama 里拉取的名字不一样一个叫llama3配置里写成llama3:8b就会静默失败。5.2 重装 OpenClaw 的正确姿势避免二次踩坑很多时候反复失败是因为旧环境没清理干净残留的配置文件和依赖会干扰新安装。第一次安装按Win R输入cmd回车确认wsl -l -v能正常看到发行版列表哪怕只有一行说明信息也行确认/etc/lsb-release或/etc/os-release里的内容可以正常读取直接在当前终端执行python3 --version只要输出版本号就表示环境已就绪切换到项目目录执行bash install.sh脚本会读取系统信息并开始安装。升级补救先备份已有配置主要是~/.openclaw/config.json和 skills 目录下载新版本安装包或更新脚本覆盖旧版本执行升级后先用openclaw doctor做环境体检它会把异常项列出来异常项逐个解决后再重启服务。从旧环境迁移拷贝整个.openclaw目录在目标机器上核对依赖版本特别是 Node.js 大版本要和旧机器一致先跑一次 dry-run 迁移测试如果官方提供了 migrate 命令的话直接跑openclaw migrate --dry-run确认无错误后正式迁移迁移完跑一遍全功能冒烟测试。5.3 部署完成后的自检查项部署完成不等于万事大吉建议按下面的清单过一遍很多问题其实在自检阶段就能发现openclaw doctor全绿才算环境健康任一 Skill 跑一次真实调用验证能返回预期结果日志里没有 ERROR 级别的异常堆栈重启 WSL 或重启机器后服务能自动拉起在另一台设备上通过局域网访问管理面板验证网络层没问题。这套检查做完基本可以确定部署是稳的。我自己现在每换一台机器部署 OpenClaw都会先跑一遍这条链路省掉了很多来回试错的功夫回头再处理真正需要动脑的问题。6. 算力接入方式的核心认知与 API 配置建议热词里有一个问题值得单独聊聊OpenClaw 只能用接入 API 的方式使用算力吗 答案是不是它支持多种算力接入方式但 API 方式最省心、最通用。6.1 本地模型、API 和混合模式的选择标准从算力来源角度OpenClaw 可分三条路线路线算力来源适合场景需要留意的地方API 线各家大模型服务的标准 API想快速上手跑通、追求稳定输出的场景需要拥有合法可用的服务权限按量计费本地线Ollama 等本地推理引擎数据敏感、离线环境、长期测试机器配置要求高小模型能力有限混合线日常用本地复杂任务切 API低成本兼顾复杂任务的综合场景配置稍复杂需要写条件路由逻辑我个人用量不大时主要用本地 7B 模型跑文本类小任务复杂流程才切 API。这样每月花不了几个钱响应速度也在可控范围内。6.2 配置 API 时的关键注意点配置 API 的坑主要集中在环境变量上OpenClaw 的.env文件里每个字段的键名必须与官方模板完全一致比如许多模型服务要求的键名是OPENAI_API_KEY或ANTHROPIC_API_KEY前后多了空格都会静默失败代理服务格式如果公司或学校网络环境下需要走代理访问模型服务HTTP_PROXY和HTTPS_PROXY需要填全只填一个会有部分请求走到直连从而超时各个大模型服务的兼容性不同如果 OpenClaw 官方没收录你使用的服务商可以试试按 OpenAI 兼容协议配置一个自定义 base URL多数情况下能通。提示切忌在公开仓库、聊天截图里暴露自己的 API Key泄露后造成的损失只能自己承担。启用使用配额与预算告警是保护自己的第一道防线。7. 从部署到用好OpenClaw 实战进阶建议当你成功部署、跑通一个 Skill 之后下一步就是如何把它用顺真正嵌入日常工作流。最后这部分说说我的深度实践经验。7.1 Skills 机制怎么玩以及如何避免把目录搞乱OpenClaw 的 Skills 机制是整个项目的灵魂。每个 Skill 本质上是一个独立目录里面有描述文件、执行脚本和依赖清单。OpenClaw 会根据描述文件来判断当前自然语言指令应该触发哪个 Skill。建议每个 Skill 一个目录内部文件尽量独立依赖的外部命令写到描述文件里注明避免别人拿到你的配置跑不起来。我自己的目录结构习惯是这样~/.openclaw/skills/ pdf-to-text/ DESCRIPTION.md run.sh web-search/ DESCRIPTION.md run.py requirements.txt >