OpenClaw 这阵子在我关注的几个社区里频频出现尤其是一堆人拿它跟 WorkBuddy 这类项目对比还有人直接问WorkBuddy 是不是参考了 OpenClaw 才搞出来的。我不去评价抄没抄这种敏感话题但可以负责任地说OpenClaw 在本地 AI 自动化这个方向上确实做了一个非常典型的架构示范——把大模型、技能插件和系统操作层解耦这对后来的一批项目影响很大。我花了两个晚上在 Windows 和 Ubuntu 上分别把它跑通过程中踩了不少坑尤其是那个无法安全验证 WSL2 环境的报错查了一圈资料才找到根因。这篇就按照实际安装顺序把完整流程、报错链路和配置要点都梳理一遍。1. 动手之前先搞清楚 OpenClaw 到底解决什么问题1.1 从模型问答到模型干活的鸿沟大多数人刚接触 OpenClaw 时会陷入一个困惑它看起来像一个聊天机器人但又不像 ChatGPT 那样开箱即用。实际上OpenClaw 定位的是AI 智能体运行框架核心目标不是陪你聊天而是让大模型能调用工具、操作文件、执行命令、完成一系列自动化任务。打个比方普通模型对话像是一个只动嘴的顾问你问什么它答什么OpenClaw 像是给这个顾问配了手和脚它拿到任务后可以拆解步骤、调用技能、读写文件、执行系统命令然后把结果反馈给你。这也是为什么网上讨论 OpenClaw 时常伴随着skill技能、companion伴生应用这些概念——它们都是让模型动手干活的配套设施。1.2 它的核心组件拆解我建议在安装之前先在心里建立一个组件地图避免在配置时迷失方向组件作用安装位置核心引擎负责任务编排、模型调度、技能加载Linux 环境WSL2 或 UbuntuSkill 技能包提供给模型调用的工具集如文件操作、网络请求核心引擎的 skills 目录Windows Companion桌面端伴侣应用提供托盘图标、快捷键、状态展示Windows 宿主系统本地模型服务如 Ollama 运行的 Qwen2.5-3B提供推理能力宿主系统或同网络机器这里要特别强调OpenClaw 的核心引擎跑在 Linux 环境Windows 用户必须通过 WSL2 或虚拟机来运行。这也是安装流程中最容易出问题的地方——不是 OpenClaw 本身难装而是很多人的 WSL2 环境不完整导致安装器检测过不去。2. 第一个拦路虎WSL2 环境检测与修复全程记录2.1 无法安全验证 WSL2 环境到底在验证什么我在 Windows 上第一次运行 OpenClaw 安装脚本时很快就弹出了那个著名的报错OpenClaw 无法安全验证 WSL2 环境。这个报错信息其实很不友好它没有告诉你到底哪里不满足只是说验证失败。经过排查我发现安装器主要检查三件事WSL 子系统是否存在且已安装完整的 Linux 发行版默认 WSL 版本是否为 2WSL1 不满足要求WSL 内核是否更新到支持 systemd 的版本OpenClaw 依赖 systemd 管理后台服务很多人只装了 WSL1或者安装的是旧版内核安装器就会直接判定环境不通过。报错信息里提示的在 PowerShell 中运行 wsl -- status就是让你先自查这三个条件。2.2 三条命令逐级排查定位根因我的排查过程是这样的你可以照着在PowerShell管理员模式里执行# 第一步查看当前 WSL 整体状态 wsl -- status # 第二步查看已安装的发行版及各自版本 wsl --list --verbose # 第三步如果内核过旧执行更新 wsl --updatewsl -- status的输出会显示默认分发和默认版本。如果你的默认版本显示为 1那就说明问题出在版本上需要执行# 将默认版本设置为 2 wsl --set-default-version 2执行完这条命令后如果提示WSL 2 需要更新其内核组件那你还需要跑一次wsl --update更新完成后重启终端再次运行 OpenClaw 安装脚本即可通过验证。这里有一个极易忽略的细节必须确保 Windows 系统的虚拟机平台功能已开启。在控制面板 → 程序 → 启用或关闭 Windows 功能中找到虚拟机平台和适用于 Linux 的 Windows 子系统两项全部勾选并重启。否则就算 WSL 命令能运行内核也无法正常工作OpenClaw 安装器依然会报同样的错误。2.3 前置依赖Node.js 版本千万别用太老的再来一个常被忽略的前置条件——Node.js。OpenClaw 的核心引擎基于 Node.js 开发安装器会检测系统里的 Node 版本。社区里有人反馈Node 16 及以下会直接安装失败或运行报错建议直接上Node.js 18 LTS 或更高版本。Windows 用户建议从 Node.js 官网下载 LTS 版本安装包而不是用apt或choco自动装的那版——官方源里的版本往往滞后容易踩坑。安装完成后在 PowerShell 里确认node -v npm -v如果 Node 版本低于 18建议先卸载旧版再装新版直接覆盖安装有时会残留旧路径配置后面 npm 安装全局依赖时会非常痛苦。3. 从零到跑通Windows 端安装的完整操作序列3.1 安装方式选哪种目前 OpenClaw 在 Windows 上的安装路径主要有两种一种是使用官方提供的安装脚本一种是手动克隆仓库后通过 npm 安装。我两种都试过个人推荐先用官方安装脚本因为它会帮你检查环境和依赖省去手动排错的成本。安装脚本的运行方式通常是在 PowerShell 中执行类似下面的命令# 官方安装脚本以实际官方文档为准 irm https://get.openclaw.example/install.ps1 | iex脚本会依次完成检查 WSL2 环境、检查 Node.js、下载核心引擎到 WSL 子系统、安装 npm 依赖、生成初始配置文件。整个过程的现代化工具标准套路比较省心。3.2 首次启动配置与目录结构安装完成之后第一次启动需要做基础配置。直接启动服务的方式是openclaw start首次启动会自动创建配置目录~/.openclaw/里面有几个关键文件config.json主配置文件包含模型服务地址、Skill 加载路径、服务端口等/skills/技能包存放目录放入子文件夹即可被自动扫描/logs/运行日志目录排查问题全靠它启动成功后会看到类似OpenClaw service started on port 3100的输出。等到这一步Windows 端的基础安装就算完成了。3.3 Ubuntu 子系统内的安装路径对照如果你用的是 Ubuntu或 WSL2 里的 Ubuntu 发行版安装路径稍有不同。官方提供的安装脚本同样适用于 Ubuntu但在运行前需要先确认curl和build-essential已安装sudo apt update sudo apt install -y curl git build-essential然后运行安装脚本curl -fsSL https://get.openclaw.example/install.sh | bashUbuntu 原生环境下最大的优势是没有 WSL2 那一层检测只要 Node.js 和 systemd 正常安装过程几乎不会出幺蛾子。所以如果 Windows 上的 WSL2 问题实在折腾不明白建议先用一台 Ubuntu 机器或虚拟机把 OpenClaw 跑通再回头处理 Windows 端的兼容——这个策略能省大量时间。4. 把 Qwen2.5-3B 接进 OpenClaw本地模型关联实战4.1 为什么要优先选本地小模型OpenClaw 本身不包含模型能力它需要外挂一个模型服务来提供推理。很多人第一反应是接云厂商的 API但我更推荐本地模型尤其是Qwen2.5-3B这个体积的——它有几个实打实的好处隐私性OpenClaw 涉及大量本地文件操作和命令执行这些内容其实不适合全部发到云端去本地模型从源头规避了这个问题。成本跑一个 3B 量级的模型普通消费级显卡或者纯 CPU 推理都能带得动不用为实验阶段额外付 API 费用。可控性参数调优、模型替换、离线运行全部自己说了算。4.2 使用 Ollama 运行模型的完整步骤本地模型我选的是 Ollama Qwen2.5-3B 这个组合。Ollama 对新手非常友好一条命令就能启动模型服务。第一步安装 Ollama。Windows 用户直接在官网下载安装包装完以后它会在后台跑一个 API 服务默认端口 11434。Ubuntu 用户可以用curl -fsSL https://ollama.com/install.sh | sh第二步拉取模型ollama pull qwen2.5:3b第三步确认模型能正常对话ollama run qwen2.5:3b输入一句简单的你好测试输出没问题就退出。此时 Ollama 服务已经在localhost:11434上提供 OpenAI 兼容接口了。4.3 修改 OpenClaw 配置指向本地模型OpenClaw 配置文件~/.openclaw/config.json里跟模型相关的部分核心逻辑是指定模型提供方和模型名称。以 Qwen2.5-3B 为例配置大致是这个样子{ model: { provider: ollama, name: qwen2.5:3b, baseUrl: http://localhost:11434 } }保存后重启 OpenClaw 服务openclaw restart然后可以向 OpenClaw 发一条简单指令测试模型链路是否通畅比如让它列出当前目录下的文件。能正常回复就说明模型关联成功。这里分享一个我实际踩过的坑默认配置里baseUrl如果写成http://localhost:11434/v1反而会报 404。Ollama 的 OpenAI 兼容接口路径是/v1子路径但 OpenClaw 内部拼接路径时可能重复拼接导致最终请求打到/v1/v1。稳妥做法是先留空或使用根地址看报错日志再微调。5. Skill 技能系统让 OpenClaw 真正干活的插件机制5.1 Skill 的本质给模型配一套工具箱OpenClaw 真正强大之处在 Skill 系统。没有 Skill 的 OpenClaw 就像只有大脑没有手脚的机器人有了 Skill模型才能执行文件读写、调用命令行、抓取网页、处理数据等操作。Skill 的本质是一组带描述和参数定义的函数集合每个 Skill 文件夹里包含SKILL.md技能说明文件告诉模型这个技能是干什么的、应该在什么场景下调用若干可执行脚本实际干活的代码常见语言有 Python、JavaScript、Bash可选配置文件定义技能参数、权限范围OpenClaw 会在启动时扫描skills/目录把每个技能的说明注入到模型上下文里让模型在对话中决策现在该调用哪个技能来解决用户问题。5.2 两个典型 Skill 的配置示例我实际配过两个比较有代表性的供参考。第一个是文件整理技能。在skills/cleanup/目录下放一个SKILL.md--- name: cleanup description: 整理指定目录中的临时文件按扩展名分类到对应子目录 parameters: target_path: 要整理的目录路径 --- 该技能用于将目录中杂乱的临时文件按扩展名归类。然后放一个 Python 脚本run.py处理实际逻辑。配置完成后只要对 OpenClaw 说一句帮我整理一下 Downloads 目录模型就会自动调用这个 Skill 去执行。第二个是网页内容抓取技能。这个技能在调试网络类任务时极其实用核心脚本就是利用requests获取页面、用正则或 BeautifulSoup 处理 HTML然后返回纯文本给模型。配置 Skill 有一个注意事项技能目录命名必须是英文小写加下划线不能用空格和中文否则模型可能会出现命名冲突。另外每个技能开头的那段 YAML 格式 metadata 一定要写全——OpenClaw 依赖它来理解技能的触发条件写错或缺失都可能导致技能被永久闲置。对于还没安装任何官方 Skill 包的朋友我的建议是先从一个最简单的 Shell 技能开始比如执行一个命令并返回结果跑通技能调用链路之后再扩展复杂的技能逻辑。6. Windows Companion从命令行到桌面伴侣6.1 Companion 解决的是什么问题OpenClaw 核心引擎跑在 WSL2 的 Linux 环境里命令行交互没有问题但对很多使用者来说每次都要打开终端输命令门槛有点高。Windows Companion 就是解决这个体验问题的它是一个跑在 Windows 桌面的小应用提供系统托盘图标、快捷键唤起、任务状态展示等能力让你不用进 WSL 也能跟 OpenClaw 交互。安装完 Companion 之后它会自动检测 WSL2 里的 OpenClaw 服务并在托盘里显示运行状态。实际使用中最常用的功能是全局快捷键唤起输入窗口相当于把 OpenClaw 变成了类似 Spotlight 的全局助手——按一下快捷键弹窗输入任务描述回车后在窗口里就能看到执行过程。6.2 配置要点与自启动设置Companion 的配置核心就两件指定 OpenClaw 服务地址、指定入口快捷键。服务地址默认是http://localhost:3100如果改了服务端口需要在 Companion 设置里同步修改快捷入口默认是CtrlShiftSpace可以在设置里改建议改成一个不跟输入法冲突的组合Windows 自启动设置可以在 Companion 的设置界面直接勾选开机自动启动。不过有一点需要注意Companion 开机自启只是启动了桌面伴侣它依赖的 WSL2 里的 OpenClaw 服务不一定已经运行。我是通过两项协同来解决的在 Windows 任务计划程序中添加一个登陆时触发的任务执行wsl -d Ubuntu -u username openclaw start这样每次开机Windows 会先拉起 WSL 里的核心服务然后 Companion 再启动链接就不会断没做这个协同之前经常出现托盘图标看着是活的发指令却一直超时的情况——那不是 OpenClaw 卡死只是 Companion 先醒了核心服务还没起来。7. 踩坑实录安装过程中最容易翻车的高频问题7.1 报错WSL 2 内核组件需要更新但wsl --update无效这个坑非常隐蔽明明执行了wsl --update系统也提示更新成功但安装器依然报环境不通过。查了一圈才发现这个版本 Windows 的 WSL 内核更新不通过 Windows Update 分发旧内核文件残留在C:\Windows\System32\lxss\下wsl --update不会主动清理和替换。我的解决方法是手动下载最新的 WSL 内核安装包从微软官方渠道获取运行安装程序它会自动覆盖旧内核。装完再次执行wsl --status确认内核版本号已经刷新然后重启电脑再跑 OpenClaw 安装脚本问题就消失了。7.2 Ollama 模型启动成功但 OpenClaw 提示模型响应为空这个坑更多是配置问题模型侧明明可以对话但 OpenClaw 调用时老是拿不到返回。我排查下来发现是配置里qwen2.5:3b写成了qwen2.5-3b。Ollama 官方在pull时用的是冒号分隔 tag配置示例里容易习惯性写成短横线这一字之差让 OpenClaw 请求了不存在的模型名服务端报错又被吞掉了最终只反馈一个空响应。解决很简单把配置改成冒号格式然后重启ollama list用ollama list确认真正的模型名之后再填写配置就不会出现这种诡异情况了。7.3 端口被占用导致服务启动失败我遇到过几次启动不了的情况日志里显示EADDRINUSE这说明3100端口已经被其他进程占用。最快速的定位方法netstat -ano | findstr 3100拿到 PID 之后在任务管理器里找到对应进程确认是否可关。如果确认是旧版 OpenClaw 残留的后台进程直接在任务管理器里结束它然后重新openclaw start。长期使用的人建议把日志路径固定到一个容易找的位置每次启动失败都去翻日志——OpenClaw 的日志质量相当不错能省很多瞎猜的时间。7.4 官方示例 Skill 加载后始终判断未启用最后一个常见问题把从网上找的 Skill 示例放进skills/目录后用openclaw skills list查看时显示未加载或无效。这个多半是SKILL.md头部 YAML 格式的问题——name、description字段不可少缩进必须严格用空格对齐不能用 Tab。我曾经因为少了一个参数描述字段导致整个 Skill 被 OpenClaw 判定为格式非法而自动忽略。后来仔细比对官方模板改好问题迎刃而解。8. 日常使用中的心得与一点扩展思路OpenClaw 装好之后日常使用中最值钱的不是让它陪你聊天而是把那些重复、固定、低创造力的任务丢给它。我现在最常用的场景是让它在每个工作日上午读取指定目录里的新文档按规则重命名归档把核心摘要写入周报草稿文件。整个链路里 OpenClaw 只用了三个基础 Skill——文件读取、目录遍历、文本写入——但组合起来就省掉了每天十五分钟的机械操作。我自己实际跑下来的体感是**用在步骤明确、评价标准清晰的任务上OpenClaw 极其省心但如果你指望它处理纯创造性或模糊边界的任务那产出还是需要人把关。**这也是我建议新手不要一上来就搭一堆复杂 Skill 的原因——从小任务起步逐步增加技能才能真正理解模型、技能和系统三者之间的配合节奏。最后提醒一句OpenClaw 的版本迭代非常快社区里的配置示例可能过时两三个版本就失效了。我写这篇文章时用的配置结构和命令在下个版本里未必完全一致。不论在哪看到教程都要以官方文档的当前版本说明为准同时养成看日志的习惯——它才是你排障时最可靠的指引。