第一次在 Windows 上折腾 OpenClaw 的人大概率会被环境问题磨掉一半耐心。我前后在两台机器上装过一遍踩过 WSL2 版本不对、Docker Desktop 起不来、初次启动报安全验证失败这些问题之后最深的体会是OpenClaw 本身安装不复杂真正的门槛全在环境预处理。这篇东西就把我实际跑的流程、看到的报错、以及最后怎么绕过去的过程写清楚给准备动手的人一条能直接对着抄的路线。1. OpenClaw 到底是个什么东西为什么非得上手装1.1 一句话认知OpenClaw 是干什么的先解决概念问题。OpenClaw 本质上是一个开源的个人自动化助手框架你可以把它理解成本地自部署版的智能代理工作台——它通过主程序统一调度各类模型能力、工具插件和外部服务让你用自然语言去驱动本机或服务器上的各种操作。和市面上那种纯聊天网页不一样OpenClaw 的设计重心是可编程的助手可以挂 skill技能插件可以对接本地模型比如 qwen2.5-3b也可以把 Windows 桌面端 companion 配起来做系统级交互。很多人拿它和 WorkBuddy 这类商业产品对比其实思路是相通的——先有一个核心编排引擎再往外挂各种能力。OpenClaw 的优势在于它是开源的本地部署数据留在自己手里扩展方式也完全由你控制。1.2 安装前先明确自己的使用场景我不建议任何人上来就照着命令逐行敲。先花十分钟想清楚你装它到底要干嘛因为安装路线跟使用场景直接挂钩。我归纳下来用 OpenClaw 的人基本是三类需求场景典型表现推荐路线个人桌面助手想在本机跑一个接本地模型的助手处理日常任务Windows 或 Ubuntu 单机部署开发测试想研究 skill 机制、改代码、跑自动化流程Ubuntu Docker 或直接源码运行服务端常驻想放在服务器上 7x24 小时跑远程调用Ubuntu Docker 部署第一类用户重点在 Windows 环境配置第二三类用户重点在 Docker 和依赖管理。搞清楚了自己的定位安装过程中的每一步决策都会变得很清晰。1.3 三类用户应该选哪条安装路线我的建议很简单如果你主力机是 Windows而且只是自己用那就在 Windows 上装 WSL2 Docker Desktop。别想着用 cmd 或者 PowerShell 直接跑 Linux 版本的程序OpenClaw 对 Windows 原生支持的边界没那么宽折腾成本远高于收益。如果手里有 Ubuntu 服务器或者虚拟机直接走纯 Linux 路线。干净、可控、报错少而且后面升级维护都方便。如果你想深度改代码那就别用 Docker 包一层直接用源码方式跑方便断点调试。接下来两个大章节我会把 Windows 和 Ubuntu 两条路线分别展开。第一条给大多数人看第二条给服务器用户看。2. Windows 路线WSL2、Docker Desktop 与高频报错排查2.1 为什么 Windows 安装 OpenClaw 绕不开 WSL2先说原理不然很多人会卡在为什么我明明装了 Docker 却起不来。OpenClaw 的运行时依赖大量 Linux 容器和 Linux 特有的系统调用它假设你的执行环境是 Linux。Windows 要跑 Linux 容器最标准的方案就是靠 WSL2 提供底层虚拟化支持——WSL2 是一个真正的轻量级 Linux 虚拟机Docker Desktop 在 Windows 上运行 Linux 容器时默认就是借用 WSL2 的发行版来承载容器。所以安装顺序是这样的先启用 WSL2再装 Docker Desktop然后让 Docker Desktop 使用 WSL2 后端最后才轮到 OpenClaw 的安装。顺序反了后面全是问题。具体启用步骤大部分教程都写过最简单的路径是管理员权限打开 PowerShell执行wsl --install装完重启然后在命令行里确认版本。wsl --status这个命令是我安装过程中使用频率最高的。它会直接告诉你当前默认的 WSL 内核版本是多少、默认发行版是哪个、有没有正在运行的分发版。如果你看到 WSL 版本是 1哪怕发行版装了也没用OpenClaw 的容器环境在里面就是跑不出正常性能。2.2 wsl --status 不出默认版本:2时的处理链路这里专门展开一下 Windows 用户最常碰到的卡点。我第一次装的时候执行完wsl --install重启以后运行wsl --status输出显示默认版本:1而 WSL2 才是当时 OpenClaw 部署文档要求的基础环境。网上很多回答直接让你执行wsl --set-default-version 2但如果你没装 Virtual Machine Platform 或者内核更新包这条命令会报错。完整的排查链路应该是这样的# 第一步确认虚拟化是否在 BIOS/固件层开启 # 打开任务管理器 - 性能 - CPU右下角看虚拟化是不是已启用 # 如果没启用需要进 BIOS 打开 Intel VT-x / AMD SVM # 第二步启用必要的 Windows 功能管理员 PowerShell 执行 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 第三步重启后设置默认版本 wsl --set-default-version 2 # 第四步如果上面命令提示需要内核更新下载 WSL2 Linux 内核更新包并安装 # 安装完再次执行 wsl --versionWSL 这个组件的坑在于wsl --install一键装好的环境跟老版本系统上残留的 WSL1 配置搅在一起时状态会很混乱。最干净的做法是把旧发行版注销wsl --unregister LegacyDistro之类排掉干扰项再重新确认版本。提示判断 WSL2 是否真正生效最直观的验证方法是执行wsl --status看到默认版本:2以及内核版本有具体版本号才说明虚拟化链路通了。纯粹能进入 bash 不代表是 WSL2切成老版本一样能进。2.3 Docker Desktop 与 WSL2 的联动配置WSL2 就绪之后去 Docker 官网下载 Docker Desktop for Windows安装包不小装的时候注意一个细节安装过程中会问Use WSL 2 instead of Hyper-V这里一定要勾选。装完之后打开 Docker Desktop 设置在 Resources - WSL Integration 页面把你要跑 OpenClaw 的那个发行版开关打开。这个开关很容易被忽略。我一开始装完 Docker Desktop没打开任何发行版的 Integration 开关结果从 WSL 的 Ubuntu 终端里执行docker --version直接 pipe 不到在 Windows 终端里 docker 倒是能用但容器跑在哪个发行版上就完全不可控了。开了 Integration 以后WSL 终端里的 docker 命令才会路由到 Docker Desktop 的 Linux 引擎上。配置好之后在 WSL 终端里验证docker --version docker compose version这两个命令能正常输出版本号就说明 Docker 链路通了。我遇到过一种情况是 Docker 引擎起来了但docker ps报permission denied这是当前用户没加进 docker 用户组执行sudo usermod -aG docker $USER后重开终端解决。2.4 Windows 上最容易翻车的几个点Windows 路线我前前后后踩下来真正的坑不在 OpenClaw 本身而在环境一致性。终端别混用。PowerShell、Cmd、WSL bash 三个环境里的环境变量和路径各自独立我建议统一在 WSL 终端里操作 OpenClaw 相关命令别一会儿 PowerShell 一会儿 bash。换行符和防火墙也有干扰。Git 在 Windows 上 clone 项目时默认把 LF 改成 CRLF个别脚本执行时可能被这个隐性差异坑到。在 WSL 里用 git 不会触发这个问题Windows 侧就需要注意。Windows 上的安全提示偶尔出来捣乱比如第一次运行某些可执行文件会弹出无法安全验证之类的拦截。这个不是 OpenClaw 的问题是系统对未签名程序的正常策略。要么在属性里勾选解除锁定要么重新从官方渠道拉取反正别为了绕过验证去关安全中心不值当。3. Ubuntu 路线从裸系统到跑通 OpenClaw3.1 基础依赖安装顺序Ubuntu 路线明显清爽很多。裸系统的情况下我建议按这个顺序装基础依赖sudo apt update sudo apt upgrade -y # 常规开发工具 sudo apt install -y curl git build-essential # 如果走 Docker 部署 sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable docker --now sudo usermod -aG docker $USER需要说明的是docker-compose-plugin这个包名在不同 Ubuntu 发行版上可能叫docker-compose-v2或docker-compose装之前可以用apt search docker-compose确认一下。如果你不想用发行版自带的 docker也可以走 Docker 官方 apt 源但说实话个人使用场景下自带的够用。3.2 拉取项目与依赖安装OpenClaw 的代码拉取方式跟绝大多数开源项目一致官方仓库 clone 到本地然后按项目文档装依赖。我这里不写死仓库地址因为项目仓库的域名和路径可能会有调整关键是流程git clone 官方仓库地址 openclaw cd openclaw # 查看说明文件确定项目要求的 Node.js 版本 cat README.md | head -n 80看到 README 里要求的 Node.js 版本后优先用 nvm 装对应的大版本避免系统自带的 node 版本不对导致装依赖时反复报错curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22这个步骤里最容易出错的地方是直接用apt install nodejs装出来的 Node 版本往往偏老然后跑npm install的时候各种原生模块编译不过去。用 nvm 指定版本是最省事的方式。3.3 首发启动与初始配置依赖装完按项目说明执行第一次启动。OpenClaw 这类框架型项目首次启动通常会做两件事生成一份默认配置文件然后检查外部依赖服务比如模型服务的连接。我在 Ubuntu 上遇到的核心问题是首次启动时模型连接配置是空的。你要先启动本地模型服务如果用的是 Ollama就执行ollama serve或者在配置文件里填上远程模型服务的 API 地址和密钥。OpenClaw 本身不内置模型它只负责编排和调用所以模型服务这块必须自己在配置里指好路。启动成功以后注意看日志输出。日志级别建议首次跑的时候不要调太低能看到请求和响应链路最好。我第一次就是图省事把日志调成 error结果有问题完全摸不着头脑改回 info 级别才看到是配置里模型名称写错导致 404。4. Windows Companion、Skill 与本地模型接入4.1 Companion 与主程序的关系OpenClaw 的 Windows companion 是一个独立的桌面端配套程序用热词搜索能看到的openclaw windows companion指的就是它。它的职责不是替代主程序而是作为一个桌面入口让你在 Windows 桌面上跟 OpenClaw 交互把系统层面的操作指令转发给主程序去处理。配置 companion 的前提是主程序已经跑起来并且对外暴露了可访问的地址和端口。在 Windows 上compaion 通常是 GUI 操作填服务器地址、填认证 token然后连接。我在配置过程中的经验是先确保主程序的网络监听地址不是只绑定了 localhost如果 companion 在另一台机器上就要绑到局域网地址如果只是本机用localhost 反而更安全。4.2 Skill 机制与扩展思路Skill 是 OpenClaw 里我最喜欢的部分它的设计思路跟插件系统类似主程序负责理解意图、调度流程具体的技能动作由 skill 实现。比如你想让 OpenClaw 能操作浏览器就装一个浏览器控制的 skill想让它能查数据库就装数据库查询的 skill。skill 本质上是打包好的指令集和工具定义。安装方式通常是克隆对应的 skill 仓库到 OpenClaw 的 skills 目录然后在配置里声明启用。这个机制的好处是你不必等主项目给你加功能自己照着 skill 的接口规范写一个就行。我自己写过一个简单的定时提醒 skill核心就是一个参数定义加上执行函数半天就调试通了。4.3 接入 qwen2.5-3b 本地模型热词里反复出现的 qwen2.5-3b 关联到 openclaw其实是很多人想用本地小模型跑 OpenClaw避免把所有对话数据发给云服务。qwen2.5-3b 是一个参数量 3B 的模型在消费级硬件上跑得动作为 OpenClaw 的默认模型完全可行。接入的方式跟模型服务有关如果用的是 Ollama# 先拉取模型 ollama pull qwen2.5:3b # 确认模型能正常对话 ollama run qwen2.5:3b 你好然后在 OpenClaw 配置文件的模型服务部分把模型名称填成qwen2.5:3b服务地址填http://localhost:11434。这里有个容易踩的坑OpenClaw 配置里模型名称必须和 Ollama 里的 tag 完全一致多一个冒号或者少一个后缀都会导致请求失败。3B 这个规模的模型回答速度在本地是够用的但不要在同一个对话里塞太长的上下文超出上下文窗口之后 OpenClaw 的体验会明显下降。如果需要更强的推理质量可以往上加参数规模但内存占用会跟着涨取舍就在于你的机器配置。5. openclaw 无法安全验证 与 WSL 环境报告的排查实录5.1 这个报错在什么场景下出现如果搜过相关话题大概率见过两个紧绑在一起的现象一个是 Windows 弹OpenClaw 无法安全验证另一个是某个检查工具提示检测到 WSL2 环境异常请在 PowerShell 中运行 wsl --status 查看环境参考报告解决。这两个现象经常同时出现很多人以为是 OpenClaw 的 bug其实不然。第一个现象本质是 Windows 对未签名可执行文件的拦截提示。OpenClaw 本身是开源社区项目不是商业软件你的系统不认识它的签名自然会在首次运行时弹出安全警告。第二个现象是 OpenClaw 在 Windows 上跑起来之前会做一次环境自检它检测到你当前的 WSL 环境并不是它预期的 WSL2 配置于是抛出报告让你用wsl --status核实。所以这两个报错经常一起出现的原因是你先被安全验证拦了一道放行以后又因为 WSL 环境不自检导致运行直接中断。5.2 完整排查链路复现步骤我第二次在一台新笔记本上安装时完整走了一遍排查过程步骤记录如下你遇到同样问题可以直接照顺序操作第一步PowerShell 里执行wsl --status。这一步的意义不是走形式而是确认三件事内核版本是否存在、默认版本是否是 2、是否有可用的发行版。我那次的结果是默认版本:1已安装的 Linux 发行版无——这同时解释了为什么后面环境自检过不了。第二步修复 WSL2 状态。按照Windows 功能 - 虚拟化 - 内核更新包 - 默认版本 2的顺序处理完毕再次执行wsl --status确认输出里出现默认版本:2。第三步处理 Docker Desktop 的联动。我在这一步发现 Docker Desktop 里的 WSL Integration 是灰色的原因是检测不到任何发行版。重新进 WSL 终端wsl --shutdown再wsl --status等发行版重新挂载后Integration 选项才变正常。第四步回到 OpenClaw。重新执行启动命令之前先确认 Docker 能正常拉取镜像。我在修复完环境之后把之前一个 half-broken 的容器清掉重来才真正跑通。5.3 修复后的验证方法修复完不要急着高兴按这几条做一遍验证wsl --status # 确认输出包含默认版本:2 wsl --list --verbose # 确认发行版状态是 RunningVERSION 列是 2 docker info # 确认 Docker 引擎 Running容器运行时是 runc openclaw doctor # 如果 OpenClaw 自带环境自检命令直接跑它如果项目没有 doctor 命令就用实际启动代替验证——启动主程序、加载一个 skill、向模型发一条问答请求三步都通才算环境没问题。我吃过亏的地方在于环境修好以后直接跑主程序报错倒是没了但一调用 skill 就挂查了半天才发现是 skill 依赖的某个系统包没装。这类深层依赖问题只有真正端到端跑一遍才能暴露。6. 安装完成后的第一件事做一次端到端验收6.1 最小可运行验收清单我把安装成功的判定标准列成一个清单全部满足才能算数主程序进程正常常驻没有几秒后自动退出的情况日志里能看到模型服务连接成功没有鉴权和 404 报错至少能成功执行一个 skill且结果正确写回Windows 用户还需要验收 companion 能连上主程序重启机器后服务能手动或自动恢复而不是必须重新配一遍环境很多人把装完能聊天当作成功标准这其实太浅了。OpenClaw 的核心价值在调度和 skill 执行聊一句话只是验证了最小链路后面那几条才是日常真正要用到的能力。6.2 日常维护与升级注意事项OpenClaw 迭代速度不算慢我自己的维护习惯是升级前先备份配置文件和 skill 目录然后拉取新代码重新安装依赖。OpenClaw 的配置如果你改动过强烈建议单独把配置文件的差异记下来不然升级后默认配置覆盖回来你之前调的东西全白费。Docker 部署的用户升级会轻松一点拉新镜像、重建容器、迁移数据卷即可。源码部署的用户就要注意依赖版本变化我遇到过升级完 npm 依赖版本冲突只能删掉 node_modules 重装才恢复。所以如果你不是要改代码我更建议用 Docker 部署方式维护成本低一个量级。还有一个细节本地模型服务的自动拉起问题。如果你用 Ollama 跑 qwen2.5-3b记得把ollama serve设成开机自启服务。否则每次重启机器OpenClaw 起来了但模型服务没起日志里全是连接超时还容易让人误判是 OpenClaw 坏了。6.3 一些使用上的个人体会最后分享几个我实际用下来的感受。第一OpenClaw 这类项目的生命力在生态skill、配套工具不在主程序本身。如果你的机器配置允许我建议至少装两个不同方向的 skill一个偏本地操作一个偏信息处理这样才能感受到编排的价值而不是像个高级聊天框。第二Windows 用户把 WSL2 环境理顺以后会发现整个安装过程其实非常顺。最难的部分就是环境预处理一旦 WSL2 和 Docker 的关系理清了后面所有的问题都是常规问题。我自己在这上面踩了两轮坑现在回头看最值得记住的就是那句先在 PowerShell 里跑 wsl --status把输出读明白了再决定下一步。第三不要迷信默认配置。OpenClaw 装完以后花一点时间把模型参数、上下文长度、日志级别这些核心项理解清楚你的使用体验会有本质区别。尤其是模型接入那块模型供应商那么多没人能给你一份万能配置理解模型服务地址 模型名称 鉴权信息这三个要素比抄任何人的配置都管用。