1. 先搞清楚 OpenClaw 是什么再决定要不要入坑说实话我一开始以为 openclaw 只是某个编码助手的开源替代品结果把它完整部署一遍之后才发现这东西的野心比我想象中大得多。openclaw 是一个自托管的个人 AI 助手框架核心用 Node.js 编写可以灵活接入不同模型后端——云端 API 能接本地 Ollama 也能接还能通过 skill 技能机制扩展工具调用能力Windows、macOS、Linux、甚至 AndroidTermux都有对应的部署方式。我决定部署它是因为不想把日常的 AI 使用绑在某个单一产品上。openclaw 允许我自己控制运行环境、自己选模型、自己写技能还内置了会话管理、任务调度和多端 companion 联动。听起来非常理想对吧现实是我从 clone 仓库到打通第一次对话花了一个周末加两个晚上中间有好几次想摔键盘。这篇文章不是官方教程而是我把坑踩完之后的复盘记录。内容涵盖 Windows WSL2、macOS 以及 Android Termux 三种环境下部署 openclaw 的完整经历重点讲文档没写清楚、但新手几乎一定会撞上的问题。如果你正准备部署或者已经卡在某个报错上这篇应该能帮你省下大量时间。1.1 它的定位是干活不是聊天openclaw 的核心价值在于它是个个人助手而不是聊天机器人。聊天机器人是你问一句、它答一句openclaw 的玩法是你给它一个任务描述它会自己拆解任务、调用合适的技能、操作外部工具再把结果拿回来给你。这个思路跟编码助手类似但它不限制在代码场景任何能被定义成技能的事情都可以接进去。skill 技能机制是它最值得玩的部分。每个技能本质上是一组指令、参数描述和可执行工具的组合openclaw 会根据任务内容自动判断该调用哪个技能。你可以给它配定时提醒、网页信息整理、本地文件检索甚至对接 ROS2 机器人控制。模型负责理解任务和调度技能技能负责真正落地执行这个分层设计是它和普通聊天工具最大的区别。1.2 哪种人值得折腾它如果你符合下面任何一条openclaw 都值得一试想自托管 AI 助手、不希望所有数据都过云端有性能足够的机器想用 Ollama 跑本地模型喜欢折腾工具链不介意在 Node.js、WSL2、Termux 之间来回切换做 ROS2 机器人开发想让 AI 参与设备控制或者单纯就是想把自己的电脑变成一个带 AI 助理的操作系统。反过来如果你只想要一个开箱即用的聊天窗口openclaw 目前真的不适合你。它的配置自由度很高代价就是默认状态下远没有商业产品那么省心。这个项目更适合愿意花一两个小时把环境理顺、并且能接受自己动手查日志的人。2. 环境部署的连环坑Node.js、WSL2 和 PowerShell2.1 第一个坑Node.js 版本不是装上就行openclaw 整个框架跑在 Node.js 上所以环境准备的第一件事就是装 Node.js。官方文档通常只会写一句要求 Node.js 18 以上但实际上版本的影响远不止能不能跑这么简单。我当时图省事用系统自带的包管理器装了一个比较旧的 Node.js结果跑 npm install 时报了一堆错什么 engine 不兼容、node-gyp 编译失败看起来像是依赖问题实际排查半天才发现就是运行时版本太旧。后来我换成 Node.js 20 LTS同样的命令一次通过。这里有个很多人容易混淆的点openclaw 并不是从 Node.js 官网下载的Node.js 官网只提供 Node.js 运行时本身openclaw 的代码要从它自己的 GitHub 仓库 clone。所以正确的顺序是先从 nodejs.org 或 nvm 装好 LTS 版 Node.js确认 node -v 版本无误再去拉取 openclaw 仓库执行安装。实操上我的建议是不要用系统包管理器自带的旧版本优先用 nvm 管理 Node.js 版本装最新 LTS如果之前装过旧版本安装依赖前先执行 npm cache clean --force 清掉缓存再重新跑 npm install。另外最好瞄一眼 openclaw 仓库 package.json 里的 engines 字段那才是这个版本真正声明支持的 Node.js 范围。2.2 第二个坑Windows 上无法安全验证 WSL2 环境这是我在整个部署过程中遇到的最离谱的报错。在 Windows 上走 WSL2 路线部署时openclaw 的检测脚本会校验 WSL2 环境是否健康一旦校验不过就会弹出类似openclaw 无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status 解决报告的问题的提示。我第一反应是检查 WSL 本身结果 wsl --status 显示一切正常版本也对内核也对为什么还是验证不过排查到最后发现问题往往是几个因素叠加造成的。最常见的是 WSL 内核版本偏旧Windows 自动安装的 WSL 组件不一定是最新的其次是机器上装了多个 Linux 发行版但没有设置默认发行版校验脚本不知道该检查哪个环境还有一种是系统太老某些系统组件缺失导致脚本误判。这三个原因都会触发同一个看似莫名其妙的报错。解决思路不复杂在 PowerShell 里按顺序执行这几条命令wsl --status wsl --update wsl -l -v wsl --set-default Ubuntu-22.04先看状态再更新内核然后列出已安装的发行版把你要用的那个设为默认。跑完这些重启终端再重新触发 openclaw 的安装校验报错基本就消失了。如果 wsl --update 提示已经是最新但问题依旧建议检查 Windows 功能里适用于 Linux 的 Windows 子系统和虚拟机平台两个可选功能是否都勾选启用改完需要重启系统。2.3 第三个坑PowerShell 执行策略这个坑很小但特别容易让人暴躁。在 PowerShell 里执行 openclaw 自带的某些辅助脚本时系统直接弹红字说无法加载配置文件因为在此系统上禁止运行脚本。原因是 Windows 默认的 PowerShell 执行策略是 Restricted只允许运行受签名保护的脚本而 openclaw 的脚本显然不在白名单里。解决办法是用管理员权限的 PowerShell 改一下执行策略我建议使用 RemoteSigned 而不是 UnrestrictedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned 的含义是本地创建的脚本可以运行从互联网下载的未签名脚本会被拦截。这样既解决了 openclaw 脚本运行的问题又不会把安全策略完全放开。改完之后用 Get-ExecutionPolicy 确认一下生效即可。2.4 相对稳的 Windows 部署顺序经过两轮踩坑我总结出一套不太容易出问题的 Windows 部署顺序。第一步先把系统更新到较新的正式版本装好 Windows Terminal操作起来舒服很多。第二步安装 WSL2设置默认发行版为 Ubuntu 22.04 或 24.04执行 wsl --update 把内核更新到最新。第三步在 WSL 里用 nvm 装 Node.js 20 LTS。第四步 clone openclaw 仓库执行 npm install。第五步配置模型后端Ollama 或 API 密钥二选一。第六步启动服务再根据需要接 Windows Companion。这里有个容易被忽略的判断openclaw 在 Windows 上其实有两条路线一条是 WSL2 环境里跑服务另一条是 Windows 原生跑 Windows Companion 联动。如果只是想在桌面上快速体验原生方式更省心如果打算把它当成常驻服务来用再考虑 WSL2。不要一上来就追求最复杂的部署方式先让最简单的链路跑通再逐层加东西这是我在所有折腾里最深刻的教训。3. 模型接入Ollama 本地模型到底行不行3.1 只能用 API 方式使用算力吗——答案是否定的搜索 openclaw 相关内容时出现频率特别高的一个问题就是openclaw 只能用接入 API 的方式使用算力吗。我先给结论不是。openclaw 的模型后端是可配置的官方支持多种接入方式包括 OpenAI 兼容接口、Anthropic API以及本地模型服务。Ollama 恰好提供 OpenAI 兼容接口所以Ollama openclaw是完全可行的组合这也是很多人在本地部署时的首选方案。但有个差异必须说清楚API 方式和本地模型方式在 openclaw 里的体验差别不只是快慢两个字那么简单。云端 API 模型的能力更强在工具调用、技能触发这类关键能力上明显更稳本地小模型比如 7B 参数级别在复杂任务上很容易出现该触发技能时不触发、工具参数传错这类问题。如果你是本地模型路线参数量建议至少 14B量化级别也别太激进否则 openclaw 的 skill 机制会变得不太可靠。3.2 Ollama 接入 openclaw 的具体步骤我的参考环境是 Ubuntu 22.04WSL2 Ollama 14B 量级模型。Ollama 安装完成后默认监听在 127.0.0.1:11434并且自带 OpenAI 兼容接口路径是 /v1。openclaw 这一侧需要把模型提供方配置成 openai-compatible 模式并指定 base_url 指向 Ollama。核心配置项大致是这样model: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 model_name: qwen2.5:14b-instruct api_key: ollamaOllama 本身不校验 API Key但这个字段在兼容接口里是必填的随便填一个占位符就行。配置完成后重启 openclaw 服务用一条简单指令验证链路是否通畅openclaw chat 你好帮我确认模型连接是否正常能正常回复说明链路已经通了。如果返回网络错误或超时优先排查三件事Ollama 进程是否在跑、11434 端口是否被占用、base_url 是否写错。我见过太多人把 127.0.0.1:11434 写成其他端口或者漏掉 /v1 路径结果卡在连不上上很久。3.3 混合方案的实战心得折腾到现在我自己用的是本地模型扛日常 API 模型跑重活的混合模式。日常的简单问答、信息整理、定时任务全部走 Ollama 本地模型响应快、免费、数据不出本机遇到需要深度推理、长篇写作、复杂任务拆解的场景再切到 API 模型。这样既保住了日常使用的响应体验又不会在关键任务上被模型能力拖后腿。这个方案唯一要注意的是切换成本。openclaw 切换模型提供方一般需要改配置并重启服务所以最好提前规划好两套配置需要切换时直接替换而不是临时去查文档。另外如果你是在 WSL2 里跑 Ollama而 openclaw 跑在 Windows 原生端两者之间的网络互通取决于 WSL 的网络模式。最省事的做法是让 openclaw 和 Ollama 跑在同一个环境里别跨环境做网络互访能减少大量莫名其妙的连接问题。3.4 本地模型的选择建议如果你决定走本地模型路线我踩过的坑是别贪便宜用小模型。openclaw 的技能调度非常依赖模型的指令跟随能力和工具调用能力参数太小的模型经常把技能参数理解错轻则任务失败重则产生错误操作。以目前主流开源模型来看14B 算是及格线有条件上 32B 或更大参数的模型效果会明显更好但硬件要求也随之上升。量化方面纯 CPU 跑建议用 Q4/Q5 量化级别有显卡就优先用 GPU 推理量化可以适当放宽到 Q6兼顾速度和效果。模型选择上指令跟随能力强的中文模型比如 qwen 系列在 openclaw 这类工具调度场景下表现会比较稳可以在 Ollama 的模型库里直接拉取对应版本测试。4. 移动端、Windows Companion 和 ROS2 扩展的坑4.1 Termux 安装 openclaw 手机版手机上部署 openclaw 的需求其实很实际人不在电脑前但还是希望 AI 助手能响应、能执行一些任务。openclaw 的移动端方向是 companion 应用但很多 Android 用户实际走的是 Termux 路线直接让 openclaw 跑在 Termux 这个终端环境里。Termux 部署的思路跟 Linux 一致但有三个特殊点值得注意。第一Termux 默认源里的 Node.js 可能不是最新建议先执行 pkg upgrade 再安装 nodejs-lts第二Android 系统会回收后台进程需要安装并启用 termux-wake-lock否则 openclaw 服务跑一会儿就被系统杀掉第三它的部分依赖需要本地编译Termux 里要装 binutils、python 等编译工具链不然 npm install 会卡在编译环节。大致流程是这样的pkg update pkg upgrade pkg install nodejs-lts binutils python termux-wake-lock termux-wake-lock git clone openclaw 仓库地址 cd openclaw npm install node openclaw.js start实测下来手机端跑 openclaw 是能用的但短板很明显如果模型也接本地 Ollama手机还得再跑一个 Ollama 服务对性能和续航都是不小的考验。我的建议是手机上优先走 API 模式或者让手机连接局域网内电脑上的 Ollama 服务而不是在手机本地跑模型。4.2 Windows Companion 配置要点Windows Companion 是 openclaw 在 Windows 桌面端的配套组件作用是把桌面环境的能力暴露给助手比如文件操作、剪贴板、屏幕信息获取等。配置时最容易出问题的点集中在认证和权限上。Companion 启动后一般会生成配对令牌或二维码需要在 openclaw 主服务确认配对。我遇到最多的情况是 Companion 启动正常但主服务一直显示未连接。排查方向就三件事第一主服务端口和 Companion 端口是否一致很多连不上就是端口对不上第二Windows 防火墙是否放行了对应端口没放行就会被静默拦截第三配对令牌是否过期令牌有效期通常很短过期就重新生成一次。这三项逐一确认过绝大多数连接问题都能解决。另外要强调一点Windows Companion 涉及桌面级权限建议只在可信的局域网环境里使用不要图方便把它暴露到公网。4.3 ROSClawROS2 Humble 和 Gazebo 的折腾openclaw 相关热度最高的扩展方向之一是跟 ROS2 机器人操作系统结合也就是 rosclaw 这套东西。它的思路是让 AI 助手通过 ROS2 的话题机制观察和控制机器人配合 Gazebo 仿真环境可以在没有实体机器人的情况下做验证。我虽然没有在真实机器人上用过 rosclaw但在 ROS2 Humble Gazebo 的仿真环境里完整走通过一遍。整体感受是想法很吸引人但配置复杂度比纯 openclaw 高一个量级。难点主要在两方面一是 ROS2 环境本身的依赖非常重Humble 版本需要装一整套工具链Gazebo 也要单独装任何一个环节版本不匹配都会出问题二是 openclaw 和 ROS2 的桥接层需要把 ROS2 消息转成模型能理解的文本描述话题列表和消息映射规则都要认真配置配不好就会出现看似连上了但一问三不知的情况。想折腾 rosclaw 的话我的建议是先想清楚目的。如果是为了学习 ROS2 和 AI 的结合方式仿真环境足够了如果是为了实际任务至少要先明确助手要控制哪些话题、读取哪些话题再动手配置桥接不要上来就把整个功能全量开启。4.4 多端协同怎么安排电脑、手机、Companion 都跑起来之后多端协同又成了新的坑。openclaw 的多端设计里会话同步和状态一致是两个核心诉求但实际用下来多端同步并不是无脑自动完成的。我的经验是不要把多端部署当成默认需求一个人用的话一台电脑加一个手机 companion 基本就够了。如果硬要三端同时跑就要接受会话历史不一致的现实并且养成关键任务只在主端执行的习惯。更现实的建议是先想清楚每一端分别承担什么职责电脑端跑重活手机端做轻量询问Companion 只负责桌面联动。职责分开之后多端协同的复杂度会下降很多冲突也少。5. 常见问题速查与排坑思路实录5.1 高频问题速查表把我在部署 openclaw 过程中遇到的和帮别人排查过的高频问题整理成一张表方便你直接对照。问题现象可能原因解决动作npm install 报 engine 错误Node.js 版本太旧升级到 20 LTS清缓存重装依赖Windows 提示无法安全验证 WSL2WSL 内核旧或默认发行版未设置wsl --updatewsl --set-defaultPowerShell 禁止运行脚本执行策略为 Restricted设为 RemoteSigned服务启动后模型请求超时Ollama 未启动或 base_url 写错确认 Ollama 进程和 11434 端口配置本地模型技能经常不触发模型参数量太小换 14B 及以上模型调整量化级别Companion 一直未连接端口不一致、防火墙拦截或令牌过期逐项确认端口、放行规则、重新生成令牌Termux 服务运行一段时间被杀未启用 wake-lock安装执行 termux-wake-lock这张表解决的是现象对应动作的问题但真正定位问题的时候还是需要一套系统的排查思路。5.2 三个容易被忽略的细节第一个是 .env 文件。openclaw 的很多配置除了写在主配置文件里还支持通过环境变量覆盖尤其是 API Key、日志级别、监听端口这些。如果你改了配置但服务没生效先看看是不是环境变量的优先级把配置文件覆盖了这个问题伪装成配置没改对最容易误导人。第二个是日志级别。openclaw 的日志信息量很大但默认级别可能只显示 info。遇到疑难杂症先把日志级别调到 debug 再复现问题。很多看起来究极离谱的报错其实在 debug 日志里就一行小字说清楚了只是默认日志级别把它藏起来了。第三个是版本锁定。openclaw 迭代速度不慢如果你部署的是某个特定版本建议锁定版本号或者定期同步更新。我看到过不少更新完依赖之后服务起不来的问题基本都是版本错位导致的回退到之前能用的版本验证一下往往立刻真相大白。5.3 一套通用的排错流程最后分享一套我排 openclaw 各种问题都会走的流程。第一步先分端问题出在 openclaw 主服务、模型后端还是 companion 端第二步再分级是配置问题、环境问题还是代码 bug第三步看日志把日志调到 debug复现一次看最后一条报错第四步二分定位如果是链路问题用 curl 直接测模型接口用端口检查工具测端口一步步缩小范围第五步回退版本如果更新后出问题优先怀疑版本兼容性。这套流程听起来不花哨但实测比凭感觉乱试高效得多。尤其是遇到那些报错信息完全看不懂的情况时先冷静按流程走一遍十次有八次能定位到真正原因。6. 最后说几句实在话踩完这一圈坑我最大的体会是openclaw 的能力上限对得起它的折腾成本但前提是你对它所依赖的生态有一定熟悉度。Node.js、WSL2、Ollama、ROS2这些词看着吓人实际拆开看每一项都不难难的是它们拼在一起时的组合问题。如果你是完全的新手我的建议是第一次部署就选最简单的单机方案一台 Ubuntu 系统或者 WSL2 环境用 Ollama 接一个 14B 模型先把对话打通再考虑手机端和 ROS 扩展。别一上来就照搬全家桶教程先把最核心的链路跑顺再逐步加功能。这个顺序能帮你少生很多气也能让你真正把 openclaw 用起来而不是一直停在部署中。
OpenClaw自托管AI助手部署全指南：从WSL2到Ollama的排坑实录
1. 先搞清楚 OpenClaw 是什么再决定要不要入坑说实话我一开始以为 openclaw 只是某个编码助手的开源替代品结果把它完整部署一遍之后才发现这东西的野心比我想象中大得多。openclaw 是一个自托管的个人 AI 助手框架核心用 Node.js 编写可以灵活接入不同模型后端——云端 API 能接本地 Ollama 也能接还能通过 skill 技能机制扩展工具调用能力Windows、macOS、Linux、甚至 AndroidTermux都有对应的部署方式。我决定部署它是因为不想把日常的 AI 使用绑在某个单一产品上。openclaw 允许我自己控制运行环境、自己选模型、自己写技能还内置了会话管理、任务调度和多端 companion 联动。听起来非常理想对吧现实是我从 clone 仓库到打通第一次对话花了一个周末加两个晚上中间有好几次想摔键盘。这篇文章不是官方教程而是我把坑踩完之后的复盘记录。内容涵盖 Windows WSL2、macOS 以及 Android Termux 三种环境下部署 openclaw 的完整经历重点讲文档没写清楚、但新手几乎一定会撞上的问题。如果你正准备部署或者已经卡在某个报错上这篇应该能帮你省下大量时间。1.1 它的定位是干活不是聊天openclaw 的核心价值在于它是个个人助手而不是聊天机器人。聊天机器人是你问一句、它答一句openclaw 的玩法是你给它一个任务描述它会自己拆解任务、调用合适的技能、操作外部工具再把结果拿回来给你。这个思路跟编码助手类似但它不限制在代码场景任何能被定义成技能的事情都可以接进去。skill 技能机制是它最值得玩的部分。每个技能本质上是一组指令、参数描述和可执行工具的组合openclaw 会根据任务内容自动判断该调用哪个技能。你可以给它配定时提醒、网页信息整理、本地文件检索甚至对接 ROS2 机器人控制。模型负责理解任务和调度技能技能负责真正落地执行这个分层设计是它和普通聊天工具最大的区别。1.2 哪种人值得折腾它如果你符合下面任何一条openclaw 都值得一试想自托管 AI 助手、不希望所有数据都过云端有性能足够的机器想用 Ollama 跑本地模型喜欢折腾工具链不介意在 Node.js、WSL2、Termux 之间来回切换做 ROS2 机器人开发想让 AI 参与设备控制或者单纯就是想把自己的电脑变成一个带 AI 助理的操作系统。反过来如果你只想要一个开箱即用的聊天窗口openclaw 目前真的不适合你。它的配置自由度很高代价就是默认状态下远没有商业产品那么省心。这个项目更适合愿意花一两个小时把环境理顺、并且能接受自己动手查日志的人。2. 环境部署的连环坑Node.js、WSL2 和 PowerShell2.1 第一个坑Node.js 版本不是装上就行openclaw 整个框架跑在 Node.js 上所以环境准备的第一件事就是装 Node.js。官方文档通常只会写一句要求 Node.js 18 以上但实际上版本的影响远不止能不能跑这么简单。我当时图省事用系统自带的包管理器装了一个比较旧的 Node.js结果跑 npm install 时报了一堆错什么 engine 不兼容、node-gyp 编译失败看起来像是依赖问题实际排查半天才发现就是运行时版本太旧。后来我换成 Node.js 20 LTS同样的命令一次通过。这里有个很多人容易混淆的点openclaw 并不是从 Node.js 官网下载的Node.js 官网只提供 Node.js 运行时本身openclaw 的代码要从它自己的 GitHub 仓库 clone。所以正确的顺序是先从 nodejs.org 或 nvm 装好 LTS 版 Node.js确认 node -v 版本无误再去拉取 openclaw 仓库执行安装。实操上我的建议是不要用系统包管理器自带的旧版本优先用 nvm 管理 Node.js 版本装最新 LTS如果之前装过旧版本安装依赖前先执行 npm cache clean --force 清掉缓存再重新跑 npm install。另外最好瞄一眼 openclaw 仓库 package.json 里的 engines 字段那才是这个版本真正声明支持的 Node.js 范围。2.2 第二个坑Windows 上无法安全验证 WSL2 环境这是我在整个部署过程中遇到的最离谱的报错。在 Windows 上走 WSL2 路线部署时openclaw 的检测脚本会校验 WSL2 环境是否健康一旦校验不过就会弹出类似openclaw 无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status 解决报告的问题的提示。我第一反应是检查 WSL 本身结果 wsl --status 显示一切正常版本也对内核也对为什么还是验证不过排查到最后发现问题往往是几个因素叠加造成的。最常见的是 WSL 内核版本偏旧Windows 自动安装的 WSL 组件不一定是最新的其次是机器上装了多个 Linux 发行版但没有设置默认发行版校验脚本不知道该检查哪个环境还有一种是系统太老某些系统组件缺失导致脚本误判。这三个原因都会触发同一个看似莫名其妙的报错。解决思路不复杂在 PowerShell 里按顺序执行这几条命令wsl --status wsl --update wsl -l -v wsl --set-default Ubuntu-22.04先看状态再更新内核然后列出已安装的发行版把你要用的那个设为默认。跑完这些重启终端再重新触发 openclaw 的安装校验报错基本就消失了。如果 wsl --update 提示已经是最新但问题依旧建议检查 Windows 功能里适用于 Linux 的 Windows 子系统和虚拟机平台两个可选功能是否都勾选启用改完需要重启系统。2.3 第三个坑PowerShell 执行策略这个坑很小但特别容易让人暴躁。在 PowerShell 里执行 openclaw 自带的某些辅助脚本时系统直接弹红字说无法加载配置文件因为在此系统上禁止运行脚本。原因是 Windows 默认的 PowerShell 执行策略是 Restricted只允许运行受签名保护的脚本而 openclaw 的脚本显然不在白名单里。解决办法是用管理员权限的 PowerShell 改一下执行策略我建议使用 RemoteSigned 而不是 UnrestrictedSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned 的含义是本地创建的脚本可以运行从互联网下载的未签名脚本会被拦截。这样既解决了 openclaw 脚本运行的问题又不会把安全策略完全放开。改完之后用 Get-ExecutionPolicy 确认一下生效即可。2.4 相对稳的 Windows 部署顺序经过两轮踩坑我总结出一套不太容易出问题的 Windows 部署顺序。第一步先把系统更新到较新的正式版本装好 Windows Terminal操作起来舒服很多。第二步安装 WSL2设置默认发行版为 Ubuntu 22.04 或 24.04执行 wsl --update 把内核更新到最新。第三步在 WSL 里用 nvm 装 Node.js 20 LTS。第四步 clone openclaw 仓库执行 npm install。第五步配置模型后端Ollama 或 API 密钥二选一。第六步启动服务再根据需要接 Windows Companion。这里有个容易被忽略的判断openclaw 在 Windows 上其实有两条路线一条是 WSL2 环境里跑服务另一条是 Windows 原生跑 Windows Companion 联动。如果只是想在桌面上快速体验原生方式更省心如果打算把它当成常驻服务来用再考虑 WSL2。不要一上来就追求最复杂的部署方式先让最简单的链路跑通再逐层加东西这是我在所有折腾里最深刻的教训。3. 模型接入Ollama 本地模型到底行不行3.1 只能用 API 方式使用算力吗——答案是否定的搜索 openclaw 相关内容时出现频率特别高的一个问题就是openclaw 只能用接入 API 的方式使用算力吗。我先给结论不是。openclaw 的模型后端是可配置的官方支持多种接入方式包括 OpenAI 兼容接口、Anthropic API以及本地模型服务。Ollama 恰好提供 OpenAI 兼容接口所以Ollama openclaw是完全可行的组合这也是很多人在本地部署时的首选方案。但有个差异必须说清楚API 方式和本地模型方式在 openclaw 里的体验差别不只是快慢两个字那么简单。云端 API 模型的能力更强在工具调用、技能触发这类关键能力上明显更稳本地小模型比如 7B 参数级别在复杂任务上很容易出现该触发技能时不触发、工具参数传错这类问题。如果你是本地模型路线参数量建议至少 14B量化级别也别太激进否则 openclaw 的 skill 机制会变得不太可靠。3.2 Ollama 接入 openclaw 的具体步骤我的参考环境是 Ubuntu 22.04WSL2 Ollama 14B 量级模型。Ollama 安装完成后默认监听在 127.0.0.1:11434并且自带 OpenAI 兼容接口路径是 /v1。openclaw 这一侧需要把模型提供方配置成 openai-compatible 模式并指定 base_url 指向 Ollama。核心配置项大致是这样model: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 model_name: qwen2.5:14b-instruct api_key: ollamaOllama 本身不校验 API Key但这个字段在兼容接口里是必填的随便填一个占位符就行。配置完成后重启 openclaw 服务用一条简单指令验证链路是否通畅openclaw chat 你好帮我确认模型连接是否正常能正常回复说明链路已经通了。如果返回网络错误或超时优先排查三件事Ollama 进程是否在跑、11434 端口是否被占用、base_url 是否写错。我见过太多人把 127.0.0.1:11434 写成其他端口或者漏掉 /v1 路径结果卡在连不上上很久。3.3 混合方案的实战心得折腾到现在我自己用的是本地模型扛日常 API 模型跑重活的混合模式。日常的简单问答、信息整理、定时任务全部走 Ollama 本地模型响应快、免费、数据不出本机遇到需要深度推理、长篇写作、复杂任务拆解的场景再切到 API 模型。这样既保住了日常使用的响应体验又不会在关键任务上被模型能力拖后腿。这个方案唯一要注意的是切换成本。openclaw 切换模型提供方一般需要改配置并重启服务所以最好提前规划好两套配置需要切换时直接替换而不是临时去查文档。另外如果你是在 WSL2 里跑 Ollama而 openclaw 跑在 Windows 原生端两者之间的网络互通取决于 WSL 的网络模式。最省事的做法是让 openclaw 和 Ollama 跑在同一个环境里别跨环境做网络互访能减少大量莫名其妙的连接问题。3.4 本地模型的选择建议如果你决定走本地模型路线我踩过的坑是别贪便宜用小模型。openclaw 的技能调度非常依赖模型的指令跟随能力和工具调用能力参数太小的模型经常把技能参数理解错轻则任务失败重则产生错误操作。以目前主流开源模型来看14B 算是及格线有条件上 32B 或更大参数的模型效果会明显更好但硬件要求也随之上升。量化方面纯 CPU 跑建议用 Q4/Q5 量化级别有显卡就优先用 GPU 推理量化可以适当放宽到 Q6兼顾速度和效果。模型选择上指令跟随能力强的中文模型比如 qwen 系列在 openclaw 这类工具调度场景下表现会比较稳可以在 Ollama 的模型库里直接拉取对应版本测试。4. 移动端、Windows Companion 和 ROS2 扩展的坑4.1 Termux 安装 openclaw 手机版手机上部署 openclaw 的需求其实很实际人不在电脑前但还是希望 AI 助手能响应、能执行一些任务。openclaw 的移动端方向是 companion 应用但很多 Android 用户实际走的是 Termux 路线直接让 openclaw 跑在 Termux 这个终端环境里。Termux 部署的思路跟 Linux 一致但有三个特殊点值得注意。第一Termux 默认源里的 Node.js 可能不是最新建议先执行 pkg upgrade 再安装 nodejs-lts第二Android 系统会回收后台进程需要安装并启用 termux-wake-lock否则 openclaw 服务跑一会儿就被系统杀掉第三它的部分依赖需要本地编译Termux 里要装 binutils、python 等编译工具链不然 npm install 会卡在编译环节。大致流程是这样的pkg update pkg upgrade pkg install nodejs-lts binutils python termux-wake-lock termux-wake-lock git clone openclaw 仓库地址 cd openclaw npm install node openclaw.js start实测下来手机端跑 openclaw 是能用的但短板很明显如果模型也接本地 Ollama手机还得再跑一个 Ollama 服务对性能和续航都是不小的考验。我的建议是手机上优先走 API 模式或者让手机连接局域网内电脑上的 Ollama 服务而不是在手机本地跑模型。4.2 Windows Companion 配置要点Windows Companion 是 openclaw 在 Windows 桌面端的配套组件作用是把桌面环境的能力暴露给助手比如文件操作、剪贴板、屏幕信息获取等。配置时最容易出问题的点集中在认证和权限上。Companion 启动后一般会生成配对令牌或二维码需要在 openclaw 主服务确认配对。我遇到最多的情况是 Companion 启动正常但主服务一直显示未连接。排查方向就三件事第一主服务端口和 Companion 端口是否一致很多连不上就是端口对不上第二Windows 防火墙是否放行了对应端口没放行就会被静默拦截第三配对令牌是否过期令牌有效期通常很短过期就重新生成一次。这三项逐一确认过绝大多数连接问题都能解决。另外要强调一点Windows Companion 涉及桌面级权限建议只在可信的局域网环境里使用不要图方便把它暴露到公网。4.3 ROSClawROS2 Humble 和 Gazebo 的折腾openclaw 相关热度最高的扩展方向之一是跟 ROS2 机器人操作系统结合也就是 rosclaw 这套东西。它的思路是让 AI 助手通过 ROS2 的话题机制观察和控制机器人配合 Gazebo 仿真环境可以在没有实体机器人的情况下做验证。我虽然没有在真实机器人上用过 rosclaw但在 ROS2 Humble Gazebo 的仿真环境里完整走通过一遍。整体感受是想法很吸引人但配置复杂度比纯 openclaw 高一个量级。难点主要在两方面一是 ROS2 环境本身的依赖非常重Humble 版本需要装一整套工具链Gazebo 也要单独装任何一个环节版本不匹配都会出问题二是 openclaw 和 ROS2 的桥接层需要把 ROS2 消息转成模型能理解的文本描述话题列表和消息映射规则都要认真配置配不好就会出现看似连上了但一问三不知的情况。想折腾 rosclaw 的话我的建议是先想清楚目的。如果是为了学习 ROS2 和 AI 的结合方式仿真环境足够了如果是为了实际任务至少要先明确助手要控制哪些话题、读取哪些话题再动手配置桥接不要上来就把整个功能全量开启。4.4 多端协同怎么安排电脑、手机、Companion 都跑起来之后多端协同又成了新的坑。openclaw 的多端设计里会话同步和状态一致是两个核心诉求但实际用下来多端同步并不是无脑自动完成的。我的经验是不要把多端部署当成默认需求一个人用的话一台电脑加一个手机 companion 基本就够了。如果硬要三端同时跑就要接受会话历史不一致的现实并且养成关键任务只在主端执行的习惯。更现实的建议是先想清楚每一端分别承担什么职责电脑端跑重活手机端做轻量询问Companion 只负责桌面联动。职责分开之后多端协同的复杂度会下降很多冲突也少。5. 常见问题速查与排坑思路实录5.1 高频问题速查表把我在部署 openclaw 过程中遇到的和帮别人排查过的高频问题整理成一张表方便你直接对照。问题现象可能原因解决动作npm install 报 engine 错误Node.js 版本太旧升级到 20 LTS清缓存重装依赖Windows 提示无法安全验证 WSL2WSL 内核旧或默认发行版未设置wsl --updatewsl --set-defaultPowerShell 禁止运行脚本执行策略为 Restricted设为 RemoteSigned服务启动后模型请求超时Ollama 未启动或 base_url 写错确认 Ollama 进程和 11434 端口配置本地模型技能经常不触发模型参数量太小换 14B 及以上模型调整量化级别Companion 一直未连接端口不一致、防火墙拦截或令牌过期逐项确认端口、放行规则、重新生成令牌Termux 服务运行一段时间被杀未启用 wake-lock安装执行 termux-wake-lock这张表解决的是现象对应动作的问题但真正定位问题的时候还是需要一套系统的排查思路。5.2 三个容易被忽略的细节第一个是 .env 文件。openclaw 的很多配置除了写在主配置文件里还支持通过环境变量覆盖尤其是 API Key、日志级别、监听端口这些。如果你改了配置但服务没生效先看看是不是环境变量的优先级把配置文件覆盖了这个问题伪装成配置没改对最容易误导人。第二个是日志级别。openclaw 的日志信息量很大但默认级别可能只显示 info。遇到疑难杂症先把日志级别调到 debug 再复现问题。很多看起来究极离谱的报错其实在 debug 日志里就一行小字说清楚了只是默认日志级别把它藏起来了。第三个是版本锁定。openclaw 迭代速度不慢如果你部署的是某个特定版本建议锁定版本号或者定期同步更新。我看到过不少更新完依赖之后服务起不来的问题基本都是版本错位导致的回退到之前能用的版本验证一下往往立刻真相大白。5.3 一套通用的排错流程最后分享一套我排 openclaw 各种问题都会走的流程。第一步先分端问题出在 openclaw 主服务、模型后端还是 companion 端第二步再分级是配置问题、环境问题还是代码 bug第三步看日志把日志调到 debug复现一次看最后一条报错第四步二分定位如果是链路问题用 curl 直接测模型接口用端口检查工具测端口一步步缩小范围第五步回退版本如果更新后出问题优先怀疑版本兼容性。这套流程听起来不花哨但实测比凭感觉乱试高效得多。尤其是遇到那些报错信息完全看不懂的情况时先冷静按流程走一遍十次有八次能定位到真正原因。6. 最后说几句实在话踩完这一圈坑我最大的体会是openclaw 的能力上限对得起它的折腾成本但前提是你对它所依赖的生态有一定熟悉度。Node.js、WSL2、Ollama、ROS2这些词看着吓人实际拆开看每一项都不难难的是它们拼在一起时的组合问题。如果你是完全的新手我的建议是第一次部署就选最简单的单机方案一台 Ubuntu 系统或者 WSL2 环境用 Ollama 接一个 14B 模型先把对话打通再考虑手机端和 ROS 扩展。别一上来就照搬全家桶教程先把最核心的链路跑顺再逐步加功能。这个顺序能帮你少生很多气也能让你真正把 openclaw 用起来而不是一直停在部署中。