先说一句如果 OpenClaw 这个名字对你还比较陌生那这篇文章其实更适合你先往下看两分钟。这是一个开源的、本地优先的个人 AI 助手框架接入大模型之后它能在你授权的范围内管理文件、执行自动化任务、定时跑流程甚至通过技能机制把各种工作流串起来。关键数据默认留在自己机器上不少人是冲着这一点才愿意折腾它的。但这东西的官方安装文档第一优先级向来是 macOS 和 Linux。Windows 用户想装通最顺的路子基本是走 Docker而 Docker 在 Windows 上又绕不开 WSL2 和虚拟化这一整套东西。更要命的是Win11 家庭版没有 Hyper-V 管理器控制面板里很多启用或关闭 Windows 功能的选项跟专业版完全不一样网上翻到的教程十有八九是按专业版写的照做根本找不到那个入口。标题里家庭版三个字的分量就体现在这里了。这篇文章把我自己在家庭版 Win11 上完整装通 OpenClaw 的过程、选路逻辑、以及踩过的坑全写清楚。适合两类人一类是从没开过 WSL2 的纯新手另一类是在专业版教程里绕来绕去没成功、想搞清楚家庭版到底哪里不同的人。1. OpenClaw 是什么家庭版 Win11 装它为什么绕路1.1 它解决的问题一句话说清OpenClaw 不是那种聊天机器人套壳的本地包。它的定位更接近一个常驻后台的个人自动化中枢你给它配好大模型后端它就能读取你指定的目录、按计划执行任务、调用各种服务的接口并且通过一套技能体系把重复性工作变成可复用的流程。举个我实际用它的场景我会让它定时整理某个文件夹里的下载文件按扩展名和日期分门别类也会让它每天汇总几个 RSS 源和本地笔记里的新增内容生成一份简报放在指定目录。这些事如果全用脚本写得维护一堆 crontab 和乱七八糟的依赖换成 OpenClaw 之后大部分逻辑可以用自然语言描述它自己调度工具去完成。它的另一个特点是本地优先。你的文档、配置、任务记录都存在本地不会被默认同步到某家云厂商的服务器上。这一点对数据敏感的场景很重要也是很多人宁可折腾 Docker 也不愿意用现成云服务的原因。1.2 为什么不能像普通软件一样双击安装这要从 OpenClaw 的技术形态说起。核心服务是用 Elixir / Phoenix 写的跑起来需要一个完整的 Erlang 虚拟机环境还要连一个 PostgreSQL 数据库来做持久化。这种结构天然面向服务器环境官方最省事的交付方式就是打包成容器镜像而不是提供一个 Windows 安装包。你非要绕开 Docker 直接跑源码也不是不行但得自己装 Elixir、Erlang、Postgres还要处理版本兼容和编译问题。Windows 原生跑 Elixir 的体验又很一般很多依赖编译不过。所以对绝大多数人来说用 Docker 是最稳的方案。可是 Docker Desktop 在 Windows 上并不是独立运行的——它的引擎要跑在 Linux 环境里。这就引出了 WSL2。简单理解就是Docker Desktop 把真正的容器环境放在 WSL2 的轻量虚拟机里Windows 侧只保留图形界面和命令行接口。而 WSL2 在家庭版 Win11 上是完整体支持的这一步走通后面就顺了。1.3 三条安装路线的取舍我实际比较下来可行路线其实有三条适合不同的人路线操作难度适合场景主要代价Docker Desktop WSL2中等大多数人图省事、要稳定Docker Desktop 占内存开机自启需要配置WSL 里源码安装偏高想改代码、不想装 Docker编译时间长依赖坑多Windows 原生跑源码极高基本不推荐编译失败率高环境兼容性差我最终选的是第一条。先把 WSL2 和 Ubuntu 装好再让 Docker Desktop 用 WSL2 做后端最后拉 OpenClaw 镜像跑容器。下面每一步我都会拆开讲包括那些官方文档里没写清楚、但我实际卡过的地方。2. 家庭版 Win11 的 WSL2 启用全流程2.1 动手之前先检查两件事第一件事是确认系统版本。Win11 家庭版的 WSL 功能在 21H2 之后就已经是完整可用的了理论上不存在家庭版不能开 WSL的问题。但还是建议你先按Win R输入winver看一眼版本号太老的版本建议先把 Windows 更新打完再继续。第二件事是确认 CPU 虚拟化已经开启。这一步很多人会忽略因为平时根本用不到。打开任务管理器切到性能标签看右下角的虚拟化状态。如果显示已启用直接跳过如果显示已禁用那就要进 BIOS 去找 Intel VT-x 或者 AMD SVM 的开关打开之后保存重启。这一步不做后面wsl --install会卡得你怀疑人生。提示有些笔记本厂商默认在 BIOS 里把虚拟化关了尤其是老款商务机。我见过不只一次因为这一步卡住用户以为 WSL 坏了其实是 BIOS 层面没开。2.2 一行命令把 WSL 和 Ubuntu 一起装上确认上面两件事之后以管理员身份打开 PowerShell 或 Windows Terminal执行wsl --install这一条命令会把 WSL 核心组件、虚拟机平台以及默认的 Ubuntu 发行版一次性装好。装的过程中会提示你重启计算机照做就是。重启之后系统会自动弹出 Ubuntu 的初始化窗口让你设置用户名和密码。如果你不想用默认发行版可以先用wsl --install --no-distribution只装组件然后单独指定发行版wsl --install -d Ubuntu-24.04命令里的发行版名称可以先用wsl --list --online看支持列表。家庭版和专业版在这边的行为没有差别这也算是虚拟化功能之外微软把 WSL 做成普通可选功能之后最大的红利。2.3 装完别急着走三项检查缺一不可重启并设置完 Ubuntu 之后先做三个检查确认环境是干净的第一确认默认 WSL 版本是 2 而不是 1。在 PowerShell 里执行wsl -l -v如果看到 VERSION 那一列是 2说明没问题。如果是 1执行wsl --set-default-version 2再把发行版重新设置一下。第二确认 WSL 内核是最新的。执行wsl --update这一步能避免很多莫名其妙的兼容问题。WSL 更新完之后建议再执行一次wsl --shutdown让内核重新加载。第三确认发行版里的 systemd 是开启状态。进入 Ubuntu 终端执行systemctl status如果输出里有System is running或者能正常显示服务列表说明 systemd 是好的。某些老版本 WSL 默认不开 systemdDocker 在里面的行为会变得很奇怪所以必须确认。2.4 家庭版没有 Hyper-V 管理器影响到底有多大这是家庭版用户最容易焦虑的问题。网上很多教程让你去控制面板 - 程序 - 启用或关闭 Windows 功能里勾选Hyper-V但你在家庭版里翻遍整个列表都找不到这一项——Hyper-V 管理器是专业版及以上才提供的图形化管理工具。但实际上WSL2 用的是它自己的一套轻量虚拟化平台不依赖 Hyper-V 管理器也不要求你去手动构建虚拟机。Docker Desktop 的 WSL2 后端同样基于这套平台。所以结论是你在家庭版里看不到 Hyper-V 管理器完全不影响 WSL2 和 Docker 的正常使用别再为了这个去折腾 Enable-WindowsOptionalFeature 之类的东西了。3. Docker Desktop 接入 WSL2 后端3.1 安装时容易被忽略的两个选项去 Docker 官网下载 Docker Desktop for Windows安装包很大下载慢是正常的。安装过程中两步要特别注意。第一步安装向导里会问你用 Windows 容器还是 WSL 2 后端务必选 WSL 2。第二次如果手快选错后面也可以在设置里改回来但安装时就选对能省不少事。第二步安装完成后首次启动Docker Desktop 会弹一个登录窗口。它不是强制项可以跳过。这一步我当时没跳过白花了几分钟注册一个基本不用的账号。跳过登录不影响本地构建和运行容器。启动之后如果没有意外右下角状态栏会出现 Docker 的鲸鱼图标。如果显示的是类似 Docker Engine Stopped 的状态先别慌多数情况下是 WSL 集成没配好往下看。3.2 把 Ubuntu 加进 Docker 的资源池Docker Desktop 默认会自动使用它自己创建的 WSL 发行版作为后端。但为了让容器和你的 Ubuntu 共享同一套网络和文件系统我建议手动把 Ubuntu 加进集成列表。打开 Docker Desktop进入 Settings设置找到 Resources再进 WSL Integration。你会看到一个Enable integration with my default WSL distro的开关打开它然后在下方的列表里把 Ubuntu 那一项也勾上。点击 Apply Restart。这一步做完你的 Ubuntu 终端里就能直接执行docker命令了而不需要每次都在 Windows 的 PowerShell 里操作。这一步对后面查看容器日志、进入容器做排查特别有用因为你会发现很多教程给的命令都是 Linux 风格的。提示如果 WSL Integration 列表里看不到 Ubuntu说明你的 WSL 发行版没有正确注册。回 PowerShell 执行wsl -l -v确认发行版存在再在 Docker 设置里点一下刷新。3.3 验证 Docker 环境hello-world 只是开始配好之后先跑一个最简单的验证。在 Ubuntu 终端里执行docker run --rm hello-world能正常打印出 Hello from Docker 就算通了。但说实话hello-world 的通过率很高它验证不了多少东西。我更建议再跑一个真正能在 Linux 容器里工作的测试docker run --rm -it ubuntu:latest uname -a如果能看到Linux开头的内核信息说明你的容器跑在真正的 Linux 内核之上而不是 Windows 模拟出来的什么奇怪东西。这一步很重要因为 OpenClaw 容器对 Linux 内核的用户态特性有一定依赖内核不对会直接启动失败。3.4 镜像拉取速度的通用处理Docker 默认的镜像源在海外实际拉取速度取决于你的网络状况。如果你发现docker pull慢到不能忍通用的做法是在 Docker Desktop 的 Settings 里找到 Docker Engine 的配置把 registry mirror 加上你自己的镜像加速地址。配置文件是 JSON 格式类似这样{ registry-mirrors: [https://你的镜像加速地址] }改完点 Apply Restart 让 Docker 引擎重新加载。这里我不打算推荐某个具体地址因为可用性经常变你去找自己云服务商或者网络服务商提供的 Docker 镜像加速就行。4. 部署 OpenClaw 容器从拉取镜像到打开控制台4.1 先理解官方命令里的两个参数OpenClaw 的官方文档里最基础的启动命令大致长这样docker run --name openclaw -p 18789:18789 -it ghcr.io/你的镜像地址/openclaw具体镜像地址以你安装当下的官方文档为准。我这边要强调的是命令里两个关键参数的意思搞懂它们你后面才不至于乱挂载。-p 18789:18789是把容器内部 18789 端口映射到宿主机同样端口。前面是宿主机端口可以改后面是容器内部端口不要动。这个端口是 OpenClaw 控制台 Web UI 的默认入口启动后浏览器访问http://localhost:18789就能打开。-it表示以交互模式运行如果只是后台跑服务可以改用-d。我建议第一次启动用-it这样你能直接在前台看到日志输出第一时间判断有没有启动失败。确认一切正常之后再改用后台方式。4.2 数据持久化别让容器一删就丢OpenClaw 运行过程中会产生配置、任务记录、日志等数据。如果你用上面那种最简命令启动这些数据会直接写进容器的可写层一旦容器被删除数据就全没了。正确做法是把数据目录挂载到宿主机。我会先建一个工作目录mkdir -p ~/openclaw-data然后在启动命令里加-v参数docker run --name openclaw -d -p 18789:18789 -v ~/openclaw-data:/app/data ghcr.io/你的镜像地址/openclaw挂载路径以后台文档为准有的版本是/root/.claw有的版本是/app/data。你只要记住核心思路容器内数据目录映射到宿主机固定路径这样升级镜像、重建容器都不会丢数据。我实际用下来还有一层感受挂了宿主机目录之后你可以直接在 Windows 里用资源管理器打开\\wsl$\Ubuntu\home\你的用户名\openclaw-data查看备份文件不需要进容器折腾排查问题方便很多。4.3 启动、看日志、打开控制台执行启动命令之后先用docker ps看容器状态。如果 STATUS 显示 Up端口能正常映射那就可以直接打开浏览器访问http://localhost:18789。如果容器一直在Restarting或者状态显示Exited不要瞎猜先看日志docker logs openclaw日志是排查一切问题的第一入口。常见的启动失败原因包括数据库连接不上如果你用了外部 Postgres、环境变量缺失、或者端口被占用。日志里都会明确写出来。第一次打开控制台你大概率会看到一个引导页面让你配置大模型后端。这一步做完OpenClaw 才能开始真正干活。4.4 首次使用给 OpenClaw 配一个大模型后端OpenClaw 本身不带模型它需要对接一个大模型服务。官方支持市面上主流的模型服务商也支持接入本地模型。配置方式一般是两种一种是在控制台界面里填 API Key 和模型名称另一种是通过环境变量注入。如果你用的是云服务商的模型 API就在环境变量里把对应的 Key 传进去比如docker run --name openclaw -d \ -p 18789:18789 \ -v ~/openclaw-data:/app/data \ -e OPENAI_API_KEY你的密钥 \ -e OPENAI_MODELgpt-4o-mini \ ghcr.io/你的镜像地址/openclaw注意API Key 这类敏感信息最好通过环境变量传而不是直接写进启动脚本或者 compose 文件里。尤其是 docker-compose.yaml 这种可能被提交到 Git 仓库的文件一旦泄露就很麻烦。如果你想完全本地化可以提前用 Ollama 跑一个本地模型然后在 OpenClaw 的配置里指向 Ollama 的服务地址。这样你的所有请求都不出本机隐私保护最彻底代价是响应速度和质量取决于你的硬件。5. 不想用 Docker在 WSL 里源码跑 OpenClaw5.1 什么人适合源码路线Docker 方案虽然省心但并不是所有人都愿意装 Docker Desktop。它吃内存是真的——启动之后动辄占用一两个 G 的内存对只有 8G 内存的机器来说很肉疼。另外如果你想改 OpenClaw 的代码、自己加技能或者只是想更清楚它里面到底是怎么跑的源码路线更适合你。源码路线的思路是把 WSL2 里的 Ubuntu 当成一台真正的 Linux 服务器在上面装齐依赖然后直接跑 OpenClaw 的 Elixir 项目。5.2 在 Ubuntu 里装 Elixir、Erlang 和 PostgreSQL进到 Ubuntu 终端先更新包管理器sudo apt update sudo apt upgrade -y然后安装基础依赖。Elixir 和 Erlang 的版本建议参照 OpenClaw 项目里的版本要求文档用预编译包或者版本管理器装都行。最快的省事方案是直接用系统包管理器sudo apt install -y elixir erlang-dev erlang-xmerl postgresql git build-essential装完确认版本elixir --version psql --versionPostgreSQL 装好之后要启动服务并创建数据库用户。Debian/Ubuntu 系的 Postgres 默认用peer认证你需要先切换到 postgres 系统用户去建库建账号然后设置好密码这样 Elixir 应用才能通过 TCP 连上。5.3 拉代码、装依赖、初始化数据库接下来克隆项目代码git clone 你的OpenClaw仓库地址 cd openclawElixir 项目的第一步是拉取 Hex 和 Rebarmix local.hex --force mix local.rebar --force然后安装项目依赖mix deps.get这个步骤会拉很多依赖包网络慢的话需要耐心等。装完之后项目一般会提供一个初始化脚本mix setup它会创建数据库、执行迁移、写入初始配置。如果报数据库连接错误基本就是上一步的 Postgres 账号密码或者数据库名没有配置对。项目根目录下通常有个.env.example或者config/dev.exs可以参考里面有数据库连接和其他初始配置的格式。5.4 跑起来的完整动作初始化完成之后启动开发服务器mix phx.server看到类似Running OpenClaw web server on http://localhost:4000的日志就是成功了。整条命令如果用 nohup 或者 tmux 挂后台可以保持 WSL 会话关闭之后服务继续运行——不过说实话我更推荐用 Docker 来做常驻服务源码模式更适合开发和调试。源码模式最大的好处是你可以直接改技能代码、改界面、加日志每次改完代码它会自动重载这对想深入定制的人来说价值很大。6. 安装过程中的高频坑与排查思路6.1 wsl --install 卡住或报 0x8007019e这个错误代码我在不止一台机器上见过。它的含义通常是这台机器的虚拟化没有开启或者缺少必要的系统更新。排查思路按顺序来先回任务管理器确认虚拟化状态。如果是已禁用进 BIOS 打开 VT-x 或 SVM。如果虚拟化已经启用那就是系统更新问题——去 Windows 更新里把可选更新里的 WSL 相关补丁装上或者手动执行wsl --update再关掉所有终端重开一次。6.2 Docker Desktop 启动后一直显示 Engine Stopped这是一个非常经典的家庭版问题现象。原因多半是 Docker Desktop 没能正确连接 WSL2 后端。排查链路是这样的先确认 WSL 发行版是否在线在 PowerShell 里跑wsl -l -v如果状态是 Stopped先wsl --shutdown再重新启动一个 Ubuntu 会话。然后打开 Docker Desktop 的 Settings重新确认 WSL Integration 里的开关特别是Enable integration with my default WSL distro这一项。最后去 Docker 的 Troubleshoot 页面执行清理重启。如果依然不行可以试一下关闭 Docker Desktop 的基于 WSL2 的引擎再重新打开强制它重新初始化后端。6.3 容器起来了但网页打不开进程状态是 Up端口映射也看到 18789但浏览器访问http://localhost:18789就是转圈或者拒绝连接。先检查映射是不是真的生效。执行docker ps看 PORTS 一列。如果显示0.0.0.0:18789-18789/tcp说明映射没问题。那问题大概率出在 Windows 防火墙或者 WSL 的网络转发上。可以先在 WSL 里直接访问容器内部地址测试curl http://localhost:18789如果在 WSL 里能通、Windows 里不通那基本是防火墙拦截了宿主机访问。去 Windows Defender 防火墙里加一条允许 18789 端口的入站规则或者临时关闭防火墙测试定位之后再加规则。6.4 家庭版特有的权限问题家庭版没有本地组策略编辑器很多时候你会感觉系统设置项少了一块。但在 OpenClaw 安装这件事上主要权限问题集中在 Docker 和 WSL 的访问权上。比如你在 PowerShell 里执行docker命令如果提示权限不足是因为当前用户不在docker-users组里。去计算机管理 - 本地用户和组 - 组里把当前 Windows 用户加进 docker-users 组然后重新登录一次。再比如 WSL 里 Ubuntu 的文件访问权限。Windows 侧的 C 盘会被自动挂载到/mnt/c如果你想让 OpenClaw 读取 Windows 桌面上的文件路径要写成/mnt/c/Users/你的用户名/Desktop。这里面经常出现权限拒绝的问题因为 WSL 访问 Linux 文件系统时默认权限映射不一定跟你 Windows 侧的账户一致。6.5 我最后的选择和建议折腾完这三条路线我个人最终把日常服务放在 Docker 上源码仓库只是用来学习和改技能。Docker 方案的优点是真的不折腾容器的环境变量、数据挂载、端口映射都清清楚楚。源码模式我留着做实验改坏了不影响主服务。如果你现在正准备在家庭版 Win11 上装 OpenClaw我建议直接走WSL2 Docker Desktop 容器这条路别去想什么原生跑源码的事。家庭版缺的只是 Hyper-V 管理器那个图形界面实际用到的东西一样都不少。最后分享一个我踩过几次坑之后学到的习惯每次更新 OpenClaw 镜像之前先把~/openclaw-data整个目录备份一次。这个目录里存着你所有的配置和任务记录备份一下只需要几秒钟但能让你在升级翻车之后十秒钟回到原状。折腾这类本地优先的工具数据安全永远比功能新版本重要。 
长河君 · 2026/10/15 20:30:41 · 阅读 1.2k Win11家庭版装OpenClaw：WSL2+Docker完整避坑指南
先说一句如果 OpenClaw 这个名字对你还比较陌生那这篇文章其实更适合你先往下看两分钟。这是一个开源的、本地优先的个人 AI 助手框架接入大模型之后它能在你授权的范围内管理文件、执行自动化任务、定时跑流程甚至通过技能机制把各种工作流串起来。关键数据默认留在自己机器上不少人是冲着这一点才愿意折腾它的。但这东西的官方安装文档第一优先级向来是 macOS 和 Linux。Windows 用户想装通最顺的路子基本是走 Docker而 Docker 在 Windows 上又绕不开 WSL2 和虚拟化这一整套东西。更要命的是Win11 家庭版没有 Hyper-V 管理器控制面板里很多启用或关闭 Windows 功能的选项跟专业版完全不一样网上翻到的教程十有八九是按专业版写的照做根本找不到那个入口。标题里家庭版三个字的分量就体现在这里了。这篇文章把我自己在家庭版 Win11 上完整装通 OpenClaw 的过程、选路逻辑、以及踩过的坑全写清楚。适合两类人一类是从没开过 WSL2 的纯新手另一类是在专业版教程里绕来绕去没成功、想搞清楚家庭版到底哪里不同的人。1. OpenClaw 是什么家庭版 Win11 装它为什么绕路1.1 它解决的问题一句话说清OpenClaw 不是那种聊天机器人套壳的本地包。它的定位更接近一个常驻后台的个人自动化中枢你给它配好大模型后端它就能读取你指定的目录、按计划执行任务、调用各种服务的接口并且通过一套技能体系把重复性工作变成可复用的流程。举个我实际用它的场景我会让它定时整理某个文件夹里的下载文件按扩展名和日期分门别类也会让它每天汇总几个 RSS 源和本地笔记里的新增内容生成一份简报放在指定目录。这些事如果全用脚本写得维护一堆 crontab 和乱七八糟的依赖换成 OpenClaw 之后大部分逻辑可以用自然语言描述它自己调度工具去完成。它的另一个特点是本地优先。你的文档、配置、任务记录都存在本地不会被默认同步到某家云厂商的服务器上。这一点对数据敏感的场景很重要也是很多人宁可折腾 Docker 也不愿意用现成云服务的原因。1.2 为什么不能像普通软件一样双击安装这要从 OpenClaw 的技术形态说起。核心服务是用 Elixir / Phoenix 写的跑起来需要一个完整的 Erlang 虚拟机环境还要连一个 PostgreSQL 数据库来做持久化。这种结构天然面向服务器环境官方最省事的交付方式就是打包成容器镜像而不是提供一个 Windows 安装包。你非要绕开 Docker 直接跑源码也不是不行但得自己装 Elixir、Erlang、Postgres还要处理版本兼容和编译问题。Windows 原生跑 Elixir 的体验又很一般很多依赖编译不过。所以对绝大多数人来说用 Docker 是最稳的方案。可是 Docker Desktop 在 Windows 上并不是独立运行的——它的引擎要跑在 Linux 环境里。这就引出了 WSL2。简单理解就是Docker Desktop 把真正的容器环境放在 WSL2 的轻量虚拟机里Windows 侧只保留图形界面和命令行接口。而 WSL2 在家庭版 Win11 上是完整体支持的这一步走通后面就顺了。1.3 三条安装路线的取舍我实际比较下来可行路线其实有三条适合不同的人路线操作难度适合场景主要代价Docker Desktop WSL2中等大多数人图省事、要稳定Docker Desktop 占内存开机自启需要配置WSL 里源码安装偏高想改代码、不想装 Docker编译时间长依赖坑多Windows 原生跑源码极高基本不推荐编译失败率高环境兼容性差我最终选的是第一条。先把 WSL2 和 Ubuntu 装好再让 Docker Desktop 用 WSL2 做后端最后拉 OpenClaw 镜像跑容器。下面每一步我都会拆开讲包括那些官方文档里没写清楚、但我实际卡过的地方。2. 家庭版 Win11 的 WSL2 启用全流程2.1 动手之前先检查两件事第一件事是确认系统版本。Win11 家庭版的 WSL 功能在 21H2 之后就已经是完整可用的了理论上不存在家庭版不能开 WSL的问题。但还是建议你先按Win R输入winver看一眼版本号太老的版本建议先把 Windows 更新打完再继续。第二件事是确认 CPU 虚拟化已经开启。这一步很多人会忽略因为平时根本用不到。打开任务管理器切到性能标签看右下角的虚拟化状态。如果显示已启用直接跳过如果显示已禁用那就要进 BIOS 去找 Intel VT-x 或者 AMD SVM 的开关打开之后保存重启。这一步不做后面wsl --install会卡得你怀疑人生。提示有些笔记本厂商默认在 BIOS 里把虚拟化关了尤其是老款商务机。我见过不只一次因为这一步卡住用户以为 WSL 坏了其实是 BIOS 层面没开。2.2 一行命令把 WSL 和 Ubuntu 一起装上确认上面两件事之后以管理员身份打开 PowerShell 或 Windows Terminal执行wsl --install这一条命令会把 WSL 核心组件、虚拟机平台以及默认的 Ubuntu 发行版一次性装好。装的过程中会提示你重启计算机照做就是。重启之后系统会自动弹出 Ubuntu 的初始化窗口让你设置用户名和密码。如果你不想用默认发行版可以先用wsl --install --no-distribution只装组件然后单独指定发行版wsl --install -d Ubuntu-24.04命令里的发行版名称可以先用wsl --list --online看支持列表。家庭版和专业版在这边的行为没有差别这也算是虚拟化功能之外微软把 WSL 做成普通可选功能之后最大的红利。2.3 装完别急着走三项检查缺一不可重启并设置完 Ubuntu 之后先做三个检查确认环境是干净的第一确认默认 WSL 版本是 2 而不是 1。在 PowerShell 里执行wsl -l -v如果看到 VERSION 那一列是 2说明没问题。如果是 1执行wsl --set-default-version 2再把发行版重新设置一下。第二确认 WSL 内核是最新的。执行wsl --update这一步能避免很多莫名其妙的兼容问题。WSL 更新完之后建议再执行一次wsl --shutdown让内核重新加载。第三确认发行版里的 systemd 是开启状态。进入 Ubuntu 终端执行systemctl status如果输出里有System is running或者能正常显示服务列表说明 systemd 是好的。某些老版本 WSL 默认不开 systemdDocker 在里面的行为会变得很奇怪所以必须确认。2.4 家庭版没有 Hyper-V 管理器影响到底有多大这是家庭版用户最容易焦虑的问题。网上很多教程让你去控制面板 - 程序 - 启用或关闭 Windows 功能里勾选Hyper-V但你在家庭版里翻遍整个列表都找不到这一项——Hyper-V 管理器是专业版及以上才提供的图形化管理工具。但实际上WSL2 用的是它自己的一套轻量虚拟化平台不依赖 Hyper-V 管理器也不要求你去手动构建虚拟机。Docker Desktop 的 WSL2 后端同样基于这套平台。所以结论是你在家庭版里看不到 Hyper-V 管理器完全不影响 WSL2 和 Docker 的正常使用别再为了这个去折腾 Enable-WindowsOptionalFeature 之类的东西了。3. Docker Desktop 接入 WSL2 后端3.1 安装时容易被忽略的两个选项去 Docker 官网下载 Docker Desktop for Windows安装包很大下载慢是正常的。安装过程中两步要特别注意。第一步安装向导里会问你用 Windows 容器还是 WSL 2 后端务必选 WSL 2。第二次如果手快选错后面也可以在设置里改回来但安装时就选对能省不少事。第二步安装完成后首次启动Docker Desktop 会弹一个登录窗口。它不是强制项可以跳过。这一步我当时没跳过白花了几分钟注册一个基本不用的账号。跳过登录不影响本地构建和运行容器。启动之后如果没有意外右下角状态栏会出现 Docker 的鲸鱼图标。如果显示的是类似 Docker Engine Stopped 的状态先别慌多数情况下是 WSL 集成没配好往下看。3.2 把 Ubuntu 加进 Docker 的资源池Docker Desktop 默认会自动使用它自己创建的 WSL 发行版作为后端。但为了让容器和你的 Ubuntu 共享同一套网络和文件系统我建议手动把 Ubuntu 加进集成列表。打开 Docker Desktop进入 Settings设置找到 Resources再进 WSL Integration。你会看到一个Enable integration with my default WSL distro的开关打开它然后在下方的列表里把 Ubuntu 那一项也勾上。点击 Apply Restart。这一步做完你的 Ubuntu 终端里就能直接执行docker命令了而不需要每次都在 Windows 的 PowerShell 里操作。这一步对后面查看容器日志、进入容器做排查特别有用因为你会发现很多教程给的命令都是 Linux 风格的。提示如果 WSL Integration 列表里看不到 Ubuntu说明你的 WSL 发行版没有正确注册。回 PowerShell 执行wsl -l -v确认发行版存在再在 Docker 设置里点一下刷新。3.3 验证 Docker 环境hello-world 只是开始配好之后先跑一个最简单的验证。在 Ubuntu 终端里执行docker run --rm hello-world能正常打印出 Hello from Docker 就算通了。但说实话hello-world 的通过率很高它验证不了多少东西。我更建议再跑一个真正能在 Linux 容器里工作的测试docker run --rm -it ubuntu:latest uname -a如果能看到Linux开头的内核信息说明你的容器跑在真正的 Linux 内核之上而不是 Windows 模拟出来的什么奇怪东西。这一步很重要因为 OpenClaw 容器对 Linux 内核的用户态特性有一定依赖内核不对会直接启动失败。3.4 镜像拉取速度的通用处理Docker 默认的镜像源在海外实际拉取速度取决于你的网络状况。如果你发现docker pull慢到不能忍通用的做法是在 Docker Desktop 的 Settings 里找到 Docker Engine 的配置把 registry mirror 加上你自己的镜像加速地址。配置文件是 JSON 格式类似这样{ registry-mirrors: [https://你的镜像加速地址] }改完点 Apply Restart 让 Docker 引擎重新加载。这里我不打算推荐某个具体地址因为可用性经常变你去找自己云服务商或者网络服务商提供的 Docker 镜像加速就行。4. 部署 OpenClaw 容器从拉取镜像到打开控制台4.1 先理解官方命令里的两个参数OpenClaw 的官方文档里最基础的启动命令大致长这样docker run --name openclaw -p 18789:18789 -it ghcr.io/你的镜像地址/openclaw具体镜像地址以你安装当下的官方文档为准。我这边要强调的是命令里两个关键参数的意思搞懂它们你后面才不至于乱挂载。-p 18789:18789是把容器内部 18789 端口映射到宿主机同样端口。前面是宿主机端口可以改后面是容器内部端口不要动。这个端口是 OpenClaw 控制台 Web UI 的默认入口启动后浏览器访问http://localhost:18789就能打开。-it表示以交互模式运行如果只是后台跑服务可以改用-d。我建议第一次启动用-it这样你能直接在前台看到日志输出第一时间判断有没有启动失败。确认一切正常之后再改用后台方式。4.2 数据持久化别让容器一删就丢OpenClaw 运行过程中会产生配置、任务记录、日志等数据。如果你用上面那种最简命令启动这些数据会直接写进容器的可写层一旦容器被删除数据就全没了。正确做法是把数据目录挂载到宿主机。我会先建一个工作目录mkdir -p ~/openclaw-data然后在启动命令里加-v参数docker run --name openclaw -d -p 18789:18789 -v ~/openclaw-data:/app/data ghcr.io/你的镜像地址/openclaw挂载路径以后台文档为准有的版本是/root/.claw有的版本是/app/data。你只要记住核心思路容器内数据目录映射到宿主机固定路径这样升级镜像、重建容器都不会丢数据。我实际用下来还有一层感受挂了宿主机目录之后你可以直接在 Windows 里用资源管理器打开\\wsl$\Ubuntu\home\你的用户名\openclaw-data查看备份文件不需要进容器折腾排查问题方便很多。4.3 启动、看日志、打开控制台执行启动命令之后先用docker ps看容器状态。如果 STATUS 显示 Up端口能正常映射那就可以直接打开浏览器访问http://localhost:18789。如果容器一直在Restarting或者状态显示Exited不要瞎猜先看日志docker logs openclaw日志是排查一切问题的第一入口。常见的启动失败原因包括数据库连接不上如果你用了外部 Postgres、环境变量缺失、或者端口被占用。日志里都会明确写出来。第一次打开控制台你大概率会看到一个引导页面让你配置大模型后端。这一步做完OpenClaw 才能开始真正干活。4.4 首次使用给 OpenClaw 配一个大模型后端OpenClaw 本身不带模型它需要对接一个大模型服务。官方支持市面上主流的模型服务商也支持接入本地模型。配置方式一般是两种一种是在控制台界面里填 API Key 和模型名称另一种是通过环境变量注入。如果你用的是云服务商的模型 API就在环境变量里把对应的 Key 传进去比如docker run --name openclaw -d \ -p 18789:18789 \ -v ~/openclaw-data:/app/data \ -e OPENAI_API_KEY你的密钥 \ -e OPENAI_MODELgpt-4o-mini \ ghcr.io/你的镜像地址/openclaw注意API Key 这类敏感信息最好通过环境变量传而不是直接写进启动脚本或者 compose 文件里。尤其是 docker-compose.yaml 这种可能被提交到 Git 仓库的文件一旦泄露就很麻烦。如果你想完全本地化可以提前用 Ollama 跑一个本地模型然后在 OpenClaw 的配置里指向 Ollama 的服务地址。这样你的所有请求都不出本机隐私保护最彻底代价是响应速度和质量取决于你的硬件。5. 不想用 Docker在 WSL 里源码跑 OpenClaw5.1 什么人适合源码路线Docker 方案虽然省心但并不是所有人都愿意装 Docker Desktop。它吃内存是真的——启动之后动辄占用一两个 G 的内存对只有 8G 内存的机器来说很肉疼。另外如果你想改 OpenClaw 的代码、自己加技能或者只是想更清楚它里面到底是怎么跑的源码路线更适合你。源码路线的思路是把 WSL2 里的 Ubuntu 当成一台真正的 Linux 服务器在上面装齐依赖然后直接跑 OpenClaw 的 Elixir 项目。5.2 在 Ubuntu 里装 Elixir、Erlang 和 PostgreSQL进到 Ubuntu 终端先更新包管理器sudo apt update sudo apt upgrade -y然后安装基础依赖。Elixir 和 Erlang 的版本建议参照 OpenClaw 项目里的版本要求文档用预编译包或者版本管理器装都行。最快的省事方案是直接用系统包管理器sudo apt install -y elixir erlang-dev erlang-xmerl postgresql git build-essential装完确认版本elixir --version psql --versionPostgreSQL 装好之后要启动服务并创建数据库用户。Debian/Ubuntu 系的 Postgres 默认用peer认证你需要先切换到 postgres 系统用户去建库建账号然后设置好密码这样 Elixir 应用才能通过 TCP 连上。5.3 拉代码、装依赖、初始化数据库接下来克隆项目代码git clone 你的OpenClaw仓库地址 cd openclawElixir 项目的第一步是拉取 Hex 和 Rebarmix local.hex --force mix local.rebar --force然后安装项目依赖mix deps.get这个步骤会拉很多依赖包网络慢的话需要耐心等。装完之后项目一般会提供一个初始化脚本mix setup它会创建数据库、执行迁移、写入初始配置。如果报数据库连接错误基本就是上一步的 Postgres 账号密码或者数据库名没有配置对。项目根目录下通常有个.env.example或者config/dev.exs可以参考里面有数据库连接和其他初始配置的格式。5.4 跑起来的完整动作初始化完成之后启动开发服务器mix phx.server看到类似Running OpenClaw web server on http://localhost:4000的日志就是成功了。整条命令如果用 nohup 或者 tmux 挂后台可以保持 WSL 会话关闭之后服务继续运行——不过说实话我更推荐用 Docker 来做常驻服务源码模式更适合开发和调试。源码模式最大的好处是你可以直接改技能代码、改界面、加日志每次改完代码它会自动重载这对想深入定制的人来说价值很大。6. 安装过程中的高频坑与排查思路6.1 wsl --install 卡住或报 0x8007019e这个错误代码我在不止一台机器上见过。它的含义通常是这台机器的虚拟化没有开启或者缺少必要的系统更新。排查思路按顺序来先回任务管理器确认虚拟化状态。如果是已禁用进 BIOS 打开 VT-x 或 SVM。如果虚拟化已经启用那就是系统更新问题——去 Windows 更新里把可选更新里的 WSL 相关补丁装上或者手动执行wsl --update再关掉所有终端重开一次。6.2 Docker Desktop 启动后一直显示 Engine Stopped这是一个非常经典的家庭版问题现象。原因多半是 Docker Desktop 没能正确连接 WSL2 后端。排查链路是这样的先确认 WSL 发行版是否在线在 PowerShell 里跑wsl -l -v如果状态是 Stopped先wsl --shutdown再重新启动一个 Ubuntu 会话。然后打开 Docker Desktop 的 Settings重新确认 WSL Integration 里的开关特别是Enable integration with my default WSL distro这一项。最后去 Docker 的 Troubleshoot 页面执行清理重启。如果依然不行可以试一下关闭 Docker Desktop 的基于 WSL2 的引擎再重新打开强制它重新初始化后端。6.3 容器起来了但网页打不开进程状态是 Up端口映射也看到 18789但浏览器访问http://localhost:18789就是转圈或者拒绝连接。先检查映射是不是真的生效。执行docker ps看 PORTS 一列。如果显示0.0.0.0:18789-18789/tcp说明映射没问题。那问题大概率出在 Windows 防火墙或者 WSL 的网络转发上。可以先在 WSL 里直接访问容器内部地址测试curl http://localhost:18789如果在 WSL 里能通、Windows 里不通那基本是防火墙拦截了宿主机访问。去 Windows Defender 防火墙里加一条允许 18789 端口的入站规则或者临时关闭防火墙测试定位之后再加规则。6.4 家庭版特有的权限问题家庭版没有本地组策略编辑器很多时候你会感觉系统设置项少了一块。但在 OpenClaw 安装这件事上主要权限问题集中在 Docker 和 WSL 的访问权上。比如你在 PowerShell 里执行docker命令如果提示权限不足是因为当前用户不在docker-users组里。去计算机管理 - 本地用户和组 - 组里把当前 Windows 用户加进 docker-users 组然后重新登录一次。再比如 WSL 里 Ubuntu 的文件访问权限。Windows 侧的 C 盘会被自动挂载到/mnt/c如果你想让 OpenClaw 读取 Windows 桌面上的文件路径要写成/mnt/c/Users/你的用户名/Desktop。这里面经常出现权限拒绝的问题因为 WSL 访问 Linux 文件系统时默认权限映射不一定跟你 Windows 侧的账户一致。6.5 我最后的选择和建议折腾完这三条路线我个人最终把日常服务放在 Docker 上源码仓库只是用来学习和改技能。Docker 方案的优点是真的不折腾容器的环境变量、数据挂载、端口映射都清清楚楚。源码模式我留着做实验改坏了不影响主服务。如果你现在正准备在家庭版 Win11 上装 OpenClaw我建议直接走WSL2 Docker Desktop 容器这条路别去想什么原生跑源码的事。家庭版缺的只是 Hyper-V 管理器那个图形界面实际用到的东西一样都不少。最后分享一个我踩过几次坑之后学到的习惯每次更新 OpenClaw 镜像之前先把~/openclaw-data整个目录备份一次。这个目录里存着你所有的配置和任务记录备份一下只需要几秒钟但能让你在升级翻车之后十秒钟回到原状。折腾这类本地优先的工具数据安全永远比功能新版本重要。