我花了一个周末把 OpenClaw 装到主力 Windows 笔记本上前后重装了三次环境翻来覆去踩了七八个坑最后总算把整个安装和配置流程跑通了。这篇 Windows 版安装及配置避坑指南就是我那三天的完整记录。OpenClaw 本质上是一个开源的个人助理平台你可以把它理解成给电脑装了一个能听懂自然语言的中枢你告诉它“帮我整理明天的日程”“把这份文档转成 PDF 发到邮箱”它会理解你的意图再调度日历、邮箱、浏览器、文件系统这些工具去执行。它适合已经能熟练打开命令行、想用自然语言统一操控本地工具的人也适合刚接触开源自动化项目、愿意折腾但不想踩太多坑的新手。这篇教程会从环境准备讲到配置拆解再给你完整的部署命令和问题排查思路照着敲就能跑起来。1. 先搞清楚 OpenClaw 到底是什么再决定要不要装1.1 核心思路一个会调度的“管家”不是一个聊天机器人很多人在第一次接触 OpenClaw 时都会有一个误解以为它跟普通的聊天机器人差不多你问它答顶多帮你搜点资料。实际上 OpenClaw 的核心是“调度”它的底层由一个或多个大模型负责理解任务但真正干活的是一堆被封装好的工具模块。你可以把 OpenClaw 想成一个管家模型是管家的大脑工具是管家的手和脚。你只需要对管家说“帮我把明天下午三点的会议邀请发出去”管家自己会去翻日历、查联系人、起草邮件、调用邮件客户端发送。整个过程中你不需要自己去操作任何一个具体软件。这个设计带来的好处非常明显第一所有工具的调用入口统一了你不用再记每个软件的操作方式第二任务可以被组合比如“把上周的报销单据整理成一个表格再按部门分类归档”这种跨工具的流程以前要手动切换好几个应用现在一句话就能触发第三整个系统是本地优先的数据流和配置都在自己的电脑或服务器上隐私方面比全云端方案更可控。1.2 在 Windows 上安装的难点到底在哪OpenClaw 官方文档虽然提供了多种安装方式但对 Windows 用户并不算友好。官方主推 Linux 和 macOS 环境Windows 上没有那种双击下一步的傻瓜安装包。主流做法是用 Docker 跑容器而 Docker 在 Windows 上又是基于 WSL2Windows 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 是唯一值得考虑的方案。安装 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_KEYsk-xxxxxxxx TZAsia/ShanghaiOPENCLAW_API_KEY就是你在模型服务商那里申请的 KeyTZ是时区设置这里填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文件中加上TZAsia/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] memory4GB processors2 swap2GB这里的参数可以根据自己机器的配置调整。改完之后在 PowerShell 执行wsl --shutdown然后重新启动 Docker Desktop配置才会生效。这个文件很多人不知道以为 WSL2 吃内存是没法控制的其实一行配置就能解决。最后再分享一个小技巧OpenClaw 每次升级版本都可能带来配置格式的变化。我现在的习惯是每次升级前先把config.yml和.env完整备份一份再执行docker pull拉新镜像删掉旧容器重新创建。这样即使新版本出了问题也能快速回滚到上一个可用状态不至于折腾半天回到解放前。