在Windows上跑OpenClaw我最初的想法很简单照着文档在系统里把环境装好直接运行。结果那天晚上我改了近三个小时的依赖——Python版本冲突、某个底层编译库报错、无头浏览器内核装不上最后甚至连系统里原本正常的开发环境都被搅乱了。冷静下来换了一条路用Docker Desktop把OpenClaw容器化部署。前后不到半小时服务就通了。这篇我把从零到能用的完整过程写出来包括WSL2配置、镜像启动、密钥接入以及Windows环境下最容易被卡住的几个排查点希望能让你在自己的机器上少走弯路。如果你还不熟悉OpenClaw一句话说明它是一个开源AI智能体框架核心能力是让大模型驱动的自动化任务真正落地——自动整理文件、定时抓取网页信息、调用外部API完成多步操作它都能拆解并执行同时还开放了HTTP接口方便集成到自己的工具链里。在Windows上跑它主要就两条路直接装在系统里或者放进Docker容器。我个人强烈建议选后者原因下面展开讲。1. 为什么非要用容器OpenClaw在Windows上原生安装的坑有多深1.1 依赖地狱的具象化OpenClaw本身不是一个单一可执行文件它背后牵扯一整套运行时Python环境、Node环境、浏览器自动化内核、若干系统级动态库以及它们之间微妙的版本约束。这不只是装的东西多而是这些依赖在Windows上经常互相打架。同一台电脑上你装A库的某个版本可能会把B库依赖的另一个版本顶掉然后你花两小时排查发现错误信息指向的库和真正有问题的那一个毫无关系。用一个生活化的类比搬家的时候书、衣服、锅碗瓢盆单独看都是好东西但若一股脑全堆进一个房间走路都困难。容器就是把每样东西放进独立隔间互不干扰。Docker镜像已经把OpenClaw运行时所需的所有依赖都封装好了你不需要在自己系统里重复安装任何东西也就不会制造新的冲突。1.2 Docker带来的四个具体好处环境隔离镜像里自带完整的运行环境宿主机只需要有Docker Engine即可Python、Node之类的通通不用装。即使安装过程中出错也不会污染系统里已有的开发环境。可复现性官方镜像在不同机器上行为一致不会出现我这台能跑、你那台不能跑的环境差异。问题排查时大家面对的是同一个起点。数据持久化容器本身可以被随意删除重建但通过数据卷映射关键配置和运行数据留在宿主机上升级、重装都不会丢。卸载干净不想要了停止容器、删除镜像、删掉挂载目录就干干净净了不会在系统里残留一堆服务和自启动项。1.3 Windows下Docker的本质还是要靠Linux内核这里有个关键点OpenClaw的官方镜像通常是Linux镜像而Windows不能直接运行Linux容器。Docker Desktop在Windows上是通过WSL2来承载Linux虚拟机的。也就是说你实际上先装了一个隐形的Linux环境WSL2Docker跑在里面OpenClaw容器再跑在Docker里。很多人忽略这一层导致出问题时不知道去查哪个环节。你可以把Docker Desktop理解成一个虚拟机管理器加上容器运行时它负责创建和管理那个Linux虚拟机。如果WSL2有问题容器必然起不来如果容器网络不通先检查WSL2而不是直接怀疑OpenClaw本身。1.4 别为了原生感去裸装的两条现实理由我见过一些朋友坚持在Windows里裸装OpenClaw理由是感觉更直接。但实际体验下来长期运行的稳定性差不少。首先是资源管理裸装时浏览器内核、Python进程、Node进程散落在系统不同角落你不容易看清楚它们分别占了多少内存和CPU偶尔某个子进程残留挂起得手动去任务管理器里找。其次升级和回滚非常别扭你可能为了满足新版本依赖不得不升级某个公共库结果另一个工具链受到影响。所以在Windows上Docker不只是一种安装方式它其实是最符合容器化软件运维思路的选择。下面直接进入实操。2. 部署前的环境准备把Docker Desktop和WSL2一次装对2.1 前置条件自查清单在动手安装之前先花三分钟确认三件事否则后面报错会很被动。系统版本Windows 10 2004及以上或者Windows 11。老版本系统对WSL2支持不完整后续会遇到莫名其妙的问题。虚拟化开关CPU虚拟化必须在BIOS层面开启。在Windows任务管理器 - 性能 - CPU页面里可以看到虚拟化已启用如果是已禁用需要进入BIOS打开通常叫Intel VT-x或AMD SVM。内存建议8GB以上。Docker Desktop本身会占一部分内存OpenClaw容器又要跑浏览器类任务8GB以下会比较吃力。2.2 Docker Desktop安装的关键点位到官网下载Docker Desktop安装包双击安装即可安装向导里的选项保持默认就可以安装过程中可能会提示需要注销或重启。装完启动后在Settings - General里确认Use the WSL 2 based engine是被选中的状态。新版本默认就选好了但如果是升级安装的老配置可能还停在旧版Hyper-V模式这一步必须手动确认。这里要解释一个常见误区很多人以为Docker Desktop装完就完事了但其实WSL2内核的完整性同样重要。如果Windows的WSL2内核版本比较老Docker Desktop启动时会提示内核太旧所以建议装完Docker Desktop后顺手在管理员PowerShell里执行wsl --update把WSL2内核更新到最新版本。这个操作我建议每季度做一次Windows的WSL2内核是独立更新的很多人没意识到它和系统补丁不是同一个入口。2.3 给WSL2设置健康的运行参数Docker Desktop默认让WSL2动态使用系统内存但这在Windows上是把双刃剑。默认情况下WSL2可能吃掉大量内存而且不会及时释放。我在一个16GB内存的机器上曾看到WSL2空闲时占用超过6GB严重影响其他程序。解决办法是在用户目录下创建C:\Users\你的用户名\.wslconfig文件内容写成[wsl2] memory4GB processors4 swap2GB localhostForwardingtrue其中localhostForwardingtrue很关键它确保Windows的localhost能访问到WSL2里容器的映射端口否则后面用浏览器打开管理页面会失败。设置完记得在PowerShell里执行wsl --shutdown重启WSL2让配置生效。2.4 验证环境是否可用执行完上面的步骤不要急着装OpenClaw先确认Docker本身工作正常。在PowerShell里运行docker version docker compose version docker run --rm hello-world如果三个命令都正常输出版本信息和Hello World日志说明Docker Desktop和WSL2这条链路已经完整打通。如果hello-world镜像拉取失败先看看Docker Desktop右下角鲸鱼图标是否处于运行状态再检查网络。2.5 WSL2启动异常的两种高频情况我在多台机器上遇到过两种典型报错。第一种是执行wsl命令时报错0x80370102这多半是BIOS中虚拟化没有打开或者Windows功能里的适用于Linux的Windows子系统没有启用。解决办法是去启用或关闭Windows功能里勾选适用于Linux的Windows子系统和虚拟机平台然后重启。第二种是WSL2服务能启动但Docker Desktop一直卡在Starting...状态。这种情况通常是因为Docker Desktop访问WSL2的发行版列表失败可以在PowerShell里执行wsl --list --verbose看看有没有发行版如果没有执行wsl --install先初始化一个默认发行版Docker Desktop就会正常起来了。3. 部署OpenClaw镜像拉取、容器命令与密钥挂载全解析3.1 拉取镜像给版本留一分心环境就绪后第一步是拉镜像。在PowerShell里执行docker pull openclaw/openclaw:latest这里有一个我吃了亏的教训latest标签虽然方便但回滚困难。如果某天官方发布了一个不兼容版本你拉下来的latest可能和你的配置文件对不上到时候又要折腾。建议正式使用前先去镜像仓库页面确认当前最新稳定版本号然后拉取精确标签比如docker pull openclaw/openclaw:0.9.2具体版本号以你看到的实际标签为准拉取过程中如果长时间卡住或超时先检查网络连通性很多情况其实是源站响应慢不是网络断了。可以稍等后重试。另外可以顺手给Docker Desktop配置镜像加速地址这会明显改善大镜像的拉取体验。3.2 启动容器每条参数背后的逻辑镜像到手后用docker run启动。下面是我实际使用的命令docker run -d --name openclaw --restart unless-stopped -p 18658:18658 -v $PWD\openclaw_data:/data -v $PWD\openclaw_keys:/root/.claw/keys -e OPENROUTER_API_KEYsk-or-v1-你的密钥 openclaw/openclaw:latest逐条拆解为什么这么写-d后台运行容器不会因为当前PowerShell窗口关闭而停止。--name openclaw给容器起个固定名字后续docker logs openclaw、docker restart openclaw都不用查容器ID。--restart unless-stoppedDocker守护进程启动时自动拉起这个容器并且除非手动停止否则不会因为崩溃而退出。OpenClaw这种需要长驻的服务必须加这个参数。-p 18658:18658把容器内18658端口映射到Windows的18658端口。这里的容器内部端口以官方文档为准如果版本不一致先docker run一个临时容器再用docker port查看实际暴露端口。-v $PWD\openclaw_data:/data把Windows当前目录下的openclaw_data文件夹挂载成容器内的/data用于存放运行时数据。-v $PWD\openclaw_keys:/root/.claw/keys把密钥文件目录挂载出来。这样你更新密钥时不用进入容器操作直接在Windows侧改文件即可。-e OPENROUTER_API_KEY...通过环境变量注入模型服务商密钥。PowerShell里的$PWD\openclaw_data表示当前目录下的子文件夹如果你在D盘专门建了一个C:\openclaw用来放这些文件就用C:\openclaw\openclaw_data替换。3.3 API密钥怎么接环境变量和密钥文件两条路OpenClaw本身不内置大模型它需要对接你选择的大模型服务商比如与OpenAI协议兼容的服务商、Claude兼容的服务商或OpenRouter这类聚合平台。对接方式就是设置API密钥。一种方式是直接用环境变量传进去适合快速验证。比如上面命令里的OPENROUTER_API_KEY就是在容器运行时注入到进程环境里。缺点是命令历史里会留下密钥明文不太推荐长期使用。更推荐的方式是挂载密钥文件。很多镜像会读取/root/.claw/keys下的配置文件文件内容看起来像这样{ openrouter: { apiKey: sk-or-v1-你的密钥 } }你只需要在Windows侧创建openclaw_keys目录把带密钥的JSON文件放进去容器启动后读取的就是这个文件。这样密钥不会出现在进程列表或终端历史中。修改密钥时改文件后重启容器即可docker restart openclaw3.4 用Docker Compose固化配置避免每天敲长命令docker run命令比较长每次重建容器都要重新输入容易出错。更稳的做法是写一个docker-compose.yml把配置固化下来。我的配置大致长这样version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 18658:18658 volumes: - ./openclaw_data:/data - ./openclaw_keys:/root/.claw/keys env_file: - .env然后在同目录创建.env文件内容写上# 模型服务商配置 OPENROUTER_API_KEYsk-or-v1-你的密钥之后启动只需要docker compose up -d停止和删除容器docker compose downenv_file方式的好处是密钥集中管理而且docker-compose.yml和.env独立存放不提交到版本库降低泄漏风险。4. 启动后的三步验证确认智能体真的在工作4.1 第一步看日志不要只看容器状态容器状态是Up不代表里面的服务就正常。第一次启动后立刻看日志docker logs -f openclaw正常情况下你会看到类似服务启动完成监听地址0.0.0.0:18658之类的输出并且日志会持续滚动这说明OpenClaw进程在正常运转。如果日志几秒钟就停止且没有新的输出多半是进程异常了需要看后面的错误信息。还有一个小细节容器日志如果出现乱码或时间不对多半是容器时区问题不影响使用但排查问题时容易干扰判断。可以在docker-compose.yml里加上- TZAsia/Shanghai环境变量日志时间就对齐了。4.2 第二步HTTP接口自检OpenClaw通常会提供一个HTTP管理接口。容器启动后在浏览器访问http://localhost:18658如果页面能打开并返回基本信息有些版本返回JSON有些返回简单的Web页面说明端口映射是通的。如果不通再用命令行测一下curl.exe http://localhost:18658/这里注意在PowerShell里curl被默认映射为Invoke-WebRequest行为不一样要测试原始HTTP响应最好显式用curl.exe。4.3 第三步提交一个最小任务验证完整链路接口能访问只说明HTTP服务活着还不能确定大模型调用链路是通的。抓紧做一次最小任务测试向OpenClaw提交一个简单任务格式大致是curl.exe -X POST http://localhost:18658/run -H Content-Type: application/json -d {\task\:\请告诉我当前时间\}具体接口路径和请求结构以你所用版本的API文档为准。这个请求如果能正常返回结果并且在日志里能看到模型调用记录和工具执行记录就说明整条链路已经打通。这一步很重要如果你跳过它后面跑复杂任务时出了问题你很难判断是配置问题还是任务本身的问题。5. 高频问题排查四个关卡逐个拆开看5.1 第一关容器一直重启或启动即退出遇到这种情况先不要急着改配置执行docker ps -a如果状态列显示Restarting说明进程一直在崩溃循环。再执行docker logs --tail 200 openclaw看最后200行日志九成问题都能在日志里找到答案。常见原因有三类密钥没配置或格式不对日志里会提示认证失败、缺少API Key之类。检查环境变量是否拼写正确密钥文件路径是否挂载到了正确位置。内存不足容器启动过程中OOMOut of Memory被杀日志末尾通常有Killed字样。解决办法是增大.wslconfig里的内存上限或者降低并行任务数量。镜像架构不匹配在非标准架构的机器上拉取镜像容器启动时会提示exec format error。这种情况需要去镜像仓库确认是否有对应架构的版本。5.2 第二关端口被占用如果启动时报端口冲突或者浏览器始终无法访问先看端口占用情况netstat -ano | findstr 18658如果发现某个非Docker进程占用了这个端口最简单的改法是把宿主机侧的映射端口改成别的比如18858。在docker-compose.yml里修改ports部分即可ports: - 18858:18658注意修改后之前用来做健康检查的localhost:18658也要同步改成localhost:18858。5.3 第三关WSL2网络导致访问超时有时候容器是活的日志也正常但Windows侧就是访问不到端口。优先怀疑WSL2网络状态。执行wsl --shutdown然后等十几秒重新启动Docker Desktop。这个操作会彻底重置WSL2虚拟机网络大部分localhost突然访问不了的问题都能解决。如果还是不行检查.wslconfig里localhostForwardingtrue是否还在。还有一种隐蔽情况Windows防火墙阻止了Docker相关进程的入站连接。如果你只在本地使用一般不会遇到但如果要从局域网其他设备访问OpenClaw就需要在防火墙里放行Docker对应进程的端口。5.4 第四关容器删掉重建后配置全没了这个坑最典型也最好预防。如果你创建容器时没有挂载卷所有配置和密钥都保存在容器可写层中一旦执行docker rm删除容器这些东西就全部消失等于白干。解决办法是严格遵守上面第3节的做法把数据和密钥目录明确挂载出来。这样重建容器后只要挂载路径指向同一个文件夹数据和配置都还在。还有一个小习惯把.env文件和docker-compose.yml放在同一个项目目录里整个目录定期压缩备份就能做到完整还原。5.5 额外提醒Docker Desktop占用资源过高Windows上跑Docker最容易被吐槽的就是资源占用。我的做法是双管齐下第一通过.wslconfig限制WSL2的内存和CPU上限前面已经写过不再重复。第二停止不需要的容器。很多时候你之前测试用的容器还在后台跑着你以为不占资源其实它们会持续吃掉CPU和内存。用这个命令查看docker stats看到空闲容器直接删掉Docker Desktop的体感性能会明显回升。6. 部署之后升级、备份与长期维护的三件事6.1 升级镜像数据不丢的操作顺序OpenClaw迭代速度比较快隔几周就可能有新版本。升级时不要直接删容器正确流程是docker compose pull docker compose up -dpull拉取新镜像up -d会自动用新镜像重建容器。因为有数据卷挂载容器重建不影响已有数据。升级完成后记得看一下日志确认新版本正常启动。使用指定标签部署的朋友升级时手动把docker-compose.yml里的版本号改成新标签再执行上面的命令即可。这里再次推荐指定标签因为latest升级有时会带来配置文件格式变化你无法控制具体落到哪个版本。6.2 备份要覆盖配置数据密钥三部分我见过有人只备份了配置结果密钥丢了还得找服务商重新申请。备份至少包含三个部分docker-compose.yml、.env和openclaw_data目录。在Windows上我习惯直接右键压缩整个项目目录成zip再复制到其他磁盘。恢复时解压目录执行docker compose up -d即可。6.3 几个值得长期坚持的使用习惯用docker compose代替docker run管理服务这是我认为最值得养成的一个习惯。它把启动参数、卷映射、密钥配置全部写进文件任何时候重建容器都是同样的结果避免了当初那条命令咋写的这种事发生。另外谨慎使用docker system prune -f。这个命令会清理所有未使用的资源听着很爽但如果你有某次关联失败的卷它可能连你的数据卷一起清掉。我的原则是先docker volume ls看看有哪些卷确认无误再用docker volume prune精准清理绝不用一键全家桶。最后分享一个我在Windows上使用Docker的小技巧Docker Desktop右下角的鲸鱼图标右键菜单里有一个Restart选项。如果遇到WSL2网络卡死、容器状态异常又查不出原因先执行这个Restart往往比你去重启整个电脑快得多。这个动作相当于把Docker引擎和WSL2的连接重新拉起来很多奇怪的偶发问题都会在它面前消失。