上个月我决定把 OpenClaw 真正用起来结果发现最耗时的事情不是调模型而是在 Windows 上把环境跑通。OpenClaw 这类开源智能体框架官方文档默认你有一台 Linux 服务器可我的主力机就是 Windows。中文资料少得可怜零零散散搜下来全是什么安卓部署、ROS2 联动、Skill 开发完整可用的 Windows 踩坑指南几乎没有。我硬是折腾了三天把 WSL、Node、Python、Poetry、Ollama、systemd 这些环节全部趟了一遍才让 OpenClaw 稳定跑起来。这篇文章就当作我个人的踩坑记录覆盖从 WSL 初始化、OpenClaw 安装配置、模型接入、服务化托管到故障排查的完整链路。适合的目标读者非常明确手头只有 Windows 电脑、想本地跑 OpenClaw 做个人助理或自动化工作流、但不想折腾虚拟机双系统的朋友。如果你属于这类人这篇指南应该能帮你省下至少两天的试错时间。1. 为什么在 Windows 上跑 OpenClaw我最终选择了 WSL1.1 OpenClaw 在 Windows 原生环境跑不起来的真实原因很多朋友下载完 OpenClaw 就想在 PowerShell 里直接跑这是第一道坎。OpenClaw 的核心运行时大量依赖 Linux 生态比如 bash 脚本编排、inotify 文件监听、systemd 进程托管、Python 源码包编译所需的完整 GCC 工具链这些在 Windows 原生环境下要么残缺要么行为完全不一样。具体来说OpenClaw 的 Skill 系统会自动监听某个目录的文件变化Windows 原生虽然有 ReadDirectoryChangesW但和 inotify 的事件语义差异很大很多 Skill 在 Windows 上要么监听不到事件要么偶尔触发但拿不到正确的文件句柄。更麻烦的是它的依赖编译环节像 pydantic-core、tokenizers 这类 Rust/Cython 扩展在 Windows 上没有预编译 wheel 时经常当场开始编译然后报一堆 MSVC 版本不匹配的错。我在 Windows 原生环境试过连openclaw init都没撑过去。所以想在 Windows 上跑起来不是装个 exe 能解决的。你需要一个 Linux 环境而 Windows 用户最体面的方案就是 WSL。1.2 WSL、虚拟机、Docker 三种方案怎么选我也考虑过另外两条路最后都放弃了这里把我的对比结论给出来方案启动速度资源占用硬件直通与 Windows 文件互访适合场景WSL2秒级动态内存分配较轻GPU 可直接用CUDA非常方便但跨盘 IO 慢Windows 主力机跑 Linux 服务首选Hyper-V/VMware 虚拟机分钟级固定内存较重需要额外配置 RDP/共享文件夹通过共享目录体验一般需要完整桌面环境或测试内核模块Docker Desktop秒级取决于容器GPU 需单独配 nvidia-container-toolkit通过 volume 挂载适合直接跑现成 OpenClaw 容器镜像但不利于二次开发最终选 WSL2 的核心原因有三个。第一WSL2 是轻量级虚拟机但启动只需要一秒OpenClaw 作为常驻服务随时拉起不心疼。第二WSL2 天然支持 NVIDIA CUDA后面用 Ollama 跑本地模型可以直接调用 GPU 算力不需要像虚拟机那样做一堆透传配置。第三WSL2 与 Windows 共享 localhost 网络端口Windows 侧的工具可以和 WSL 里的服务直接通信这对 OpenClaw 的 Companion 工具来说太重要了。1.3 最终架构长什么样我最终搭起来的环境长这样Windows 11安装 WSL2发行版选择 Ubuntu 22.04 LTSWSL 内部通过 Node.js 20 Python 3.10 跑 OpenClaw 本体模型接入有两个通道本地 Ollama 跑开源模型需要跨 Windows/WSL 访问时走 localhost 转发OpenClaw 以 systemd 服务方式常驻运行开机自启日志统一由 journalctl 管理Windows 侧安装 OpenClaw Companion 配套工具负责剪贴板共享、系统通知、快捷唤醒这套架构的好处是OpenClaw 的所有核心逻辑都跑在 Linux 环境里和官方文档保持一致Windows 侧只做交互和展示出问题也不会拖垮整个系统。2. 初始化 WSL 之前先把版本和资源配置想清楚2.1 别急着升 WSL 3.0也别用 WSL1网上有 WSL 3.0 的讨论听起来很诱人但我实际看下来WSL 3.0 还处在快速迭代期周边工具链的兼容性没有完全跟上。我在升级后遇到过 Python 虚拟环境启动变慢、Docker Desktop 联动异常的问题花了一晚上回滚。我的建议是现阶段锁定 WSL2 的稳定版本即可不要盲目追新。如何确认当前 WSL 版本在 PowerShell 里执行wsl --version如果输出的版本号低于 2.0.4建议先运行 Windows Update 把系统补丁打全再执行wsl --update另外要明确一点一定要用 WSL2不要用 WSL1。WSL1 是 API 翻译层不是真虚拟机OpenClaw 依赖的 systemd、inotify、完整的 Docker 网络栈在 WSL1 里都是残缺的。检查方法是在 PowerShell 执行wsl -l -v看到 VERSION 列是 2 就对了。如果是 1用下面命令转换wsl --set-version Ubuntu-22.04 22.2 发行版选择Ubuntu 22.04 LTS 比 24.04 更稳WSL 里装什么发行版看似随手一选实际影响很大。我一开始装的是 Ubuntu 24.04预装 Python 3.12看着很新鲜但接二连三踩坑OpenClaw 的部分依赖底层用了 Python 3.10 时代编译的扩展在 3.12 上只能现场重新编译编译过程中又冒出各种系统库缺失的错误。后来我重新装了 Ubuntu 22.04 LTS自带 Python 3.10很多依赖直接命中预编译缓存安装过程顺滑得多。如果你还没有安装发行版建议在 PowerShell 里直接指定版本安装wsl --install -d Ubuntu-22.04安装完成后进入 WSL立刻做两件事更新软件源并升级基础工具。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential git curl wget unzipbuild-essential一定不能省后面编译 Python 扩展和 Node 原生模块都需要整套 GCC 工具链。很多教程默认你已经装好了但我遇到的情况是 90% 的编译失败都源于缺了build-essential。2.3 .wslconfig 资源配置与发行版磁盘迁移WSL2 默认内存占用是动态的但 OpenClaw Node Python Ollama 跑起来之后内存很容易飙到 4GB 以上默认配置下 Windows 会抱怨内存不足。我建了C:\Users\你的用户名\.wslconfig文件手动控制资源上限[wsl2] memory12GB processors8 swap8GB networkingModemirrored localhosttrue解释一下参数memory12GB给 WSL 最大 12GB 内存防止吃掉整个物理内存。如果你的机器只有 16GB 内存建议设为8GB。processors8允许 WSL 使用 8 个逻辑核心编译依赖和跑模型推理都能快一截。swap8GBWSL 的交换文件在跑大模型或者长时间任务时不容易被 OOM 杀掉。networkingModemirrored镜像网络模式让 WSL 和 Windows 共享网络接口这样 localhost 互访最省心。但注意部分企业网络环境用了特殊网络过滤驱动时mirrored 模式会导致 WSL 无法联网遇到这种情况就把它改为默认的 NAT 模式。修改.wslconfig后必须让 WSL 完全重启才生效wsl --shutdown然后重新进入 WSL用free -h验证内存上限是否生效。还有一个非常容易忽略的问题WSL 默认装在 C 盘OpenClaw 的模型缓存、日志文件、依赖动辄几十 GBC 盘分分钟爆掉。为了避免重装建议在安装发行版时就指定位置。新版本 WSL 支持wsl --install -d Ubuntu-22.04 --location D:\WSL如果已经装好了可以用迁移命令把发行版挪到 D 盘wsl --manage Ubuntu-22.04 --move D:\WSL\Ubuntu-22.04--manage --move这个参数需要 WSL 版本在 2.0.4 以上不支持的话先执行wsl --update。迁移过程大概几分钟完成后可以用wsl -l -v再次确认发行版状态正常。3. OpenClaw 本体的安装过程依赖、命令与目录规划3.1 安装通用依赖链进入 WSL 命令行后开始安装 OpenClaw 的运行时依赖。核心依赖是 Node.js 和 Python。Node.js 我强烈建议用 NodeSource 装 LTS 版本而不是用 apt 自带的旧版curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs检查版本node -v npm -vPython 方面Ubuntu 22.04 自带 Python 3.10但还需要确保 pip 和 venv 可用sudo apt install -y python3-pip python3-venv python3-dev这里有个小细节OpenClaw 的 Python 扩展会用到 systemd 的 Python 绑定所以最好也装上sudo apt install -y libsystemd-dev pkg-config如果漏装了libsystemd-dev后面加载某些服务扩展时会报cannot find -lsystemd的链接错误。3.2 克隆源码编译而不是 npm 全局安装OpenClaw 有两种常见安装方式npm 全局安装预编译包或者从源码仓库克隆后手动构建。我第一次图省事用了 npm 全局安装确实能跑起来但有两个问题。第一没法快速升级和查看源码出问题连日志堆栈对应的代码位置都找不到第二OpenClaw 的 Skill 二次开发基本是围绕仓库目录展开的全局安装模式下修改 Skill 要跑到全局 node_modules 里权限和路径都很别扭。所以我的建议是从源码构建。找一个你希望存放工程文件的目录然后执行git clone https://github.com/openclaw/openclaw.git cd openclaw npm ci npm run buildnpm ci和npm install的区别是npm ci严格按照 lock 文件安装不会动依赖版本构建环境更可复现。这一跑就会把所有的依赖和核心代码编出来时间取决于网络状况我这边大概需要五到十分钟。构建完成后把 OpenClaw 的命令链接到系统路径npm link然后执行初始化openclaw init初始化的过程中会询问项目目录、默认模型、消息平台接入方式等全部按默认回车即可后面都可以通过改配置文件来调整。初始化结束后你会得到一个.openclaw配置目录这是后续所有折腾的主战场。3.3 openclaw init 之后目录结构长什么样初始化完成后查看~/.openclaw目录结构大致如下~/.openclaw/ ├── config/ │ └── openclaw.yml # 核心配置文件 ├── logs/ │ ├── openclaw.log # 运行日志 │ └── error.log # 错误日志 ├── skills/ # Skill 技能目录 ├── memory/ # 记忆存储 ├── keys/ │ └── credentials.json # 第三方凭证 └── sessions/ # 会话历史这个目录结构要记牢因为后面 90% 的排错都是围绕这里展开的。config/openclaw.yml是主配置logs是排错第一现场skills用来管理自定义技能扩展。Skills 支持从本地目录导入也支持从远程仓库拉取具体命令在 GitHub 仓库的 README 里有文档这里不展开。4. 配置阶段最容易翻车的四个环节模型、消息平台、端口和文件权限4.1 API 接入还是 Ollama 本地算力很多人问 OpenClaw 是不是只能通过 API 方式使用算力。不是OpenClaw 支持本地模型后端。因为我经常处理敏感文本不希望所有内容都发到云端所以最终采用的是本地 Ollama 云端 API 双轨方案日常简单任务走本地模型复杂任务临时切换到云端大模型。两种方案的对比如下维度云端 API本地 Ollama响应速度依赖网络通常 1-3 秒显卡好时 0.5-2 秒隐私性数据出本机完全本地算力要求无按量付费建议 16GB 显存以上模型能力可用顶级模型取决于你拉取的模型离线可用不可用完全离线可用如果你选本地 Ollama安装就一条命令curl -fsSL https://ollama.com/install.sh | sh然后拉取一个适合日常任务的中小参数模型比如 Qwen2.5 系列注意要以能塞进显存为前提ollama pull qwen2.5:14b安装完 Ollama 后确认服务在 WSL 里监听 11434 端口ollama serve curl http://127.0.0.1:11434/api/tags返回 JSON 数组就说明可用。后面 OpenClaw 配置里的模型地址直接指向这个端口即可。4.2 配置文件核心字段拆解OpenClaw 的主配置位于~/.openclaw/config/openclaw.yml。我拿自己正在用的配置做个拆解agent: name: my-openclaw model: provider: ollama name: qwen2.5:14b temperature: 0.3 max_tokens: 8192 base_url: http://127.0.0.1:11434/v1 platforms: telegram: enabled: true bot_token: 你的Telegram Bot Token discord: enabled: false skills: auto_load: true allow_remote: false memory: enabled: true max_entries: 500几个容易踩坑的字段base_url结尾不要漏掉/v1。Ollama 的 OpenAI 兼容接口挂在/v1路径下漏掉这个路径会导致 404而且 OpenClaw 报错时只会告诉你connection failed定位起来非常痛苦。max_tokens不要设置成 0 或过小。某些后端会把 0 当作无限而 OpenClaw 的默认值如果没配好生成长文本会被截断。模型名一定要写 Ollama 里ollama list查到的确切名字很多朋友写成qwen2.5-q4_k_m.gguf这种文件名字段注定匹配不上。配置完之后用openclaw doctor检查配置是否正常这个命令会帮你诊断配置文件的语法错误和网络连通性。4.3 端口和 localhost 的互通规则OpenClaw 的消息平台接入需要在本地监听端口比如 Telegram Bot 长轮询、自定义 Webhook 回调等。这里最容易出问题的是 WSL2 的网络模型。如果你用的是默认 NAT 模式WSL2 启动的服务会自动被转发到 Windows 的 localhost 上。也就是说WSL 里 OpenClaw 监听了127.0.0.1:8000Windows 浏览器里直接访问http://127.0.0.1:8000就能通。但这有个前提localhostForwarding没被关掉。如果你像我一样已经在.wslconfig里开启了networkingModemirrored那么 WSL 和 Windows 完全共享 localhost互访没有障碍。但镜像模式有一个副作用部分需要绑定固定源 IP 的软件会拿不到本机 IP在 WSL 里执行curl ifconfig.me、ip addr时看到的网络形态都和 NAT 模式不同。如果只是日常使用这个影响不大。端口被占用的排查方法我建议先在 Windows 侧执行netstat -ano | findstr :8000如果发现端口被别的进程占用再执行taskkill /PID 进程号 /F在 WSL 里确认监听状态用ss -tlnp | grep 8000OpenClaw 启动后如果长时间连不上消息平台大概率就是端口没监听或者被防火墙拦了。4.4 永远不要把项目放在 /mnt/c 下这是一条血的教训。很多人包括我习惯把工程代码放在D:\projects里然后在 WSL 里通过/mnt/d/projects去访问。Windows 和 Linux 互访看起来爽但跨文件系统的性能非常感人而且有两个致命问题。第一符号链接symlink在 Windows NTFS 和 WSL 虚拟文件系统之间经常失效。Node.js 的npm ci在/mnt/c下常常会报symlink权限错误解决起来非常麻烦。第二inotify 文件监听在跨盘文件系统上行为异常OpenClaw 的 Skill 自动重载功能会间歇性失效日志里只会留下一堆无意义的EVENT OVERFLOW警告。所以OpenClaw 本体和所有依赖必须放在 WSL 的原生文件系统里比如~/openclaw。Windows 侧需要共享文件时再从 WSL 往 Windows 发而不是反着来。5. 把 OpenClaw 托管成常驻服务systemd、开机启动与日志5.1 开启 systemd 支持OpenClaw 作为个人助理不可能每次都用openclaw serve手动拉起来。我把它注册成了 systemd 服务这样开机自启、崩溃自恢复、日志统一管理全都解决了。老版本 WSL 默认不带 systemd好在现在的 WSL2 已经支持了。开启方法先退出 WSL在 Windows 侧编辑C:\Users\你的用户名\.wslconfig如果之前没建过就新建加入[boot] systemdtrue然后执行wsl --shutdown重新进入 WSL执行systemctl --version能输出版本号就说明 systemd 生效了。这一步如果没生效可能是 WSL 版本太低先执行wsl --update再试。5.2 编写服务单元文件我用 root 权限在/etc/systemd/system/openclaw.service创建了服务文件内容如下[Unit] DescriptionOpenClaw Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple User你的WSL用户名 WorkingDirectory/home/你的WSL用户名/openclaw ExecStart/usr/bin/npm run serve Restarton-failure RestartSec10 EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target注意几个细节ExecStart需要写绝对路径先用which npm确认 npm 的真实路径。写在WorkingDirectory之外的命令要能被 systemd 找到。User不要用 root。虽然 root 最简单但 OpenClaw 产生的日志文件权限全是 root后续你在普通用户下改配置、写 Skill 会遇到各种权限冲突。Restarton-failure是必备项OpenClaw 偶尔会因为上游 API 超时闪退有这个配置会在 10 秒后自动拉起来。写完服务文件后依次执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw查看运行状态sudo systemctl status openclaw如果状态显示active (running)就说明服务已经跑起来了。5.3 start the windows daemon from a non-elevated terminal 的真相安装 OpenClaw 的 Python 依赖时我遇到过一条非常诡异的报错完整文本是error: start the windows daemon from a non-elevated terminal; shared clients第一次看到这条消息时人直接懵了。查了一圈发现这个报错来自 Poetry是它在 Windows 上的服务进程管理模式。当你用管理员权限的 PowerShell 启动 Poetry 相关命令时Poetry 的 Windows daemon 会拒绝从提权终端启动因为共享客户端和服务端在同一会话下需要非提升权限。挺反直觉的对吧完整版安装指南里很少提到这一点。解决办法倒是很简单关掉管理员终端用普通权限的用户终端重新执行 Poetry 命令或者在 WSL 终端里执行不要从 Windows 侧以管理员身份去触发。如果你确实需要在 PowerShell 里跑记得用普通权限。5.4 Docker Desktop 升级后 WSL 起不来的自救OpenClaw 的一些隔离工具链依赖 Docker所以我在 Windows 上装了 Docker Desktop。结果有次 Docker Desktop 自动升级之后WSL 彻底起不来了打开终端直接卡死在启动界面连wsl -l -v都超时。这是因为 Docker Desktop 自带的 WSL 集成组件升级后和已有发行版的虚拟化平台配置产生了冲突。我当时没重装 WSL用下面的三板斧解决了wsl --shutdown等十秒后重新启动 WSL。如果还是起不来重置 Docker Desktop 的 WSL 集成设置把 OpenClaw 对应的发行版取消勾选再重新勾选。最后实在不行在管理员的 PowerShell 里执行netsh winsock reset然后重启电脑。这个操作会重置 Windows 网络栈对 WSL 网络驱动异常特别有效但代价是很多软件的网络连接需要重新建立。6. 高频报错自查清单与一次真实排错案例6.1 高频报错对照表我把折腾过程中遇到的高频报错整理成一张表遇到同样问题直接查报错现象定位方向解决方案command not found: openclaw全局路径未生效确认是否执行过npm link重启终端或重开 WSL 会话Cannot find module xxx依赖不完整在项目目录执行npm ci重新安装依赖Failed to connect to localhost:11434Ollama 未启动或地址错误确认ollama serve正在运行检查base_url是否带/v1symlink EPERM operation not permitted跨盘文件系统权限问题把项目迁到 WSL 原生目录避免/mnt/cMemory limit exceededWSL 内存分配不足调整.wslconfig的memory和swap然后wsl --shutdownEACCES: permission denied文件权限问题检查服务和日志文件 owner用 chown 修正Docker Desktop cannot connect to WSLDocker 与 WSL 集成冲突重置 Docker Desktop WSL 集成设置必要时重装event loop error或EVENT OVERFLOWinotify 跨盘监听异常将 Skill 目录移回 WSL 原生文件系统6.2 真实排错案例Windows 侧访问不到 OpenClaw 的消息平台端口有一天 OpenClaw 服务状态正常journalctl也没有报错但 Windows 侧 Companion 工具始终提示连接不上消息平台。我花了半小时定位。第一步先确认 OpenClaw 确实在监听sudo ss -tlnp | grep openclaw输出显示进程监听在127.0.0.1:8000没有异常。第二步在 WSL 里测试端口从外部访问curl http://127.0.0.1:8000/health响应正常。第三步在 Windows 的 PowerShell 里测试curl http://127.0.0.1:8000/health结果卡住连接超时。这说明监听虽然存在但没有被转发到 Windows 侧。联想到之前动过.wslconfig网络模式我判断问题出在网络配置。于是执行wsl --shutdown然后重新进入 WSLOpenClaw 服务启动后Windows 侧再次访问就通了。这个案例的教训是如果你改过.wslconfig特别是networkingMode和localhostForwarding一定要记得重启 WSL 让配置完整加载而不是指望热生效。6.3 国内环境下的换源与提速安装 OpenClaw 依赖时如果你发现npm ci慢到令人发指或者pip install卡在某个包上下载不完可以考虑换源。我用的是三个源替换npm 全局源切换npm config set registry https://registry.npmmirror.compip 源切换到清华镜像pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simpleapt 源替换为中科大镜像这里需要编辑/etc/apt/sources.list把默认地址批量替换成https://mirrors.ustc.edu.cn/ubuntu/然后执行sudo apt update。源切换之后再跑一次依赖安装速度能快一个数量级少很多无谓的等待。换源之后如果下载出现奇怪的校验和错误先清缓存重试比如 npm 执行npm cache clean --forcepip 执行pip cache purge。最后说几句我的实际体会一套流程跑通之后最深的感触是OpenClaw 在 WSL 里的稳定性远超我最初的想象。前期所有折腾其实都集中在环境适配一旦 systemd 托管跑起来它就是一个可靠的常驻智能体配合本地 Ollama 模型基本可以做到全天候在线。如果让我重新装一遍我会在第一时间就确认三件事WSL2 版本和资源配置、项目绝对不要放在/mnt/c、 Poetry 相关命令用普通终端跑。这三个坑占了全部排错时间的三分之二。顺便分享一个小技巧OpenClaw 的日志默认在~/.openclaw/logs/但如果你用 systemd 托管journalctl -u openclaw -f看日志更实时。我习惯开着这个命令观察服务状态也方便随时把报错信息粘贴到群里问人。后续你如果打算在安卓上部署 OpenClaw或者把它和 ROS2、Gazebo 那套机器人生态连起来这套 WSL 环境的经验依然适用底层跑通之后剩下的就只是玩法问题了。