Windows部署openclaw全攻略：从WSL2到Docker的智能体搭建实践

1. 在Windows上部署openclaw先想清楚三个问题我是在一个周五晚上决定在Windows上装openclaw的。之前一直用Linux服务器跑Agent自动化任务但家里那台主力机装着Windows 11显卡、内存、日常文件都在上面实在不想为一个小项目再开一台机器。于是就有了这次折腾折腾完之后我发现openclaw在Windows上部署不是能不能的问题而是你愿不愿意把几个坑提前踩一遍的问题。先说结论openclaw是一个面向本地化部署的智能体编排框架你可以把它理解成装了方向盘和仪表盘的Agent底座。它解决的核心问题是当你手里有多个模型渠道、多个对话入口比如飞书、Teams、本地终端和一批自动化任务时谁来做路由和调度。openclaw做的就是这件事——把大模型能力接到channel上再按你的配置去执行。在Windows上装它你会遇到三类典型问题环境依赖缺失、系统会话机制差异、WSL2与Docker的资源拉扯。这篇文章我把完整的安装过程、我遇到的报错、以及最终的稳定配置全部写出来适合想在Windows本机体验openclaw的开发者也适合准备把它接到飞书或Teams上做日常自动化的人。开始之前建议你先在心里过一遍这三个问题再动手装你是只想跑通Demo还是准备长期挂着当服务用这两条路的环境配置完全不同。你的Windows版本是不是Win10 22H2以上WSL2对这个有硬性要求。你准备用Docker方式跑还是裸机方式跑这决定了你后面的排查方向。想清楚之后再往下看。2. 部署前的环境准备WSL2、Docker与JDK17这三板斧openclaw本身不挑操作系统但它的依赖链在Windows上特别容易出问题。我实际跑下来的环境组合是Windows 11 WSL2 Docker Desktop JDK17 Git Bash。下面逐个说为什么要这么配。2.1 WSL2从在Windows里装Linux到Windows原生虚拟化openclaw的安装脚本和运行时依赖了一系列Linux风格的工具链包括bash脚本、systemd服务管理、以及部分用Linux路径硬编码的配置。你当然可以在Windows下装一个Git Bash来凑合但后续要挂常驻服务、开Redis、跑docker-compose就非常别扭。所以我的建议是先装WSL2。步骤很简单以管理员身份打开PowerShell执行wsl --install这条命令会默认安装Ubuntu发行版并启用WSL2架构。装完重启一下然后确认版本wsl --set-default-version 2 wsl -l -v看到VERSION这一列是2就对了。如果你这步提示虚拟化未启用需要进BIOS开Virtualization TechnologyVT-x这是很多人在第一步就被卡住的地方。为什么非要WSL2而不是WSL1因为WSL2是真正的轻量虚拟机跑Docker不会出现存储驱动兼容性问题而且它的网络模式对NAT转发支持更干净openclaw里的Agent回调服务不会莫名其妙丢包。这一步建议不要图省事跳过。2.2 Docker DesktopWindows版必须开启两个开关openclaw的推荐部署方式是Docker原因很简单它内置的依赖服务Redis、向量库、网关组件用compose编排最省心。Windows上装Docker Desktop本身不难但装完之后有两个设置必须检查Settings - General - Use WSL 2 based engine必须勾选。这样Docker跑在WSL2里性能和Linux一致。Settings - Resources - WSL Integration勾选你刚才装的那个Ubuntu发行版。否则你在WSL终端里执行docker ps会提示连不上daemon。这个坑我踩了半小时。装完Docker DesktopWindows本体的cmd里docker version都能正常输出但切到WSL终端里就报Cannot connect to the Docker daemon。最后发现就是WSL Integration没开。2.3 JDK17与Git Bashheadless模式之外的隐藏依赖openclaw启动时要调用Java运行时版本要求就是17。Windows上很多人装了Oracle JDK 8或者OpenJDK 11跑起来直接UnsupportedClassVersionError这类报错在日志里非常难看出是版本问题。我建议装Adoptium Temurin 17因为它同时提供.msi安装包和zip包环境变量配置也不会被杀毒软件拦。下载地址就不贴了搜Temurin 17即可装完用这个命令验证java -version至于Git Bash如果你打算在Windows原生环境下执行openclaw的一键安装脚本Git Bash几乎是必须的。不建议直接用cmd或PowerShell跑openclaw.sh因为脚本里大量使用了$HOME、source这类bash语法在PowerShell里会有各种诡异的转义问题。准备到这里一个干净的基础环境就齐了。下面进入正题。3. 一键安装脚本跑起来之后到底发生了什么openclaw在Windows上的安装一共两条路线一是用官方一键脚本二是手动clone仓库后按步骤部署。我两条都试过这里说下每条路线的细节和坑。3.1 路线A一键脚本安装在WSL终端或Git Bash里执行curl -fsSL https://openclaw.example/install.sh | bash注意如果真的按网上某些教程跑的大概率会在中途卡在检查依赖这一步。因为脚本会依次检测docker、docker-compose、git、java、curl等组件任何一个缺失都会中断。我的建议是先手动把上一节那些组件全部确认无误再跑脚本别指望脚本自带环境救火功能。脚本执行过程中你会看到它做了以下事情理解这一过程对你后续排查非常有用创建~/.openclaw目录作为所有配置、日志、会话文件的根目录。clone核心代码仓库并切换到当前release tag。生成默认的openclaw.yaml配置文件模板。执行docker-compose pull拉取基础镜像。启动网关服务和数据库依赖。如果你在这一步发现拉镜像特别慢不用怀疑就是网络问题。解决办法我放在第四节统一说。3.2 路线B手动clone部署如果你喜欢每一步都掌握在自己手里那手动clone更合适。在WSL里执行git clone https://github.com/openclaw/openclaw.git cd openclaw cp config/openclaw.yaml.example ~/.openclaw/openclaw.yaml docker-compose up -d这里要特别提醒openclaw.yaml的存放路径很关键。网上很多教程让你把配置文件放在项目目录下但openclaw在启动时会优先读取~/.openclaw/openclaw.yaml如果你把配置放错位置会出现改了配置但是不生效这种最让人抓狂的问题。我个人的做法是统一把配置放到~/.openclaw/下项目目录只留代码。3.3 两种路线的选择建议对比项一键脚本手动部署上手速度快适合跑通Demo中等适合学习原理排错难度难因为封装层多容易每一层都看得见长期维护脚本升级比较方便添加自定义组件更方便适合场景先跑起来再说要接入多个channel/定制Agent我个人的经历是第一次跑通用的是路线A后来因为要接飞书机器人、修改路由逻辑又切到了路线B。如果你确定自己会长期用建议直接选B少走很多改了配置找不到缓存的弯路。4. Windows上安装openclaw的五大坑按踩中频率排序这一节是全文最实用的部分。以下每个坑我都实际踩过并且给出了可复现的排查路径。4.1 坑一镜像拉取超时与换源现象docker-compose up -d执行后进度条卡在某个镜像上几分钟不动最后报timeout或TLS handshake timeout。根因公开镜像仓库的出口带宽在高峰期极不稳定这是基础设施问题不是openclaw的问题。解决方案给Docker配置国内镜像加速器。在Docker Desktop的Settings - Docker Engine里把registry-mirrors加进去{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }保存后Docker daemon会自动重启再跑一次docker-compose up -d就快了。如果两个镜像源都慢可以换成阿里云容器镜像服务的个人加速器地址这个需要你登录阿里云控制台查看专属地址不展开说。4.2 坑二session file locked (timeout 60000ms) 报错现象启动Agent后第一次和它对话就收到错误agent failed before reply: session file locked (timeout 60000ms)。根因session文件被人为锁定了。在Windows WSL2的组合下最常见的原因是某个文件同步工具比如OneDrive同步目录、坚果云、或者杀毒软件的实时监控把~/.openclaw/sessions/里的文件锁住了导致openclaw的会话管理器无法在超时时间内写入。排查链路按顺序执行先确认是不是有多个openclaw实例同时启动。如果开了两个终端窗口都执行了openclaw start会造成同一个session文件被两个进程抢占。关闭一个实例再试。检查进程占用。在WSL终端执行lsof ~/.openclaw/sessions/*.session看是否有非openclaw的进程占用。如果有kill掉。如果以上都没有检查是不是云同步软件的问题。把~/.openclaw目录加入文件同步排除列表或者干脆把openclaw的数据目录移到/home/yourname/openclaw-data这种本地路径彻底避免云同步干扰。这个报错我在前两次安装时都遇到了前一次是开了两个终端导致的后一次是OneDrive惹的祸。提这个问题的人很多注意一下基本都能解决。4.3 坑三脚本闪退问题现象在Windows下用cmd或PowerShell执行安装脚本窗口一闪而过什么日志都没留下。根因脚本本身是bash脚本在cmd里执行当然会闪退——它只是试图找一个没有注册的shell来运行。而且PowerShell对curl的别名是Invoke-WebRequest参数完全不兼容你在cmd里执行curl -fsSL ...| bash时其实是在下载HTML而不是安装脚本。解决方案不要在cmd里折腾直接用WSL终端或Git Bash执行。如果你确实想用PowerShell可以这样wsl bash -c curl -fsSL https://openclaw.example/install.sh | bash这样就是让PowerShell把命令转发给WSL的bash去执行一切语法都正常了。同理日常操作openclaw的所有命令最好都在WSL终端里完成建立这个习惯之后会省掉很多莫名其妙的问题。4.4 坑四Windows防火墙拦截Agent回调这个坑藏得比较深。openclaw的Agent在响应飞书或Teams消息时不是主动轮询而是通过webhook回调地址把消息推送到本地网关。Windows防火墙默认会拦截来自局域网/公网的入站连接如果你发现飞书机器人已连接但收不到消息大概率是这个问题。现象飞书管理后台显示机器人正常本地日志也显示channel connected但实际发消息没有任何响应。排查方法在本机打开浏览器访问http://localhost:网关端口/health能通说明openclaw本体没问题。再用手机连接同一个局域网访问http://你的电脑IP:网关端口/health如果打不开说明防火墙拦了入站端口。打开Windows安全中心 - 防火墙和网络保护 - 高级设置 - 入站规则新建一个放行TCP端口的规则指向你的openclaw网关端口默认通常是8080或9876按你配置文件里的来。更稳妥的做法是在Windows防火墙里设置程序例外直接放行wsl.exe和docker desktop的可执行文件。因为WSL2的端口转发是经NAT的单单放行端口有时候不好使。别问我为什么连手机测这一步很有价值——它能帮你区分是防火墙问题还是openclaw网关问题。4.5 坑五端口冲突与Redis启动失败现象docker-compose up -d时Redis容器反复重启日志显示bind: address already in use。根因openclaw默认的Redis端口是6379而Windows下很多关联软件会私自占用这个端口。比如某些缓存工具、或者是上一次openclaw退出时没清理干净的残留容器。排查与解决# 查看哪些进程占用了6379 lsof -i :6379 # 或者用netstat netstat -ano | findstr 6379如果确认有非Docker进程占用可以改openclaw配置里的Redis映射端口比如把6379:6379改成16379:6379然后在openclaw配置文件中同步修改Redis连接串即可。如果占用的是残留容器直接:docker ps -a # 找到残留容器后用 docker rm -f 容器ID清理完再重启compose就正常了。端口冲突看起来不复杂但它会让你的compose卡在等待依赖就绪的状态排查时间比较久所以专门列出来。5. 从安装到可用配置你的第一个Channelopenclaw装好只是第一步真正让自己用起来、能让Agent回话还需要配置channel。我拼装了三个入口做日常使用飞书、Teams、本地命令行。下面分别说重点。5.1 Channel工作原理简述在openclaw里channel是指Agent与外界沟通的通道飞书机器人、Teams应用、WebSocket本地接口都是channel。它做的事很直白从各个入口接收消息统一格式化成内部会话结构交给Agent编排层处理再通过原始channel把回复发回去。所以配置channel的关键在于两类信息入口凭证App ID、App Secret、Token等和回调地址让消息平台能找到你的实例。5.2 接入飞书自定义机器人还是应用建议用企业自建应用里的机器人能力而不是简单自定义机器人。原因自定义机器人只能往群里发消息不能接收用户消息做双向对话自建应用机器人则支持单聊、群聊、机器人回复。步骤简述如下在飞书开放平台创建一个企业自建应用开启机器人能力。获取App ID和App Secret配置到openclaw.yaml的feishu.channel段。在事件订阅里配置请求地址为http://你的公网IP或域名:网关端口/feishu/event。如果没有公网IP可以先在局域网内测试使用类似frp的内网穿透工具将这个端口映射出去仅用于调试不建议长期这么干。在权限管理里开通im:message、im:message.receive_v1等读写权限并发布版本。配置完成后重启openclawopenclaw restart在飞书群里你的机器人发一句你好正常情况会在几秒内收到回复。这里有一个我踩了很久的坑飞书事件订阅要求请求地址必须以/结尾否则会回调失败。我在第3步省略了末尾的斜杠一直报verify failed。5.3 接入Microsoft Teams需要租户管理员操作Teams的接入比飞书繁琐一些涉及Azure门户配置。核心步骤是在Azure门户创建一个应用注册拿到Directory (Tenant) ID。为应用开启Team.ReadBasic.All、ChannelMessage.ReadWrite.All等权限。创建客户端密钥配置到openclaw。在openclaw的msteams.bot.channel里填入租户ID、应用ID、密钥并配置回调路径。如果你只是本机测试Teams这一项可以先不配置它的价值在于团队协作场景个人使用时飞书已经够用。5.4 命令行Channel最快验证安装的方式其实openclaw自带一个简单的命令行对话入口安装完成后再装一个CLI工具即可或者直接用openclaw chat命令。在WSL终端里执行openclaw chat它会在终端里直接起一个对话会话不需要任何网络回调。我建议无论你想接什么平台先把这个跑通这样能确认Agent编排本身没问题再排查各平台回调的故障。我第一次跑openclaw chat的时候其实没成功原因是配置文件里默认的模型路由没填对报错一看no model provider configured for agent default。这个在第6节细说。6. 接入模型提供商以千问为例的配置实战openclaw本身不包含大模型它只是一个编排框架你需要给它一个Model Provider才能让Agent真正具备对话能力。这一步看起来简单但很多新手栽在模型参数对齐上。6.1 Model Provider配置结构的理解在openclaw.yaml中模型部分的逻辑是三层model provider定义你是用OpenAI兼容接口、还是千问、还是本地Ollama以及该Provider的API地址和Key。agent profile定义Agent的名字、人设、使用的模型、温度参数、prompt模板类似剧本的角色设定。channel - agent映射定义哪个入口的消息由哪个Agent处理。网上常说的openclaw配置千问就是把第1层的Provider指向阿里云百炼的接口地址再让某个Agent的model关联到它。6.2 配置千问的推荐写法打开~/.openclaw/openclaw.yaml在models段添加model_providers: qwen: type: openai_compatible base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: sk-your-qwen-api-key models: - name: qwen-max context_length: 32768注意这里用的是openai_compatible类型因为千问的API兼容OpenAI的调用格式openclaw不需要单独适配就设置成OpenAI兼容模式然后改base_url就行。这个设计很实用国内这些大模型厂商几乎都提供OpenAI兼容接口。配置好之后在agent段指定模型agents: default: model: qwen/qwen-max temperature: 0.7然后在WSL终端执行openclaw config test它会试调一次模型接口如果返回正常就说明配置成功。出现401就检查API Key出现404就检查base_url末尾的/v1路径是否写对。6.3 实测体验与参数调整心得同样的prompt用qwen-max和用默认的openai-gpt-3.5-turbo在中文长文本理解上差距其实不小。我最终给default Agent用的qwen-maxtemperature调到0.5回答更稳定不会动不动放飞自我。另一个Agent负责飞书群里用户提问的我用了0.7因为它需要一点随机性来产生多样化的回答。这里有一个容易忽略的点每个channel可以绑定不同的Agent也就意味着你可以在飞书里放一个客服人设Agent在Teams里放一个技术总结Agent在本地CLI里放一个测试专用Agent。模型可以各自不同千问也好OpenAI也好完全看你的使用场景。7. 把openclaw跑成常驻服务的正确姿势安装配置都搞定之后最后的问题就是怎么让它一直跑着不用每次手动开终端。7.1 为什么不能直接用openclaw start挂后台在Windows WSL2环境里openclaw start虽然是后台模式但实际上它依附于当前WSL会话。一旦你关掉Windows终端窗口WSL会话会被回收openclaw进程也就没了。更麻烦的是Windows休眠或者睡眠唤醒后WSL2默认的虚拟网络和端口转发经常处于不稳定状态。7.2 方案systemd WSL2启动自启在WSL2的Ubuntu里配置systemd服务让openclaw作为系统服务常驻。步骤如下先在/etc/wsl.conf里确保有[boot] systemdtrue然后在WSL里创建service文件放在/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Agent Service Afterdocker.service network-online.target Requiresdocker.service [Service] Typesimple Useryourusername WorkingDirectory/home/yourusername/openclaw ExecStart/usr/local/bin/openclaw start Restartalways RestartSec10 [Install] WantedBymulti-user.target注意ExecStart的路径which openclaw看一下你实际安装位置别盲抄。然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw这样每次启动WSLopenclaw都会自动跟着跑起来。查看日志也方便journalctl -u openclaw -f7.3 Windows开机自启WSL再进一步如果你还想省掉打开WSL这一步Windows的开机自启WSL可以借助任务计划程序创建任务触发器选登录时操作填wsl.exe参数填-d Ubuntu -u username -c sudo systemctl start openclaw。这个需要配一个免密切换sudo安全性取决于你本机环境自己权衡。我个人的习惯是WSL内systemd自启就够了Windows登录后随手敲一个wsl命令进去也不费事。8. 使用一周后的体会与一个实用扩展写这篇安装记录之前我特意把openclaw在Windows上连续跑了一周飞书入口日常使用期间经历了重启、休眠、网络切换基本稳定。有几个体会想分享第一WSL2是Windows上运行这类服务的最佳载体但你要接受它偶尔出现的网络延迟抖动。飞书回调偶尔会有几秒延迟属于正常现象如果持续超过1分钟多半是防火墙策略又抽风了。第二配置文件的备份比想象中重要。~/.openclaw/openclaw.yaml里包含API Key和App Secret一旦丢失就得重新配置所有channel。建议引入到git仓库管理仅提交本机别推到公开平台。我在项目目录里做了个config-backup分支定期commit出了幺蛾子直接回滚。第三openclaw和WorkBuddy这类产品的定位不太一样。WorkBuddy更偏开箱即用的对话助手openclaw更像是自己动手搭Agent架构的积木箱。你要是喜欢折腾、愿意读配置、有自己的流程设计openclaw的灵活度明显更高但如果你只是想要一个能聊天、能查日程的助手那它给你的自由度反而成了学习成本。最后再分享一个实用扩展给openclaw加一个每日总结定时任务。在配置里填好cron表达式让Agent每天定时读取某个channel里的消息记录生成摘要推送到飞书群。这个做法让我每天早上一睁眼就有前一天的完整项目进度汇总效果非常直接。具体配置在openclaw示例目录里有模板把你想总结的时间和范围填上就好。安装到这里已经不再是跑通Demo层面而是真正可以在Windows上长期使用的Agent基础设施了。希望这篇记录能让你少走几段弯路。