Windows部署OpenClaw：WSL2与Docker Desktop完整指南

1. 先搞清楚运行链路：OpenClaw容器为什么站在WSL2肩膀上

我第一次在Windows上装OpenClaw（“小龙虾”）的时候，其实吃过一个认知上的亏。那时候我下意识地认为，GitHub上给出了一份docker-compose.yml，所以只要在Windows上装好Docker Desktop就能直接跑起来。结果等镜像拉到一半，容器启动就报错，日志里一堆Linux内核相关的东西，这才反应过来：OpenClaw的官方推荐部署方式是Linux容器，Windows上的Docker Desktop本质上是借用了WSL2提供的Linux内核来承载容器。说白了，你要跑的不是一个“Windows版小龙虾”，而是一个放在Windows机器里的Linux容器。

1.1 OpenClaw的部署形态决定了它绕不开Linux环境

先聊聊OpenClaw本身。它不是一个普通的聊天机器人，而是一个个人AI助理框架——你给它一个目标，它会把目标拆成多轮工具调用，比如打开浏览器、点击网页、写文件、执行命令、调用第三方接口等等。要实现这些能力，它的镜像里至少打包了这几样东西：运行时环境、浏览器自动化组件（用来驱动一个受控的Chromium）、操作系统级别的工具链，以及连接各种消息渠道的适配层。

这些组件大多依赖Linux生态，所以作者直接以Linux镜像的方式分发，而不是提供一个Windows可执行文件。这其实是很务实的选择——在Linux容器里，浏览器自动化和命令行工具的兼容性最省心，各种依赖都现成。但对Windows用户来说，问题就出现了：Windows原生不能直接运行Linux镜像，必须有一个“翻译层”或者“承载层”。

1.2 WSL2和Docker Desktop分别干了什么

这里的承载层就是WSL2。WSL2不是一个简单的兼容模拟器，而是一个运行在Windows上的轻量级Linux内核，通过虚拟化技术实现。它的启动速度很快，内存开销比传统虚拟机小得多，和Windows文件系统也能互操作。你可以在WSL2里安装Ubuntu之类的发行版，甚至直接在命令行里敲bash、ls、apt这些命令，体验跟在真Linux服务器上几乎一样。

Docker Desktop则是另一层东西。它在Windows上提供了一个图形化管理界面，同时内置了Docker引擎。当你勾选“Use WSL 2 based engine”之后，Docker引擎实际上是在WSL2的某个发行版里跑的，你从Windows命令行敲docker命令，只是通过客户端去连那个引擎。关系大概是这样的：

宿主机Windows → Docker Desktop客户端 → WSL2发行版里的Docker引擎 → OpenClaw容器

理解这个结构特别重要，因为你以后排查任何问题，都会先问自己：到底是Windows这边的Docker客户端出问题了，还是WSL2里的引擎出问题了，还是容器内部出问题了？这个判断顺序能帮你省下大量时间。

我建议大多数人走Docker Desktop这条路。原因很简单：部署完以后，你会频繁查看容器状态、重启服务、翻日志，Docker Desktop的Dashboard能让你少敲很多命令。等你用熟练了，再考虑要不要把Docker引擎完全搬进WSL2也不迟。

2. 底层环境铺平：WSL2与Docker Desktop的完整配置清单

2.1 第一步先确认虚拟化有没有开

很多人装WSL2装到一半失败，不是命令敲错了，而是Windows的虚拟化功能没开。你可以在任务管理器的“性能”选项卡里找到“CPU”，看一眼右下角“虚拟化”是否显示“已启用”。如果显示“已启用”，那就没问题；如果显示“已禁用”，你需要重启电脑进BIOS/UEFI，把Intel VT-x或AMD-V相关选项打开。

这一步是硬件层面的开关，绕不开。WSL2作为轻量级虚拟机，必须有硬件虚拟化支持才能工作。如果你是在旧电脑或者公司锁了BIOS的机器上操作，可能卡在这第一步，只能找管理员权限解开。

2.2 安装WSL2和默认发行版

确认虚拟化没问题之后，用管理员身份打开PowerShell，执行：

wsl --install

这条命令会自动安装WSL2相关组件，同时装一个默认的Ubuntu发行版。如果是比较新的Windows 10/11版本，通常一次就能搞定。安装完成后需要重启一次电脑，然后Ubuntu会提示你设置用户名和密码。

装完以后，记得确认WSL的版本和默认发行版：

wsl -l -v

输出里应该能看到类似“Ubuntu”发行版，并且在VERSION那一列是2。如果显示的是1，那说明你的WSL内核版本还是旧的，执行一条升级命令：

wsl --set-default-version 2

然后再对具体发行版执行：

wsl --set-version Ubuntu 2

版本切换可能需要一点时间，耐心等待完成即可。我第一次在这条命令上卡了两次，因为旧内核没更新，后来执行wsl --update更新了内核包，再切版本就顺利通过了。

2.3 安装Docker Desktop并打开WSL2集成

接下来去Docker官网下载Docker Desktop安装包。安装过程中有几个选项值得注意：如果出现了“Use WSL 2 instead of Hyper-V”的勾选，一定要勾上；安装完以后，打开Docker Desktop，进入Settings → General，确认“Use the WSL 2 based engine”处于打开状态。

然后在Settings → Resources → WSL Integration里，把你刚刚装好的Ubuntu发行版勾选上。这一步很多人忽略，导致容器只能在Docker Desktop自己创建的默认发行版里跑，或者干脆找不到WSL2环境。勾选完成之后，点一下“Apply & Restart”，让Docker Desktop带着新配置重启。

还有一个很实用的操作：在Settings → Docker Engine里可以配置镜像加速地址。OpenClaw需要拉取的镜像总大小有好几个GB，如果网速不稳，拉取过程很容易超时。配置registry mirror能缓解大部分拉取慢的问题。你可以把常用的加速地址填进去，然后重启Docker服务。

2.4 验证环境是否真正可用

配置完成后，用下面三连来验证：

wsl -l -v docker version docker run hello-world

第一确认WSL2发行版存在，第二确认Docker客户端和引擎都正常（重点看Server那一段的输出，光有Client是不够的），第三确认容器能真正跑起来。如果docker version里Server段没输出，通常说明Docker引擎没启动，这时候去检查Docker Desktop是否在运行、WSL集成是否勾选。

我在这一步遇到过最典型的坑：docker version里Client正常，Server报错“cannot connect to the Docker daemon”。排查半天发现是Docker Desktop虽然显示在运行，但WSL集成没开。把所有窗口关掉重开，重新确认Settings里的WSL Integration勾选框，这才解决。

3. 正式部署：拉取镜像、填入密钥、启动第一版配置

3.1 拿到OpenClaw的部署文件

环境就绪后，下一步是拿到OpenClaw的部署文件。OpenClaw项目在GitHub上开源，部署文件通常包括docker-compose.yml和一个环境变量模板文件，比如.env.example。你可以用git clone整个仓库，也可以直接在仓库页面上下载压缩包，解压到一个专门目录。我建议放到一个不包含中文和空格的路径下，比如D:\openclaw，避免后面容器挂载目录时出现编码问题。

打开docker-compose.yml，你会看到这里定义了多个服务，而不只是一个。这一点和“一个软件一个容器”的直觉不太一样。OpenClaw的主服务负责Agent逻辑和大模型交互，还有服务负责浏览器自动化、消息渠道连接，以及存储依赖。这些服务通过网络互相通信，像是几个各司其职的小团队。

3.2 从.env.example到.env：密钥配置的坑

项目里通常自带一个.env.example文件，里面记录了各种可配置项。第一步把它复制成.env：

cp .env.example .env

然后用文本编辑器打开.env，重点看大模型API相关的配置项。OpenClaw需要一个支持OpenAI兼容协议的大模型接口，你需要在对应的KEY字段填上自己的API Key，同时把API的endpoint地址填准确。

这里有几个很容易踩的细节：

• 密钥前后不要有空格，很多配置文件是严格按字符串读取的，一个不小心多出来的空格会让鉴权失败。
• API地址要区分http和https，路径要以实际开发文档为准，不要想当然地多加“/v1”或漏掉“/v1”。
• .env文件不要提交到git仓库，这个文件相当于你本地的敏感信息库，一旦泄露，别人就能用你的API额度。

如果你用的是某个国产大模型厂商的兼容接口，或者本地部署的模型服务，同样只要保证它是OpenAI兼容协议即可，不需要重新改架构。

3.3 启动第一版：docker compose up -d

配置改完，回到命令行：

docker compose up -d

第一次执行会拉取所有镜像。这个过程最容易让人等得心慌——镜像数量多、体积大，加上网络波动，你可能盯着进度条看半天没动静。如果你的磁盘空间不够，建议先清理一下，整个部署大概需要预留5到10GB的可用空间。

拉取完成后，用以下命令查看各个服务的状态：

docker compose ps

理想状态下，所有服务应该显示“running”或“healthy”。如果某个服务一直处于“restarting”状态，别急着重复up，先看日志：

docker compose logs -f

日志是整个部署过程最重要的排错依据。第一次运行时，我建议把日志窗口开着，留意主服务有没有输出类似“ready”或“started”的提示。如果看到的是报错堆栈，优先定位是密钥问题、网络问题还是配置格式问题。

3.4 冷启动慢不代表卡死

注意，第一次启动OpenClaw会比想象中慢很多。因为它不光要启动主程序，还要初始化浏览器自动化环境，建立模型连接，甚至下载一些运行时组件。这时候容器状态可能是“running”，但日志里没什么动静。我的经验是等3到5分钟，不要一看没输出就重启。你可以用docker stats看CPU和内存消耗，如果CPU有波动，说明服务还在干活。

4. 把小龙虾接上聊天入口：首次对话与浏览器自动化的边界

4.1 OpenClaw为什么非要接一个渠道

OpenClaw本身没有默认的漂亮网页聊天窗口，它的设计思路是让助理“住”在你的消息渠道里。这样做的好处很明显：你可以随时随地用手机发消息指挥它干活，它也能主动推送任务进度和结果，而不是等你打开网站刷新。最常见的接入方式是Telegram、Discord这类消息应用，也支持Web控制台或者本地接口。

我自己的习惯是先用最轻量的方式验证，所以第一次部署只接了Telegram Bot。你如果不方便用它，也可以先用项目自带的控制台或Web界面试，核心流程是一样的：在配置文件里填写对应渠道的凭证，然后重启相关容器。

4.2 创建一个Bot并填入Token

以Telegram Bot为例，你需要在Telegram里找到官方提供的BotFather账号，发送新建机器人指令，填一个名字，就能拿到一串Bot Token。这串Token类似于机器人的“门禁卡”，格式通常是一串数字加冒号再加一长串字符。复制这串Token，填进.env文件对应的字段。

填好之后重启相关容器：

docker compose restart

然后在你的Telegram里找到这个Bot，点一下Start。如果配置没问题，Bot会回复一个初始消息，或者至少显示“已开始”。日志里也会出现类似“bot started”的字段。

4.3 第一条自然语言指令怎么发

接入成功后就到最有意思的环节。我建议第一条指令不要发“你好”，而是发一个能触发工具调用的任务，比如：

帮我写一个Python脚本，计算斐波那契数列前20项，保存到当前目录的fib.py

或者：

搜索一下最近关于个人AI助理的新闻，把摘要保存在notes.txt

发完这条消息，我强烈建议你同时打开日志窗口。你会看到整个调用链是怎么走的：用户消息被送给大模型分析意图，模型决定调用哪个工具，工具执行完把结果返回给模型，模型再组织语言回复你。这个过程可能持续十几秒甚至更久，因为它不只是生成一段文字，而是在真实地操作系统和外部服务。

如果你发中文指令，模型可能理解没问题，但个别工具返回结果时对中文编码不友好，日志里偶尔会出现乱码。这不影响功能，但你有心理预期会少一点困惑。

4.4 浏览器自动化的能力与边界

OpenClaw最让我感兴趣的部分是浏览器自动化。它可以启动一个受控的Chromium，帮你打开网页、点击按钮、填写表单，甚至完成登录后的操作。但这个能力的边界必须明确：它操作的是一个独立的浏览器实例，和你日常使用的浏览器之间没有会话共享。也就是说，你需要让小龙虾登录某个网站，它就需要自己在受控浏览器里走一遍登录流程，并不存在什么“借用你手机扫码状态”的魔法。

这带来了安全性考量。如果你让它登录邮箱或工作系统，账号凭据会存在它的容器环境里。我不建议在正式账号上让它执行涉及支付、删除数据的操作，至少在初期测试阶段，用一次性小号或者低权限账号来实验会比较稳妥。

另外，浏览器自动化对网络环境有要求，如果目标网站对外部访问有限制，或者需要额外验证码，小龙虾会卡在流程中间。这种情况不是配置错误，而是网站本身的访问策略导致的，你需要提前评估任务可行性。

5. 高频故障速查：启动不起来的五种典型死法

5.1 镜像拉取慢或者总是超时

这是Windows用户遇到概率最高的问题，没有之一。OpenClaw的镜像总量不小，如果网络不稳定，docker pull会在中途断开。解决办法有几个：配置registry mirror加速地址；或者在拉取时保持Docker Desktop在前台运行，不要让它休眠；如果实在拉不动，就去仓库看镜像的具体tag，只拉必要的那几个。

镜像拉取中断后，再次执行docker compose up -d会从断点续传，所以不用删除重来，只管重试即可。

5.2 容器一直处于restarting状态

看到某个服务一直在“restarting”，九成是配置文件或密钥的问题。最常见的三个原因：

• 大模型API Key没填，或者填了但格式带空格。
• API的endpoint地址填错，容器连不上模型服务。
• 环境变量里值带了引号，比如“sk-xxx”被写成了'“sk-xxx”'，整条密钥就废了。

排查顺序就两步：先docker compose ps确认哪个服务在重启，再docker compose logs -f看具体报错。日志里通常会直接告诉你“401 Unauthorized”还是“connection refused”。前者去查密钥，后者去查地址和网络。

5.3 端口冲突导致服务起不来

容器里的服务会映射到Windows的某个端口上，比如主服务控制台、浏览器调试端口。如果这个端口已经被本机程序占用，启动会报“address already in use”之类的错误。解决方法是找到占用端口的进程，或者直接改docker-compose.yml里的端口映射。

查端口占用用这个：

netstat -ano | findstr :端口号

拿到PID之后，在任务管理器里结束对应进程。如果你不想动那个进程，就改compose文件左侧的宿主机端口，比如把“8123:8123”改成“8124:8123”，只改冒号左边那个数字，容器内部的配置不用动。

5.4 WSL2内存占用越来越大

用了一段时间后，你可能会发现WSL2吞掉了大量内存，即使容器没怎么干活。这是因为WSL2默认会动态占用最多可达物理内存一半的资源，而且回收很保守。解决办法是在用户目录下创建一个.wslconfig文件，限制内存上限：

[wsl2] memory=4GB swap=2GB

然后在PowerShell里重启WSL：

wsl --shutdown

改完再启动Docker Desktop，内存占用就会控制在设定值内。这个方法对低配Windows设备尤其适用，我自己的机器是16GB内存，限制成6GB后整体顺畅很多。

5.5 Docker Desktop重启后容器状态异常

有时候电脑重启，Docker Desktop不会自动启动，或者容器状态变成exit。如果你希望容器“开机自启”，先给所有容器设置自动重启策略：

docker update --restart unless-stopped 容器名

然后确认Docker Desktop的Settings里打开了“Start Docker Desktop when you sign in”。这两步配合起来，基本能做到开机后不用管，小龙虾自己在后台跑起来。

不过我始终建议，自动化程度越高越需要留意日志。哪怕容器自动重启了，如果镜像里的主服务在启动时崩掉了，它还是会反复重启。所以每次用完容器，不要只看Dashboard上有个“running”小绿点，要看一眼日志里的启动过程是否完整。

6. 写到最后，说点掏心窝的建议

如果你只是在围观层面好奇OpenClaw，大可不必急着接入一堆渠道。我最开始部署的时候，一口气把Telegram、Discord、浏览器自动化全接上了，结果某个渠道配置出错，找问题反而花了不少时间。后来索性重置，只保留一个最简单的渠道，把任务跑通，再逐步扩展，整个过程顺利得多。

还有一个容易被忽略的点：配置目录的备份。.env文件、自定义的配置、工作区文件，这三个东西建议周期性拷贝到安全位置。容器本身坏了可以随时重建，但你在配置文件里精心调整的prompt和工具参数，丢了就要重写。

OpenClaw这类本地部署的AI助理，最核心的价值在于数据和控制权都在你自己手里。你可以放心让它读取本地文件、操作你自己的工具链，而不用把隐私交出去。只是上手之前，先在环境上花点耐心，磨刀不误砍柴工，后面跑任务的时候会轻松很多。