想在一台Windows机器上把OpenClaw 完整跑起来确实不是下载一个安装包就能完事的。OpenClaw 这类面向 AI Agent 工作流的开源命令行工具天生依赖一套完整的“运行时环境”Node.js 负责驱动 CLIPython 负责跑本地模型或辅助脚本Git 负责拉取项目和扩展模块WSL2 提供类 Linux 的运行底座Docker 则用来起隔离服务。这篇内容就是围绕 OpenClaw 在 Windows 下的安装与初始化展开的我会从环境选型、工具安装、核心初始化到常见坑位排查把整个流程中值得注意的细节完整讲一遍。适合正在Windows上部署智能体工具、尤其是第一次接触 WSL2 Node Python 组合的开发者参考也适合那些已经被各种报错折磨过、想系统梳理一遍部署链路的人。1. 部署前必须想清楚的几件事1.1 为什么最终选择了 WSL2 而不是 Windows 原生环境先说结论OpenClaw 这类 Agent 工具在 Windows 上优先跑在 WSL2 里而不是直接装在 PowerShell 或 CMD 环境里。原因不复杂但值得展开。OpenClaw 的源码和依赖链里有大量为 POSIX 设计的脚本、软链接和权限模型。Windows 原生文件系统虽然能通过 Git for Windows 拉代码但 npm 安装依赖时会经常碰到路径过长、符号链接失败、权限模型不一致等问题。尤其是 node_modules 动不动几千个文件Windows 的 NTFS 对这类小文件密集场景处理效率远不如 Linux 的 ext4安装慢是小事安装到一半报错才是最折磨人的。WSL2 本质上是一个轻量虚拟机跑着完整的 Linux 内核但能直接读写 Windows 文件系统网络和端口也能共享。对 OpenClaw 来说这就等于你在一台 Windows 电脑上“借”到了一个完整的 Linux 环境并且这个环境的启动成本比传统虚拟机低得多。我在踩过几次纯 Windows 环境的坑之后才彻底转向 WSL2后面所有初始化步骤都稳定多了。对比一下两个方案的差异对比项Windows 原生WSL2文件系统性能NTFS 小文件性能差ext4 性能好适合 node_modules符号链接与权限需要管理员权限易出错原生支持Docker 支持需要额外配置Docker Desktop 可直接走 WSL2 后端shell 脚本兼容性类 Unix 脚本经常跑不了原生支持 bash资源占用较轻虚拟机方式但内存可动态回收1.2 OpenClaw 依赖链的整体认识在动手之前先把 OpenClaw 的依赖链路理清楚这会直接决定安装顺序。OpenClaw 的主程序是一个 Node.js 应用所以 Node.js 运行时是第一个刚需。它负责解释执行 CLI 命令、启动交互界面、管理 Agent 会话。第二个刚需是 Git因为 OpenClaw 的安装方式不是下载一个 exe而是从仓库拉取源码安装扩展模块也依赖 Git。第三个刚需是 PythonOpenClaw 安装模块里有不少辅助脚本用的是 Python比如数据处理、工具链集成另外如果要关联本地模型服务模型推理部分通常也由 Python 生态提供。第四个是 Docker它用于启动隔离的沙箱服务、中间件或者辅助应用默认情况下不是必须但很多扩展场景会用到。还有一个容易忽略的点OpenClaw 的底层交互需要访问模型服务。你可以选择配置云端 API也可以配置本地模型服务比如通过 Ollama 运行 Qwen2.5 系列模型无论哪种都必须在初始化阶段正确写入配置否则工具起来之后一问一个错。1.3 版本选型的“基线思维”在部署这类开源工具时我的原则是“不要用最新要用 LTS”。Node.js 只选 LTS 版本Python 选 3.10 或 3.11Git 选官方稳定版不要碰 nightly 或 beta。为什么这么保守OpenClaw 的依赖库覆盖面很广一旦某个底层依赖使用了 Node 原生模块而你的 Node 版本太新导致 ABI 不匹配npm install 阶段就会直接编译失败。这种问题排查起来非常痛苦因为报错信息往往指向某个 C 编译库而不是 Node 版本本身。Python 同理过新的版本可能导致依赖库还没有提供对应的 wheel 包pip 现场编译又会引入一堆编译工具链问题。所以把版本固定在一个稳妥的基线上是省时间的第一要务。2. 安装前的环境准备与工具选型2.1 WSL2 的正确打开姿势先说 WSL2 的启用。很多人在这一步就卡住了因为 Windows 功能开关和 WSL 内核是两码事。正确顺序是这样第一步以管理员身份打开 PowerShell执行# 启用 WSL 功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完这两条命令后重启电脑。重启后打开 PowerShell执行wsl --set-default-version 2注意如果这里提示“WSL 2 需要更新其内核组件”说明你缺少 WSL 内核更新包。这时候不要在 PowerShell 里死磕直接去微软官网搜索“WSL2 Linux 内核更新包”下载并安装对应的 MSI 包安装完再执行上面的命令。这个坑非常常见因为它跟系统版本、Windows Update 策略都有关系不是每次都能顺利通过在线更新。为了确认 WSL2 是否就绪执行wsl --status wsl -l -v如果看到“默认版本2”并且安装的发行版版本列是 2说明环境没问题。我个人的建议是直接安装 Ubuntu 22.04 LTS 作为默认发行版原因很实际社区兼容性最好遇到问题搜索到的解决方案最多Node.js 和 Python 的 apt 安装源也最全。2.2 Node.js 与 Git 的两种安装路径Node.js 的安装方式有两种一种是手动下载 MSI 安装包另一种是用 winget 命令行。我推荐后者因为可以精确指定版本并且方便后续升级。# 安装 Node.js LTS 版本 winget install OpenJS.NodeJS.LTS # 安装 Git winget install Git.Git安装完成后为了确保工具链在 WSL2 里也能直接用建议在 WSL2 里单独再装一份 Node.js或者用 nvm 管理。这里有个常见的误区很多人以为 Windows 装了 Node.jsWSL 里就能直接用。但实际上 WSL 里跑的是 Linux 内核Windows 的 exe 版 Node.js 虽然能通过 interop 被调用性能却有损耗而且 OpenClaw 在 WSL 里的安装脚本可能无法正确解析 Windows 路径。老老实实在 WSL 里用 apt 或者 nvm 安装是最稳的。在 WSL 的 bash 里执行# 更新源 sudo apt update sudo apt upgrade -y # 安装 Git sudo apt install git -y # 安装 Node.js 20 LTS通过 NodeSource 仓库 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs装完检查版本node -v npm -v2.3 Docker Desktop for Windows 的关键配置OpenClaw 在某些工作流里会要求启动 Docker 服务比如跑沙箱、跑中间件、或者关联一些容器化的辅助应用。Windows 下装 Docker 的常规方案是 Docker Desktop安装本身没有太多坑关键是安装后的后端选择。Docker Desktop 安装完成后建议在 Settings 里把 “General” 中的 “Use the WSL 2 based engine” 勾选上而不是用 Hyper-V 后端。选 WSL2 后端的好处是和 OpenClaw 所在的 WSL2 环境无缝打通容器端口可以直接通过 localhost 访问不需要额外做端口映射。还需要注意一个细节Docker Desktop 的资源限制。默认情况下它会占用较多内存如果你电脑只有 16GB 内存又同时在跑本地模型服务很容易出现卡顿。我建议在 Settings 的 Resources 里把内存限制在 4GB-6GBCPU 限制在 50% 左右给 WSL2 里的模型服务留出空间。2.4 Python 虚拟环境管理Python 的安装相对直接但我的建议是不要直接往系统里装全局 Python而是用 pyenv-win 或者 Anaconda 来管理版本。原因同样是版本隔离。考虑到 OpenClaw 关联的模型服务经常会用到 Ollama、vLLM 或者 llama.cpp 这类工具它们对 Python 版本有要求如果你系统里同时有多个项目虚拟环境能帮你免去百分之八十的“这个包为什么装错版本”问题。我习惯优先用 WSL2 里的 Python 3.10因为大部分 AI 相关依赖在 3.10 上的兼容性最稳。在 WSL 里安装sudo apt install python3 python3-pip python3-venv -y python3 --version注意不要用系统自带的 Python 3.8 以下的版本那些在依赖解析上会遇到很多麻烦。3. OpenClaw 安装与初始化完整实操3.1 工作目录规划与代码拉取我建议把 OpenClaw 放在 WSL2 内部的 Linux 文件系统目录里而不是放在 /mnt/c 下面的 Windows 目录。原因前面已经说过Linux 文件系统在 WSL 里的 I/O 性能远好于 /mnt/c 的 9P 协议性能。如果你把 OpenClaw 放在 /mnt/c/projects/openclaw 下npm install 会慢到让你怀疑人生而且 git checkout 的速度也会明显变慢。推荐的工作区结构是这样的mkdir -p ~/workspace cd ~/workspace git clone https://github.com/openclaw/openclaw.git cd openclaw拉完代码后先看一眼仓库根目录的文件结构确认有 package.json、README、还有类似 setup.sh 之类的脚本。这一步虽然不起眼但能帮你确认仓库是否完整避免后面执行到一半发现缺文件。3.2 依赖安装要点与 npm install 避坑OpenClaw 的依赖安装命令就是标准的 npm install但这里有几个实操层面的细节值得注意。首先npm install 可能会因为网络原因在某个包上下载超时。遇到这种情况不要立即重跑先删掉可能残缺的 node_modules 文件夹和 package-lock.json再重新安装。具体命令是rm -rf node_modules package-lock.json npm install其次如果安装过程中出现 node-gyp 编译错误不要慌先确认系统里有没有 build-essential。绝大多数原生模块编译失败都是因为缺少这些基础编译工具sudo apt install build-essential -y安装完成后可以验证一下核心依赖完整性npx tsc --version如果 TypeScript 编译器能正常输出版本号说明依赖安装基本正常。3.3 初始化配置从配置文件到环境变量OpenClaw 的初始化过程本质上就是生成配置文件、写入模型服务凭据、然后做一次环境自检。进入项目目录后执行初始化命令./openclaw init这个命令会引导你生成一份配置文件通常在 ~/.openclaw/config.yaml 或项目目录下的 openclaw.config.yaml。里面最核心的字段有几个默认模型服务地址、API Key、Agent 名称、工作目录。我的建议是配置文件里的密钥不要用明文写在 YAML 里而是通过环境变量引用例如model: provider: local base_url: ${OPENCLAW_MODEL_URL} api_key: ${OPENCLAW_API_KEY} model_name: qwen2.5:3b这样做的好处是当你把配置同步到其他机器或者放进代码仓库时不会泄露密钥。对应地在 WSL 的 ~/.bashrc 或 ~/.zshrc 里写入export OPENCLAW_MODEL_URLhttp://127.0.0.1:11434 export OPENCLAW_API_KEYlocal-test-key然后执行 source ~/.bashrc 生效。3.4 模型服务关联以 Qwen2.5-3B 为例OpenClaw 初始化之后最重要的一步是确认它能正确访问模型服务。如果你的机器配置不算高我强烈建议先用 Qwen2.5-3B 这种小模型跑通整个链路。3B 参数量在量化之后大约需要 2-3GB 内存普通笔记本的 CPU 也能跑只是速度会慢一些但用来验证功能完全够。具体操作是用 Ollama 把模型拉下来# 安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 下载模型 ollama pull qwen2.5:3b # 启动服务 ollama serve服务默认监听 127.0.0.1:11434。确认服务正常后在 OpenClaw 的配置里把 base_url 指向这个地址model_name 填 qwen2.5:3b。如果你使用的是云端模型 API只需要把 provider 改成对应厂商并填入 API Key 即可。这里有一个实操细节在 OpenClaw 里测试模型连接时不要直接问复杂逻辑问题先发一个“ping”级别的简单消息验证链路。我见过太多人配置完模型后直接让它写代码结果报错之后分不清是模型服务问题还是 OpenClaw 自身问题白白浪费排查时间。3.5 启动与首次交互验证配置完成后正式启动 OpenClaw./openclaw启动成功后你会看到一个交互式命令行界面。这个界面就是 Agent 的核心入口可以输入任务指令OpenClaw 会调用配置好的模型服务来执行。首次交互建议按这个顺序测试输入 help 命令确认 CLI 能正确响应。输入一个简单的非代码任务比如“介绍一下这个项目的文件结构”确认模型调用链路通。输入一个代码任务比如“帮我写一个 Python 脚本实现斐波那契数列”确认代码生成与文件操作能力正常。如果在第三步出现工具无法调用的问题比如没法创建文件、没法执行命令多半是权限问题检查一下 OpenClaw 运行用户对工作目录是否有写权限。如果出现在 WSL 里卡住无响应则优先怀疑 Docker 服务没起来。4. 常见问题与排查技巧实录4.1 OpenClaw 无法安全验证 WSL2 环境报错提示 wsl --status在 OpenClaw 启动时有时会遇到提示“无法安全验证 WSL2 环境请在 PowerShell 中运行 wsl --status”。这个报错本质上是 OpenClaw 在启动环境自检时发现 WSL2 状态异常。最常见的几个原因按顺序排查第一确认当前终端确实是 WSL 终端而不是 Windows 的 PowerShell。直接用 Windows 终端输入 openclaw 命令和进入 WSL 后输入 openclaw 命令是完全两套环境。很多人装完环境后在 PowerShell 里直接敲 openclaw自然报这个错。第二检查 WSL 默认版本wsl --status如果输出显示“默认版本1”说明 WSL2 被切换回来了需要重新执行wsl --set-default-version 2第三如果 wsl --status 里显示内核文件缺失或版本过旧直接去下载 WSL2 内核更新包安装。安装完执行wsl --shutdown然后重新启动 WSL再进入 OpenClaw 目录验证。4.2 磁盘必须经过初始化逻辑磁盘管理器才能访问这个报错虽然听起来像是磁盘分区问题但在 OpenClaw 部署场景里它通常是 WSL2 的虚拟磁盘文件vhdx没有被正确挂载导致的。常见原因是异常重启后 WSL 的虚拟磁盘状态损坏。修复方法是wsl --shutdown然后在 Windows 的磁盘管理工具里找到对应的 vhdx 文件确认它的状态。如果 WSL 相关发行版仍然无法启动可以尝试用管理员 PowerShell 重新注册发行版wsl --unregister Ubuntu wsl --install -d Ubuntu不过注意这会清空该发行版里已有的数据建议先备份重要配置。4.3 端口占用冲突Windows 关闭端口号的正规操作OpenClaw 默认会占用一个本地端口作为 API 服务端口默认通常是 8080 或 3000。如果启动时报端口被占用不要直接改代码先用系统工具查清占用来源。在 PowerShell 里执行netstat -ano | findstr :8080记下最后一列的 PID然后打开任务管理器在“详细信息”标签里根据 PID 找到对应进程确认它是什么程序之后再决定是否结束。也可以直接用命令结束taskkill /PID 6284 /F如果你发现占用端口的进程是 Docker Desktop 或者某个模型服务不要贸然 kill正确的做法是在 OpenClaw 配置文件里把 service_port 改成没用过的端口比如 18080。改端口后重新启动比和现有服务抢端口要省时得多。4.4 Docker 守护进程错误start the windows daemon from a non-elevated terminalDocker Desktop 有一个比较反直觉的设定它不建议你从管理员终端启动。如果你用管理员权限的 PowerShell 启动了 Docker Desktop然后在 WSL 里执行 docker 命令有时会碰到类似“error: start the windows daemon from a non-elevated terminal; shared clients”的提示。这个问题的本质是权限令牌不一致。Docker Desktop 在 Windows 上通过管道与客户端通信管理员的管道和普通用户的管道不能共享导致 WSL 里的 docker 客户端连不上守护进程。解决方式很简单关掉 Docker Desktop正常用普通权限的终端重新启动不要在“以管理员身份运行”的终端里启动它。启动后再回到 WSL执行docker ps如果能看到容器列表哪怕是空的说明 Docker 链路正常。4.5 npm 与 Python 版本冲突速查在多次部署尝试中我把常见报错和对应解法整理成了速查表方便对照。问题表现可能原因解决方式npm install 时报 enoent 错误删除的 package.json 或目录权限异常重新 git clone 项目再 npm installpython3 命令找不到WSL 未安装 Pythonsudo apt install python3 python3-pip执行 openclaw 提示 Cannot find moduleNode.js 版本未切换或依赖缺失执行 node -v 确认版本重装依赖模型请求超时本地模型服务未启动确认 ollama serve 进程验证 curl 127.0.0.1:11434WSL 启动后网络异常Windows 代理环境或 WSL 网络模式冲突检查 /etc/resolv.conf执行 wsl --shutdown 后重启5. 初始化后的扩展与生产化建议5.1 与 Obsidian 等知识库联动OpenClaw 初始化跑通后很多人会把它和 Obsidian 联动用 Agent 管理笔记或构建个人知识库。整体思路是让 OpenClaw 的 Agent 能把工具输出写到 Obsidian 的 vault 目录里并且读取已有笔记作为上下文。在 OpenClaw 的配置里添加一个 workspace 目录指向 Obsidian 的 vaultworkspaces: obsidian: path: /mnt/d/ObsidianVault auto_index: true这里有一个容易踩的坑Obsidian vault 如果在 Windows 文件系统上OpenClaw 从 WSL 里访问 /mnt/d 路径时文件监听效率很低。大型 vault 的索引更新会有明显延迟。折中方案是用 Windows 任务计划程序或者 Obsidian 自带的同步机制把 vault 同步一份到 WSL 内部目录用于 Agent 索引处理完再同步回去。5.2 自定义模型参数与系统提示词OpenClaw 默认配置下模型参数和系统提示词基本是开箱即用的但真要用于生产环境建议改几个参数。temperature 默认值通常是 0.7但如果你让它处理代码重组、配置修改这类任务建议降到 0.2 以下减少随机性。反之如果是创意写作、头脑风暴可以调到 0.9。系统提示词的配置路径通常在配置文件的 prompt 字段。你可以把项目的编码规范、工作流约定写进去这样 Agent 输出会更贴合团队规范。不过我补充一句系统提示词不要写太长超过模型上下文窗口的 20% 后多写的部分对输出质量基本没有正向贡献反而会挤占上下文空间。5.3 Windows 服务化托管与开机自启如果希望 OpenClaw 在 Windows 上开机自动运行最简单的方案是在 WSL 里用 pm2 托管进程然后在 Windows 任务计划程序里设置开机调度。在 WSL 里安装 pm2npm install -g pm2 pm2 start ./openclaw --name openclaw pm2 save pm2 startuppm2 startup 会生成一条 systemd 启动命令按它提示的执行即可。然后在 Windows 端用“任务计划程序”新建一个开机任务运行 wsl.exe参数填 pm2 resurrect。这样每次开机后WSL 启动并恢复 pm2 进程列表OpenClaw 就自动在后台跑了。5.4 日志与备份OpenClaw 的日志默认打到 ~/.openclaw/logs 目录但很多人不会主动去查看。建议在配置文件里开启详细日志并把日志目录软链到 Windows 下方便查看ln -s ~/.openclaw/logs /mnt/d/OpenClawLogs日志轮转也值得设置。pm2 自带日志轮转模块直接执行pm2 install pm2-logrotate pm2 set pm2-logrotate:max_size 10M日志文件不清理的话几个月后能涨到几个 GB到时候磁盘满了才去排查就属于给自己找麻烦了。最后再分享一个小经验部署 OpenClaw 这类工具最难的不是安装本身而是第一次跑通端到端链路后的状态确认。建议在完成初始化后花十分钟把默认端口、配置文件路径、日志路径、模型服务地址四个关键信息记下来做成一个简单的部署备忘。后续升级、迁移或者排障时这份备忘能帮你省下大把时间。另外WSL2 的磁盘占用会随着依赖安装逐渐变大建议定期在 Windows 侧执行一次磁盘清理并用 wsl --manage 检查虚拟磁盘的健康状态。