Windows上安装OpenClaw全指南：从WSL2到Docker配置与多智能体部署

1. 安装前的环境准备与方案选型

1.1 OpenClaw 是什么，为什么 Windows 上安装会“绕”

先花一分钟把 OpenClaw 这个东西说清楚。OpenClaw 是腾讯开源的多智能体协作开发平台，你可以把它理解成一个“智能体管家”：它能调度多个 AI 智能体协同完成任务，支持接入不同的模型服务（OpenAI 兼容接口、NVIDIA NIM、本地 Ollama、各种云厂商模型等），还能配上工具（skills）让智能体具备使用电脑、操作浏览器、读写文件这类实际能力。换句话说，它不像普通聊天机器人那样只做问答，而是围绕一个目标，拆任务、调工具、跑流程。

正因为它能干这么多事，依赖项就不是“一个软件装完就完事”那么轻松。OpenClaw 官方推荐用 Docker 部署，容器里面把运行环境、依赖库、配置文件一次性打包，省去你在宿主机上折腾 Python、Node、依赖冲突的麻烦。对 Windows 用户来说，装 Docker Desktop 就得先搞定 WSL2（Windows Subsystem for Linux 2），这一套下来，安装过程就从“下载 exe 双击下一步”变成了“装 Docker、配 WSL、拉镜像、配模型、启动服务”五连跳。

这篇文章就是把这五连跳拆开，按 Windows 平台的实际操作顺序一步步走。适合谁看？第一次接触 OpenClaw 的 Windows 用户，想在自己电脑上跑起来的人，以及以前装过但卡在 Docker 引擎、WSL 内核、模型配置这类环节上的朋友。看完你不仅能装完，还能知道每一步为什么这么装。

1.2 Windows 上安装 OpenClaw 的三条路，我为什么推荐 Docker

先说结论：我在 Windows 上试过三种方式，最终长期用的是 Docker Desktop 方案。

方案 A：Windows 原生直接跑（Git clone + 脚本安装）

OpenClaw 官方仓库提供了 Linux/macOS 的一键安装脚本，Windows 上也可以通过 Git Bash、PowerShell 或者 WSL 里执行安装。这种方式的问题是：OpenClaw 依赖一堆 Python 包、Node 工具链，原生跑在 Windows 上时偶尔会遇到路径分隔符、编译依赖、环境变量不识别这类问题，处理起来比较烦。

方案 B：虚拟机（VMware/VirtualBox）里装 Ubuntu，再装 OpenClaw

这种方式隔离性最好，适合不想动 Windows 系统配置的人。但虚拟机开销大，你给 VM 分配多少内存都嫌不够，而且 Docker 里面再跑容器，属于“嵌套虚拟化”，性能打个折。如果你是 AMD/Intel 新平台，嵌套虚拟化一般能用，但老旧 CPU 核显直通、USB 透传这些配置会占掉不少时间。我只在需要干净实验环境时才用这个方案。

方案 C：Docker Desktop + WSL2（推荐）

Docker Desktop 在 Windows 上默认使用 WSL2 后端，容器实际运行在轻量级 Linux 虚拟机里，但用户完全感知不到，文件共享、端口映射、命令行操作都跟本机一样顺滑。OpenClaw 官方镜像开箱即用，升级也就是重新拉镜像的事，卸载也干净，不污染系统。代价是你需要装 WSL2 并保证虚拟化开启，这部分下面会一步步做。

所以这篇教程的主线就是方案 C，把 WSL2、Docker Desktop、Git、OpenClaw 容器、模型配置串起来。

1.3 安装前的软硬件清单核对

在动手之前，先对照这个清单检查自己的环境，能省掉后面很多坑：

这里面最容易翻车的就是虚拟化没开。很多人装 Docker Desktop 一直提示 WSL2 kernel 错误，最后发现 BIOS 里虚拟化关闭了。如果你不确定，先按 Ctrl + Shift + Esc 打开任务管理器，切到“性能”选项卡，点“CPU”，右下角看“虚拟化”那行。显示“已启用”就放心，显示“已禁用”就要先去 BIOS 开，这个不提前搞定，后面全白搭。

2. Windows 系统层配置：WSL2 与必要工具链

2.1 启用 WSL2：执行一条命令，但别忽略前提

WSL2 是 Docker Desktop for Windows 的核心后端，它本质上是一个轻量级虚拟机，专门跑 Linux 内核，让容器可以直接运行在 Linux 环境里，不用像传统虚拟机那样消耗一整份完整的操作系统资源。

在 Windows 11 或新版 Windows 10 上，启用 WSL2 最简单的方式是以管理员身份打开 PowerShell 或 Windows Terminal，执行：

wsl --install

这条命令会帮你自动启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个可选组件，然后安装默认的 Ubuntu 发行版，再下载安装最新 WSL2 内核。执行完之后按提示重启电脑，第一次启动 Ubuntu 时会要求你设置用户名和密码，这个用户是 WSL 里面的 Linux 用户，跟你 Windows 登录账号没关系。

有几件事我要单独提醒：

1. wsl --install 在部分国行机器或装了精简版系统的机器上，可能会因为系统组件被精简而失败。这时候你需要手动启用组件： dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart ，然后 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart ，重启后再用 wsl --update 手动更新内核。

2. 装完之后检查默认版本是不是 WSL2。在 PowerShell 执行：

wsl -l -v

输出里 NAME 是 Ubuntu，VERSION 应该是 2。如果显示 1，执行：

wsl --set-version Ubuntu 2

3. WSL2 默认会占用内存，微软的机制是按需分配，但 Docker 跑起来后调度比较激进。建议在用户目录下建一个 .wslconfig 文件限制资源，内容参考：

[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true

这里 memory 和 processors 按你机器实际配置改， localhostForwarding=true 一定要留着，这是 Windows 侧通过 localhost 访问容器内端口的关键。

2.2 安装 Git 并做最小必要配置

OpenClaw 安装过程、技能库（skills）的拉取都依赖 Git。Windows 上推荐安装 Git for Windows，直接去官网下载安装包，安装向导里大多数选项保持默认即可，但有几个选项值得注意：

• “Select Components”里勾上“Git Bash Here”和“Git GUI Here”，后面在文件夹里右键就能打开 Git Bash，很方便。
• “Choosing the default editor”选你顺手的，VSCode 或 Vim 都行，不常改代码的保持默认 Vim 也行。
• “Adjusting your PATH environment”选“Git from the command line and also from 3rd-party software”，这样 PowerShell、CMD、WSL 里都能直接用 git 命令。
• “Configuring the line ending conversions”选“Checkout as-is, commit as-is”，避免 Windows 和 Linux 换行符差异带来莫名其妙的问题，尤其是从仓库拉取脚本时。

装完验证一下：

git --version

然后配置你的用户信息，这两个配置会写进 Git 的全局配置文件，OpenClaw 拉取远程仓库或提交本地修改时都会用到：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

如果你在 WSL Ubuntu 里也打算用 Git，别忘在 WSL 终端里也执行一遍同样的配置。Windows 侧 Git 和 WSL 侧 Git 的配置是独立的。

2.3 终端工具：为什么我推荐 Windows Terminal

安装过程中你会频繁用到命令行，Windows 自带的 CMD 不好用，PowerShell 比 CMD 强但也不算顺手。我建议你装 Windows Terminal，微软商店直接搜就行。它的好处：

• 多标签页，PowerShell、CMD、WSL Ubuntu、Git Bash 可以并排开，不用开一堆窗口。
• 支持 Ctrl+V 粘贴，对新手友好。
• 渲染速度比老终端快，长日志输出不容易卡。
• 可以自定义配色、字体，显示中文没问题。

装完之后把默认终端配置文件改成“Windows PowerShell”或“Ubuntu”，看你自己习惯。我个人的做法是：系统层面用 Windows Terminal，跑 Docker 命令用 PowerShell，跑 OpenClaw 交互命令行时如果遇到字符集问题，就切到 WSL Ubuntu 里执行。

3. Docker Desktop 安装与核心配置

3.1 下载安装 Docker Desktop，注意两个选项

去 Docker 官网下载 Docker Desktop for Windows，双击安装。安装界面上有两个关键选项要留意：

• “Use WSL 2 instead of Hyper-V”：这个必须勾上，表示用 WSL2 后端，性能更好且与 WSL 集成更顺。如果你不小心选了 Hyper-V，后面也可以去设置里改。
• “Add shortcut to desktop”：看个人喜好，建议勾，方便随时打开。

安装完成后会提示注销或重启，照做。重启后第一次启动 Docker Desktop，它会初始化 WSL 后端，可能需要几分钟。启动后会让你登录 Docker Hub 账号，可以直接跳过（Skip）。

验证安装是否成功，在 PowerShell 执行：

docker version
docker compose version

docker version 输出包含 Client 和 Server 两段，如果 Server 段有信息，说明引擎跑起来了。如果 Server 段是空的或提示无法连接，先看 Docker Desktop 右下角鲸鱼图标是不是在运行状态，右键看“Troubleshoot”有没有报错。

3.2 Docker Desktop 的资源设置与国内拉取加速

Docker Desktop 跑起来后，进 Settings 做几项优化：

• “General”标签里，如果你在中国大陆，把“Expose daemon on tcp://localhost:2375 without TLS”留着不勾，保持默认安全状态。
• “Resources → Advanced”里给 WSL 后端分配内存和 CPU。默认是机器一半资源，OpenClaw 单容器场景建议给 6GB 到 8GB 内存，CPU 留 2 核以上。给太少容器会 OOM，给太多会影响 Windows 本身流畅度。
• “Resources → WSL Integration”里确保打开“Enable integration with my default WSL distro”，并且勾选你安装的 Ubuntu。这一步很重要，不然你在 WSL 里执行 docker 命令会提示找不到。
• “Docker Engine”标签里可以改镜像加速配置，如果你能直接访问 Docker Hub 官方源，不用改；如果拉取镜像超时，建议在 JSON 配置文件里添加国内镜像加速地址。在 Docker Desktop 的 Docker Engine 配置中增加 registry-mirrors 列表即可，比如：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

改完点 Apply & Restart，让 Docker 引擎按新配置重启。这里提醒一句，镜像加速只影响 Docker Hub 镜像拉取速度，不影响 OpenClaw 本身的数据传输。

3.3 检查 Docker 与 WSL 的联动是否正常

我见过不少人在这一步出问题：Docker Desktop 显示 Running，但在 WSL Ubuntu 里执行 docker ps 却提示“permission denied”或“cannot connect to the Docker daemon”。

先在 PowerShell 里验证：

docker ps

如果正常，再切到 WSL Ubuntu 终端里执行同样的命令。如果 WSL 里不行，多半是 WSL Integration 没勾上，或者当前用户不在 docker 用户组。WSL 里执行：

sudo usermod -aG docker $USER

然后重启 WSL 终端，或者干脆重启 Windows 让用户组生效。有些人改了用户组还是不行，那就重启 Docker Desktop 再试。

另外，Docker Desktop 右下角图标如果是一直转圈或者红点，去 Settings → Troubleshoot 里点“Get support”，看看日志里有没有 WSL 相关的报错。最常见的原因是 Windows 版本过旧、WSL 内核没更新，或者虚拟化被安全软件禁用。对应处理分别是升级系统、执行 wsl --update 、检查 BIOS 和安全中心。

4. OpenClaw 安装与启动实操

4.1 获取 OpenClaw：官方脚本 vs 仓库手动拉取

OpenClaw 官方推荐一条命令安装，但在 Windows 上直接用官方脚本会有一个典型问题：它默认面向 Linux/macOS 环境，PowerShell 下执行 curl 管道脚本有时会因为执行策略（Execution Policy）报错，或者脚本内部用到的命令在 Windows 上没有对应实现。

所以我在 Windows 上的做法是：先通过 Git 把仓库拉下来，再手动执行安装脚本。具体步骤：

1. 找一个你打算放安装文件的目录，比如 D:\OpenClaw ，在 PowerShell 里执行：

mkdir D:\OpenClaw
cd D:\OpenClaw
git clone https://github.com/open-claw/open-claw.git
cd open-claw

如果你访问 GitHub 比较慢，可以考虑用 ghproxy 之类的加速地址，但注意代理服务的安全性和时效性，更稳妥的方式是直接用 git clone 多试几次，断点续传性能还不错。

2. 查看仓库里的安装说明。通常有 README.md 和 install 相关脚本，打开看当前版本的安装方式。OpenClaw 的安装脚本支持指定目录，如果你想装到别的路径，官方脚本一般带 --directory 或环境变量参数，具体以仓库文档为准。用 PowerShell 执行安装脚本时如果提示“无法加载，因为在此系统上禁止运行脚本”，先执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这是 PowerShell 的安全策略，允许运行本地脚本和经过签名的远程脚本，只对当前用户生效，不会影响系统安全性。

3. 安装脚本执行完成后，会提示你设置工作目录和配置模型服务。OpenClaw 支持多种模型后端：OpenAI 兼容接口、NVIDIA NIM、Ollama 等。你可以先用 OpenAI 兼容 API 来跑通流程，比如配置一个环境变量 OPENAI_API_KEY 指向能访问的大模型服务。如果你有 NVIDIA GPU 并想本地跑 NIM，OpenClaw 有专门的 NIM 配置方式，会在配置向导里让你填 endpoint 和 API key。

4.2 通过 Docker 运行 OpenClaw 容器

OpenClaw 仓库里带 Dockerfile 和 docker-compose.yml。如果你是用 Git 拉取的仓库，直接用 docker compose 启动最省事。在仓库目录下执行：

docker compose up -d

这个过程会构建镜像，首次构建会比较久，因为要拉基础镜像和安装依赖。构建完容器会以守护模式跑起来。查看状态：

docker compose ps

看到状态是 Up 就说明起来了。日志查看：

docker compose logs -f

这时候你可能会在日志里看到模型服务的连接信息，以及启动后的端口监听信息。OpenClaw 的 Web 界面或交互面板一般会监听某个本地端口，比如 8080 或 3000 之类的，具体看日志输出和配置样例。浏览器访问 http://localhost:端口 ，应该能看到 OpenClaw 的控制面板。

如果你不想通过源码仓库构建，也可以用官方发布的 Docker 镜像直接跑，这样升级时只要重新拉取镜像就行。命令形如：

docker run -d --name openclaw -p 8080:8080 \
  -v /d/OpenClaw/data:/data \
  -e OPENAI_API_KEY=你的key \
  openclaw/openclaw:latest

注意 Windows 上路径挂载的写法跟 Linux 不一样：主机路径 D:\OpenClaw\data 在 Git Bash 里可以写 /d/OpenClaw/data ，在 PowerShell 里直接写 D:/OpenClaw/data 也可以。如果你不确定，先创建一个目录放数据，避免容器删除后配置全丢。

4.3 配置模型后端与核心参数

OpenClaw 启动后第一件事就是确认模型服务能连通。配置文件通常是一个 .env 或 config.yaml ，里面需要指定：

• 模型服务地址（endpoint），比如你用的是 NVIDIA NIM，那就是 NIM 网关的地址和端口；用的是 OpenAI 兼容服务，就是对应服务的 API 地址。
• API Key，必须配好，不然请求会被拒。
• 默认模型名称，比如 meta-llama-3.3-70b-instruct 、 gpt-4o-mini 或你服务里支持的模型名。
• 温度、最大 token 等生成参数，这些可以留默认值，OpenClaw 在智能体任务中会按需覆盖。

我的建议是先用最简单的对话场景验证连通性，再逐步加技能、加工具。不要一上来就配置复杂的 skills 和 computer use，先把基础链路跑通，再考虑扩展。具体到 OpenClaw 2.0 上的配置，有些版本支持通过管理界面点选配置，有些版本必须改 yaml 文件，你先确认自己拉取的版本是哪种。

有一个新手容易忽略的点：OpenClaw 容器里的时钟和时区。如果你启动容器后日志时间不对，很多定时任务、调度逻辑会判断失误。可以在 docker run 命令里加环境变量 TZ=Asia/Shanghai ，或者通过 docker-compose 的 environment 配置项指定。

4.4 启动后的验证清单

启动完成不代表万事大吉，我每次新装完都会按这个清单过一遍：

1. 访问 Web 界面或命令行交互界面，能正常响应。
2. 用一句话任务测试模型连通性，比如“你好，介绍一下你自己”，确认模型返回结果。
3. 尝试让 OpenClaw 执行一个简单的多步任务，比如“搜索一个话题并整理要点”，观察日志中智能体是否按步骤执行、是否有报错。
4. 确认数据目录有写入，说明容器内的数据持久化正常。
5. 重启 Docker Desktop 后容器能自动恢复（取决于 docker-compose 的 restart 策略），或者你手动启动一次确认没有严重 bug。

如果第 2 步就卡住，绝大多数时候问题都出在 API Key 填错、模型名不对、网络不通这三件事上。按“日志优先”原则去查，OpenClaw 日志会明确告诉你请求发到哪个地址、返回什么错误。

5. 常见问题与排查技巧实录

5.1 安装过程高频报错速查表

5.2 我踩过的三个 Windows 专属坑

坑一：文件路径里的反斜杠

在 Windows 上执行 docker run 挂载目录时，我一开始用的是 PowerShell 原生写法 -v D:\OpenClaw\data:/data ，结果 Docker 把反斜杠当成了转义字符，容器里看到的路径完全不对。解决办法是改用正斜杠 D:/OpenClaw/data ，或者用 Git Bash 里的 /d/OpenClaw/data 写法。如果你用 docker-compose，yaml 文件里路径统一用正斜杠。

坑二：杀毒软件拦截 WSL 虚拟化

我在一台装了第三方安全软件的机器上装 Docker，WSL2 始终无法启动，日志里报告虚拟化平台无法启用。关掉安全软件的“虚拟化保护”功能后立刻就好了。这类问题很难排查，因为提示信息往往不清楚，如果你确认 BIOS 虚拟化已开启但 WSL 还是不行，优先怀疑安全软件。

坑三：中文用户名导致挂载失败

如果你的 Windows 用户名是中文（比如 C:\Users\张三 ），Docker Desktop 在挂载某些目录时会出现编码问题。这个没有绝对通用的解决方法，但有两个临时规避手段：一是把工作目录放在纯英文路径下（比如 D:\Tools\OpenClaw ），二是用 WSL 内部的文件系统存放 OpenClaw 数据，路径像 /home/你的用户名/openclaw-data ，Windows 侧的路径只在必要时挂载。

5.3 升级与卸载要留个心眼

OpenClaw 迭代快，升级前先备份数据目录。如果你是用 docker compose 拉取的仓库，升级流程是：进入仓库目录，执行 git pull 拉最新代码，然后 docker compose down ，再 docker compose build 和 docker compose up -d 。如果你用的是官方镜像，直接 docker pull 最新tag ，然后 recreate 容器即可。

卸载 OpenClaw 有几个步骤容易漏：

1. 停止并删除容器： docker compose down ，如果用了 docker run，则 docker stop openclaw && docker rm openclaw 。
2. 删除镜像： docker rmi openclaw镜像名 ，节省磁盘空间。
3. 删除数据目录：确认数据不需要了再删，OpenClaw 的所有配置、日志、技能数据都在这个目录里，删除不可恢复。
4. 可选清理 WSL 发行版：如果你确定不再用 WSL，可以在 PowerShell 执行 wsl --unregister Ubuntu ，这会删除整个 WSL 文件系统，操作不可逆，先想清楚。
5. Docker Desktop 卸载就走 Windows 设置里的应用卸载，卸载后有余留文件，可以用官网提供的清理脚本或手动删除 %APPDATA%\Docker 之类的残留目录。

5.4 在 Windows 上扩展 OpenClaw 的经验顺序

装完能跑只是开始。如果你想让 OpenClaw 真正干活，建议按这个顺序往里加东西：

先加技能（skills）。打开技能市场或按官方文档安装示例技能，比如搜索、文档处理、任务规划类。注意每个技能可能依赖额外的 Python 包或命令行工具，技能装完要在 OpenClaw 的环境里确认依赖可用，否则运行时会报“工具不存在”。

再加外设能力。热搜里提到的“cau computer”应该是指 computer use 类功能，也就是让智能体操作电脑。在 Windows 上做这件事要谨慎，OpenClaw 容器默认跑在 Linux 环境里，它要通过 WSL 才能操作 Windows 桌面，这里面涉及权限、显式授权、界面识别准确性等一系列话题。建议先在一台不重要的电脑或虚拟机上验证，不要直接在生产或主力机上放开。

最后再碰多智能体编排。OpenClaw 的核心卖点就是多智能体协作，但多智能体意味着更多的参数、更多需要调教的 prompt、更多的错误排查复杂度。先让单个智能体把一条任务链路跑顺，再复制出第二个、第三个，让他们协作。

6. 写在最后：我的实际使用体会

OpenClaw 在 Windows 上安装这件事，说难不难，说简单也不简单。难的地方在于它把 WSL2、Docker、Git、模型服务四件事串在一起，任何一个环节出了岔子，表面症状都可能差不多——容器起不来、日志报错、界面空白，排查起来需要一点耐心。简单的地方在于，只要按顺序走，每一步的目标都很明确，你不是在“撞运气”，而是在验证一个链条上的每一环。

我个人在实际使用中的体会是：Windows 上最容易出错的时间点，恰恰不是 OpenClaw 本身，而是它的前置依赖安装。WSL2 的内核更新、Docker Desktop 的 WSL Integration 勾选、镜像加速配置这三件事，你只要按本文顺序走一遍，后面几乎不会再遇到安装层面的坑。反过来，如果你跳过这些直接去跑安装脚本，出了问题反而会绕一大圈。

最后再分享一个没用但在关键时刻能救命的小技巧：OpenClaw 容器日志是可以持久化的。docker-compose 里配置 logging 参数，把日志输出到文件，或者用 docker logs > 日志文件.log 重定向。当你的智能体任务跑了很久之后突然失败，翻日志能定位到哪一步出了问题，比盯着界面看转圈有用得多。

按这套流程装下来的 OpenClaw，后续扩展技能、接不同的模型服务、做多智能体编排，都有了一个稳固的底座。剩下的事情，就是在实际任务里慢慢调教了。