OpenClaw Windows 安装配置避坑指南：WSL2 与 Docker 全流程

我花了一个周末，把 OpenClaw 装到主力 Windows 笔记本上，前后重装了三次环境，翻来覆去踩了七八个坑，最后总算把整个安装和配置流程跑通了。这篇 Windows 版安装及配置避坑指南，就是我那三天的完整记录。OpenClaw 本质上是一个开源的个人助理平台，你可以把它理解成给电脑装了一个能听懂自然语言的中枢：你告诉它“帮我整理明天的日程”“把这份文档转成 PDF 发到邮箱”，它会理解你的意图，再调度日历、邮箱、浏览器、文件系统这些工具去执行。它适合已经能熟练打开命令行、想用自然语言统一操控本地工具的人；也适合刚接触开源自动化项目、愿意折腾但不想踩太多坑的新手。这篇教程会从环境准备讲到配置拆解，再给你完整的部署命令和问题排查思路，照着敲就能跑起来。

1. 先搞清楚 OpenClaw 到底是什么，再决定要不要装

1.1 核心思路：一个会调度的“管家”，不是一个聊天机器人

很多人在第一次接触 OpenClaw 时都会有一个误解：以为它跟普通的聊天机器人差不多，你问它答，顶多帮你搜点资料。实际上 OpenClaw 的核心是“调度”：它的底层由一个或多个大模型负责理解任务，但真正干活的是一堆被封装好的工具模块。你可以把 OpenClaw 想成一个管家，模型是管家的大脑，工具是管家的手和脚。你只需要对管家说“帮我把明天下午三点的会议邀请发出去”，管家自己会去翻日历、查联系人、起草邮件、调用邮件客户端发送。整个过程中，你不需要自己去操作任何一个具体软件。

这个设计带来的好处非常明显：第一，所有工具的调用入口统一了，你不用再记每个软件的操作方式；第二，任务可以被组合，比如“把上周的报销单据整理成一个表格，再按部门分类归档”，这种跨工具的流程，以前要手动切换好几个应用，现在一句话就能触发；第三，整个系统是本地优先的，数据流和配置都在自己的电脑或服务器上，隐私方面比全云端方案更可控。

1.2 在 Windows 上安装的难点到底在哪

OpenClaw 官方文档虽然提供了多种安装方式，但对 Windows 用户并不算友好。官方主推 Linux 和 macOS 环境，Windows 上没有那种双击下一步的傻瓜安装包。主流做法是用 Docker 跑容器，而 Docker 在 Windows 上又是基于 WSL2（Windows Subsystem for Linux）来运行的，这就形成了一个“Windows → Docker Desktop → WSL2 → 容器”的长链路。链路越长，出问题的概率就越高，这也是为什么网上一搜 OpenClaw 安装报错，十个有八个都是 Windows 用户。

我自己的安装经历就非常典型：第一次装的时候，我先装好了 Docker Desktop，才想起来去开 WSL，结果 Docker 引擎一直起不来；第二次我把配置文件里的模型服务地址写错了，容器起来了但一跟它说话就报错；第三次是时区没设置，看日志的时候全是 UTC 时间，排查问题特别痛苦。所以我才想写这篇教程，把 Windows 版安装配置过程中最容易踩的坑提前标出来，让你少走弯路。

2. Windows 环境准备：90% 的坑都出在这一步

2.1 安装顺序有讲究，别急着装 Docker Desktop

很多教程一上来就让你装 Docker Desktop，这是个大坑。在 Windows 上，正确的安装顺序应该是：先准备好 WSL2 环境，再安装 Docker Desktop，最后才拉取 OpenClaw 镜像。顺序反了，Docker Desktop 在启动时会检测不到 WSL 后端，然后给你抛一个“Docker Engine stopped”之类的错误，新手很容易在这里卡住半天。

WSL2 的开启方式很简单：以管理员身份打开 PowerShell，执行一条命令：

wsl --install

这条命令在较新版本的 Windows 11 上会自动完成 WSL2 的安装和默认发行版的部署。装完之后记得重启电脑。如果你用的是旧版本 Windows 10，可能需要手动开启“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个功能，再下载 WSL2 内核更新包，最后用wsl --set-default-version 2把默认版本切到 WSL2。这里有一条判断标准：在 PowerShell 里执行wsl -l -v，如果看到发行版名称后面写着“2”，就说明 WSL2 已经就绪。

注意：WSL1 和 WSL2 完全是两回事。OpenClaw 的 Docker 方案依赖 WSL2 的完整 Linux 内核，用 WSL1 会出现各种各样的兼容性问题，不要在这种地方图省事。

2.2 Docker Desktop 与原生安装方式的选型对比

我见过有人在 Windows 上尝试不用 Docker，直接编译 OpenClaw 源码来跑。理论上可行，但实际上非常折腾，因为 OpenClaw 依赖的组件比较多，系统库版本、编译工具链、Python 和 Rust 环境都要对齐，一个版本偏差就是半天时间。相比之下，Docker 容器把所有这些依赖都打包好了，你只需要拉取镜像、挂载配置、启动容器三步。

这里我整理了一个简单的对比表格：

结论很明确：对绝大多数人来说，Docker Desktop 是唯一值得考虑的方案。安装 Docker Desktop 时，记得在设置界面勾选“Use WSL 2 based engine”，这个选项决定了 Docker 是跑在 Hyper-V 还是 WSL2 上。对于日常使用 WSL2 的用户，这个选项能显著减少资源占用，启动也更快。

2.3 环境自检清单，三分钟确认准备就绪

环境装完之后，不要急着拉镜像。先用下面这几条命令做一次自检，确认整条链路是通的，不然排错的时候容易搞不清问题出在哪一层。

首先在 PowerShell 里执行：

wsl -l -v

看到发行版名称后面的版本号为 2，继续执行：

docker version

这条命令会分别显示 Client 和 Server 的版本信息。如果 Server 部分显示“Server Version”或者“Engine”相关字段，说明 Docker 引擎已经正常连接上 WSL2；如果 Server 部分报错，基本可以断定是 Docker Desktop 没有正确使用 WSL2 后端，去设置里重新勾选然后重启。

最后确认一下虚拟化是否开启，打开任务管理器，切到“性能”选项卡，看 CPU 那一栏有没有“虚拟化: 已启用”。如果是“已禁用”，需要进 BIOS 开启 VT-x 或 AMD-V，这一步不做，WSL2 根本跑不起来。

3. 配置文件逐项拆解：改错一个缩进都得折腾半天

3.1 config.yml 骨架结构，先搭起一个能跑的最小框架

OpenClaw 的主配置文件是config.yml，遵循 YAML 格式。Windows 上编辑这个文件最大的坑是缩进问题：YAML 对缩进极其敏感，必须是两个空格，不能用 Tab。我建议你用 VS Code 来编辑，把“Tab 键插入空格”选项打开，就能从源头避免这个问题。

一份最小可用的配置骨架大致长这样：

app: name: openclaw port: 18789 model: provider: compatible api_base: https://your-model-endpoint.example.com/v1 api_key: ${OPENCLAW_API_KEY} model_name: your-model-name tools: calendar: enabled: true email: enabled: false browser: enabled: true file: enabled: true storage: data_dir: /app/data

这个骨架里最关键的就是model这一段。provider填compatible，表示你的模型服务商提供的是标准接口，这样 OpenClaw 可以用统一的格式去调用；api_base是模型服务的地址，很多人在这一步填错导致服务不可用；api_key这里用了${OPENCLAW_API_KEY}的写法，意思是从环境变量里读取，不要把真实的 Key 硬编码进配置文件；model_name是你要用的具体模型名称，填模型服务商给你的模型标识。

3.2 模型通道配置：连不上模型，一切功能都是空谈

模型通道是整个 OpenClaw 的命脉。我的建议是先用最简单的方式跑通，再慢慢调优。你只要记住一个原则：模型服务商必须提供标准接口，然后在config.yml里把api_base和model_name填对就行。

具体操作上，先找一家提供标准接口的模型服务商申请 API Key，然后在api_base里填上它的接口地址，比如https://your-model-endpoint.example.com/v1。这里要注意一个细节：有些服务商的接口地址结尾不带/v1，有些带，OpenClaw 在拼接请求路径时对这块很敏感。如果你不确定，可以先在浏览器里访问一下这个地址，能返回正常的响应就说明格式没错。

配置完成之后，测试模型通不通，不需要启动完整容器，直接看启动日志就行。如果日志里出现401或者authentication failed，那就是 API Key 填错了；如果出现connection refused或者timeout，那多半是api_base地址填错，或者本地网络到该地址的连通性有问题。先把模型通道调通，再谈后面的工具配置。

注意：不要在配置文件里写真实的 API Key，更不要把配置文件传到公开仓库。用${OPENCLAW_API_KEY}引用环境变量是最稳妥的做法。

3.3 工具开关与执行策略：先关掉不用的，再逐个打开

OpenClaw 的能力核心是各种工具模块，包括日历、邮件、浏览器、文件系统、命令行等等。在tools这一段里，每个工具都有enabled开关。我强烈建议你第一次启动时，只打开确实需要用到的工具，其他全部保持false。原因有两个：第一，OpenClaw 启动时会尝试初始化所有开启的工具，如果某个工具对应的服务不可用，轻则打日志警告，重则阻塞启动流程；第二，工具越多，大模型在做任务规划时就越容易“选择困难”，可能把简单任务复杂化。

我自己的做法是先只开browser和file这两个最通用的工具，跑通“帮我打开某个网页”“帮我找某个文件”这类简单对话，确认整个链路没有问题，再根据实际需求，把日历、邮件这些工具逐个打开。

3.4 环境变量与敏感信息：用 .env 文件把机密锁起来

OpenClaw 支持通过.env文件注入环境变量，这是管理敏感信息最方便的方式。在项目目录下新建一个.env文件，内容大致如下：

OPENCLAW_API_KEY=sk-xxxxxxxx TZ=Asia/Shanghai

OPENCLAW_API_KEY就是你在模型服务商那里申请的 Key，TZ是时区设置，这里填Asia/Shanghai，能让容器内部的日志时间变成北京时间，排查问题的时候会舒服很多。

启动容器时用--env-file .env参数把这个文件加载进去，配置文件里的${OPENCLAW_API_KEY}就会被自动替换成真实值。这样做还有个额外好处：.env文件可以写进.gitignore，即使整个项目目录被同步到代码仓库，密钥也不会泄露。

4. 从零到一完整部署：跟着敲就能跑起来

4.1 创建项目目录与启动容器

环境准备好之后，正式开始部署。先在 D 盘建立一个项目目录，目录名不要用中文，也不要有空格，比如D:\openclaw。把刚才写的config.yml和.env放进去，目录结构是：

D:\openclaw\ config.yml .env

然后打开 PowerShell，切换到项目目录：

cd D:\openclaw

接下来拉取 OpenClaw 镜像。在终端执行：

docker pull ghcr.io/openclaw/openclaw:latest

这一步取决于网络环境，可能需要一点时间。如果长时间卡住不动，多半是网络问题，可以先检查 Docker Desktop 的镜像加速配置，或者换个时间再试。

镜像拉取完成后，执行容器启动命令。我这里用的是 PowerShell 环境，命令如下：

docker run -d --name openclaw --restart unless-stopped -p 18789:18789 -v "${PWD}/config.yml:/app/config.yml" -v openclaw_data:/app/data --env-file .env ghcr.io/openclaw/openclaw:latest

逐段解释一下这条命令的含义。-d表示后台运行；--name openclaw给容器起名叫 openclaw，方便后续管理；--restart unless-stopped表示系统重启或容器异常退出时自动拉起，除非你手动停止，这个参数对长期运行非常关键，不加的话电脑一重启 OpenClaw 就没了；-p 18789:18789把容器内部的 18789 端口映射到宿主机的 18789 端口，之后你访问http://localhost:18789就是访问 OpenClaw 的服务；-v "${PWD}/config.yml:/app/config.yml"把刚才编辑的配置文件直接挂载进容器，这样改配置不需要重建容器，重启一下就行；-v openclaw_data:/app/data是数据卷，用来持久化数据，容器删掉重装数据也不会丢；--env-file .env加载环境变量文件。

注意：在 CMD 命令行里，当前目录的变量是%cd%，不是${PWD}。如果你用的是 CMD 而不是 PowerShell，命令要改成-v "%cd%/config.yml:/app/config.yml"。这个差异非常坑，网上很多教程混着写，照抄之后会报挂载路径无效。

4.2 验证服务是否正常启动

容器启动后，先看一下运行状态：

docker ps

看到openclaw这一行的 STATUS 是Up就基本没问题。如果发现容器不断重启，仪表盘上 STATUS 显示Restarting，用下面的命令看日志排查：

docker logs -f openclaw

日志是排查问题的第一手资料。第一次启动时，OpenClaw 可能会拉取模型相关的依赖，日志会持续输出一段时间，看到类似“started”或者“listening”的字样，就说明服务已经起来了。这个过程多等几分钟是很正常的，不要一看没输出就急着重启。

服务启动后，打开浏览器访问http://localhost:18789。如果能看到 OpenClaw 的交互界面，说明 Web 服务正常；如果打不开，先确认端口没有被占用，再检查 Windows 防火墙是否拦截了本地端口的访问。

4.3 首次对话测试与功能验证

服务跑起来只是第一步，真正关键的是模型和工具链路是否通畅。在交互界面里输入一句最简单的指令，比如“你好，请介绍一下你自己”。如果界面有正常回复，说明模型通道已经通了。

接着测试工具链路，输入“帮我创建一个测试文件，内容为 Hello OpenClaw，放在当前数据目录下”。这句话会触发文件系统工具。然后去数据卷对应的目录里找一下，如果看到文件生成成功，说明从“模型理解意图”到“工具执行操作”的完整链路已经跑通。到这一步，OpenClaw 在 Windows 上的安装和基础配置就算真正完成了。

5. 高频问题与避坑实录：我踩过的那些坑

5.1 容器反复重启，日志刷了一屏又一屏

这是新手最容易遇到的问题。打开日志，十有八九是两种情况：一种是config.yml解析失败，一种是模型服务鉴权失败。配置解析失败时日志里会明确报 YAML 解析错误的行号，常见原因是缩进用了 Tab、冒号后面没有空格、或者字符串没有加引号。解决方法是把配置文件用 VS Code 打开，开启“将 Tab 键插入为空格”，重新整理缩进。

模型鉴权失败的日志通常会带有401或403状态码，这时候去检查api_key是否正确，以及.env文件是否真的被加载了。可以在容器启动命令里临时加一句env | grep OPENCLAW看看环境变量到底有没有传进去。

5.2 端口被占用，Web 界面死活打不开

如果访问http://localhost:18789打不开，先判断端口是不是被占了。在 PowerShell 里执行：

netstat -ano | findstr 18789

如果有输出，看最后一列的 PID，然后打开任务管理器，在“详细信息”里找到这个 PID 对应的进程，结束它，或者干脆换一个映射端口，比如把启动命令里的-p 18789:18789改成-p 18790:18789，然后访问http://localhost:18790。另外，Windows 防火墙有时会拦截本地端口的访问，如果确认端口没有被占用，去“Windows Defender 防火墙”里检查一下有没有对应的入站规则。

5.3 日志时间差八个小时，排查问题像在破案

这个问题几乎每个 Windows 用户都会遇到。Docker 容器默认使用 UTC 时间，如果你没有设置时区，日志里记录的时间会比北京时间慢八个小时。排查问题的时候，看到一条报错发生在“凌晨三点”，下意识以为是深夜的问题，实际却是上午十一点。解决方法是提前在.env文件中加上TZ=Asia/Shanghai，然后重启容器。已经启动的容器再加环境变量比较麻烦，最省事的做法是删掉容器重新创建：

docker rm -f openclaw

然后用加了TZ的.env文件重新执行一次docker run命令。

5.4 改了配置不生效，总觉得是缓存问题

很多人修改了config.yml之后重启容器，发现配置没有变化，第一反应是缓存。其实绝大多数情况是文件编码问题。Windows 自带的记事本在保存文件时，默认会带上 UTF-8 BOM 头，这个 BOM 头在 Linux 环境下会让 YAML 解析器第一行就报错。解决方法是改用 VS Code，保存时在右下角把编码选择为“UTF-8”，不带 BOM 的那种。改完配置记得用docker restart openclaw重启容器让配置生效，不要只刷新浏览器页面。

5.5 Windows 路径与权限问题，挂载目录不生效

Windows 路径转 Linux 路径的坑非常隐蔽。在 PowerShell 里，${PWD}/config.yml会被 Docker Desktop 自动转换成 WSL 内的路径，但前提是当前目录路径里不能有中文、特殊符号和空格。我见过有人把所有文件放在D:\我的项目\openclaw下面，结果挂载目录始终不生效，容器里读取到的还是默认的空配置。另外注意盘符要小写，D:/openclaw这个写法比D:\openclaw更安全，反斜杠在某些场景下会被转义。

5.6 内存占用太高，电脑风扇一直转

OpenClaw 本身不算重，但 WSL2 有个特性：默认会占用宿主机最多 50% 的内存，Windows 上如果内存不够大，跑起来会比较吃力。解决办法是在用户目录下新建一个.wslconfig文件，内容写：

[wsl2] memory=4GB processors=2 swap=2GB

这里的参数可以根据自己机器的配置调整。改完之后在 PowerShell 执行wsl --shutdown，然后重新启动 Docker Desktop，配置才会生效。这个文件很多人不知道，以为 WSL2 吃内存是没法控制的，其实一行配置就能解决。

最后再分享一个小技巧：OpenClaw 每次升级版本，都可能带来配置格式的变化。我现在的习惯是每次升级前，先把config.yml和.env完整备份一份，再执行docker pull拉新镜像，删掉旧容器重新创建。这样即使新版本出了问题，也能快速回滚到上一个可用状态，不至于折腾半天回到解放前。