Windows 环境下的部署我前前后后折腾了一周把 OpenClaw 本地部署完整跑通之后最大的感受是这才是把 AI 代理握在自己手里的正确姿势。以前用云端托管模型、接口、额度和数据全都不受控平台改个策略我的自动化流程就得跟着推倒重来。OpenClaw 这类代理运行时搬到本地之后模型可以选本地推理的千问、DeepSeek消息入口能接飞书、Teams 或者直接走终端所有配置和数据都留在自己硬盘上没有额度焦虑也不用担心聊天内容被拿去二次利用。如果你正打算做同样的事情这篇 Windows 环境下的部署全攻略可以帮你少走不少弯路。这套部署方案适合谁我想大概是三类人一是个人开发者想用本地大模型构建私有知识库和自动总结机器人二是办公自动化爱好者需要在飞书、Teams 这类 IM 工具里跑一个能自动处理消息的代理三是 IT 运维人员希望在离线或内网环境里验证 AI 代理能力。无论哪类看完这篇之后你应该能把 OpenClaw 在 Windows 上完整装起来并且搞清楚它到底是怎么工作的。1. 部署前的判断OpenClaw 本地跑到底解决什么问题1.1 先把 OpenClaw 的定位搞清楚OpenClaw 不是一个“聊天机器人软件”而是一个 AI 代理运行时框架。你可以把它理解成一个自带调度系统的“代理管家”它负责加载大语言模型、管理消息渠道、维持会话状态并按你设定好的规则自动执行任务。最简单的类比是这样的如果说大模型是一个运算能力很强的实习生OpenClaw 就是给这个实习生配备的完整办公桌——有电话消息渠道、有日程表会话状态、有文件柜记忆与上下文存储、还有一套工作手册Agent 定义与提示词。没有这张办公桌你只能每次手动把任务喂给模型有了它模型才能持续在线、主动响应。基于这个定位部署 OpenClaw 至少要做三件事准备模型接入、配置消息渠道、定义代理行为。这三件事在后面的安装和配置章节里都会逐一展开。1.2 本地部署相对云端调用的四个优势我选择在 Windows 本地跑而不是继续用托管平台核心原因有四条按重要程度排序第一是数据主权。所有提示词、会话记录、中间输出都留在本机硬盘不会因为平台审查策略而丢数据也不需要担心企业聊天内容被第三方服务商读取。第二是响应延迟。本地调用大模型走的是 localhost 或者局域网典型延迟在几十到几百毫秒对比云端 API 动辄两三秒的响应体验差距非常明显尤其在飞书、Teams 这样需要即时回复的场景里。第三是成本可控。本地模型一次性把硬件成本花掉之后单次调用边际成本几乎为零。个人使用强度下云端按 token 计费的模式长期看并不便宜。第四是自由度。OpenClaw 的配置项全部落在本地文件里你可以随时改模型供应商、切换渠道、调整 Prompt 甚至自己改代码扩展能力不受平台功能边界限制。1.3 硬件与系统要求以及适合的复现条件我在实际部署时用的是一台日常办公机Windows 11 专业版CPU 是 i7-12700内存 32GB显卡是 RTX 3060 12GB系统盘剩余空间 80GB 以上。这套配置跑 7B 到 14B 规模的量化模型整体体验还算流畅。如果只有核显或者显卡显存低于 8GB也别急着放弃。你仍然可以用 CPU 推理小尺寸模型比如千问 1.5B、DeepSeek-R1-Distill-Qwen-1.5B只是响应速度会慢不少。严格来说一台 16GB 内存的 Windows 电脑就能把 OpenClaw 跑起来模型小一点而已。操作系统方面建议 Windows 10 21H2 以上或者 Windows 11因为后续要启用 WSL2 和虚拟化老版本系统会多一些坑。复现这套部署过程按照第 2 章先把环境彻底准备好后面基本可以一路顺到底。2. Windows 环境准备WSL2、Docker 与模型权重一步到位2.1 安装 Docker Desktop 时最容易忽略的 WSL2 设置OpenClaw 的推荐部署方式是容器化所以在 Windows 上第一步是装 Docker Desktop 并启用 WSL2 后端。很多人装完 Docker Desktop 之后发现 OpenClaw 容器起不来排查半天才发现问题出在 WSL2 没启用或者 Docker 没有正确绑定到 WSL 发行版上。先在 PowerShell管理员模式里检查一下当前系统是否已支持 WSLwsl --status如果提示没有安装执行wsl --install执行完之后重启电脑。这一步会自动帮你启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个 Windows 功能。要注意wsl --install之后默认安装的是 Ubuntu后面安装 Docker Desktop 时可以直接选择 Ubuntu 作为集成目标。安装 Docker Desktop 时有一个非常关键的勾选在 Settings - General 里确认Use the WSL 2 based engine是打开状态。然后在 Settings - Resources - WSL Integration 里把 Ubuntu 的开关打开。这个开关如果漏掉Docker 会始终跑在 Hyper-V 的后端上和后续配置的 localhost 端口映射逻辑不一致容易引发“容器起来了但宿主机访问不到服务”的诡异问题。装完之后打开 PowerShell 验证docker version看到 Client 和 Server 两段都有版本号说明 Docker 引擎正常。如果只有 Client 没有 Server多半是 WSL Integration 没开或者 Docker Desktop 还在启动中等一两分钟再看。2.2 用 Ollama 准备本地模型千问 / DeepSeekOpenClaw 本身不捆绑任何大模型它需要一个模型后端。我在 Windows 上用的是 Ollama原因有两个一是它对 Windows 原生支持安装非常简单二是它提供了和 OpenAI 兼容的 APIOpenClaw 配置文件里只需要填一个 base_url 就能接入省去很多适配工作。到 Ollama 官网下载 Windows 安装包安装完成后 Ollama 会作为后台服务运行默认监听127.0.0.1:11434。接着拉取模型我拿千问和 DeepSeek 分别试过最终留在本地的两个模型是ollama pull qwen2.5:7b-instruct ollama pull deepseek-r1:7bqwen2.5:7b-instruct聊天和总结能力强适合做日常办公助手deepseek-r1:7b推理链路更完整适合处理带逻辑判断的任务。拉取完毕后用ollama list确认模型已经在本地。需要提醒的是Ollama 默认只监听本机回环地址。如果后续你打算让局域网内其他设备也能调用这个模型接口需要设置环境变量OLLAMA_HOST0.0.0.0然后重启 Ollama 服务。我建议第一轮部署先保留默认监听专注把 OpenClaw 跑通局域网共享可以放到后面再优化。2.3 系统端口、防火墙与目录规划部署前最好把端口和目录规划清楚。OpenClaw 服务本身会监听一个 API 端口默认一般是8080或1860这一类具体以你拿到版本的默认配置为准。Ollama 占用11434。这两个端口在部署时都要保证没有被其他程序占用。在 PowerShell 里检查端口占用netstat -ano | findstr 8080 11434如果发现端口被占需要去对应进程里释放或者修改 OpenClaw 配置里的端口号。Windows Defender 防火墙也可能会拦截容器端口外部访问如果你只是在同一台电脑上访问一般不会触发如果要从别的设备访问记得在防火墙的“允许应用”里把 Docker Desktop 相关项放行。目录规划同样重要。我建议专门建立一个工作目录存所有 OpenClaw 相关文件例如D:\OpenClaw下面分出data和config两个子目录。这样备份、升级、清理都很清晰不会让数据散落在系统盘的隐藏路径里。3. 安装 OpenClaw 的两条路线一键脚本与 Docker Compose3.1 一键脚本适合快速验证OpenClaw 的快速安装方式是一键脚本官网上一般会提供对应操作系统的安装命令。Windows 上的典型做法是在 PowerShell 里执行一个远程脚本这个过程会自动下载镜像、生成默认配置并拉起服务。我第一轮尝试用的就是这条路体验是快确实快全程大概十分钟基本没有手工干预。但也正因为过度自动化过程中出了问题排查很麻烦。比如我第一次执行完脚本后看着终端刷了一堆日志以为装好了结果打开浏览器访问管理页面一直超时后来才发现是 Docker Desktop 当时还没完全启动脚本拉起容器时失败了两三次最终态看着是运行中实际上服务端口根本没监听。所以我的建议是用一键脚本做第一轮的快速验证没问题但装完后必须按第 3.3 节做一次健康检查。如果你计划长期使用我更推荐第二种方案。3.2 Docker Compose适合长期维护我更推荐用 Docker Compose 来部署因为所有启动参数、端口映射、存储卷都在一个docker-compose.yml里升级、回滚、迁移都方便。以一个典型的本地部署为例目录结构大概是这样的D:\OpenClaw ├── docker-compose.yml ├── .env ├── data └── configdocker-compose.yml的核心思路是定义 OpenClaw 的主服务容器把配置文件目录和会话数据目录挂载到宿主机并把8080端口暴露出来。大致结构如下services: openclaw: image: openclaw/core:latest container_name: openclaw restart: unless-stopped ports: - 1860:1860 volumes: - ./config:/app/config - ./data:/app/data env_file: - .env extra_hosts: - host.docker.internal:host-gateway这里有一个非常关键的配置extra_hosts加上了host.docker.internal:host-gateway。因为 OpenClaw 跑在容器里如果模型后端用的还是宿主机上的 Ollama容器内访问宿主机不能用localhost必须用host.docker.internal这个特殊域名。这一行不加后面配置模型接口时百分之百会踩“容器里调不通宿主机模型”的坑。.env文件里主要放服务端口、数据目录路径、必要的密钥参数。注意.env文件保存时一定要用 UTF-8 编码下面第 5 章会专门讲这个坑。3.3 安装完成后的健康检查清单无论用哪条路线装完都要按这个清单过一遍缺一项都不算装成功确认容器状态正常。在项目目录执行docker compose ps服务状态应该是Up。查看启动日志有没有报错。执行docker compose logs -f --tail100重点看有没有error、panic、timeout字样。第一次启动时日志会比较长耐心等到出现类似server started或API listening的信息。验证 API 端口通不通。在 PowerShell 里执行curl http://127.0.0.1:1860/health端口按你实际配置改如果能返回一段 JSON 或者OK说明服务已经暴露出来了。检查配置目录和数据库目录是否自动生成。OpenClaw 第一次启动时会自动创建默认配置和数据文件如果config和data目录还是空的说明容器可能没有正确的挂载权限需要检查路径。第一轮跑完这四项检查就可以进入配置阶段了。4. 把模型和消息渠道接进来代理才算真正跑起来4.1 配置本地模型的 OpenAI 兼容接口OpenClaw 默认的模型接入方式很直接它调用的是 OpenAI 兼容的 Chat Completions 接口所以你既可以选择 OpenAI、Anthropic 等云端服务也可以填本地 Ollama 的地址。我最终用的是 Ollama配置时主要关心三个字段接口地址、模型名称、密钥。如果走本地 Ollama密钥随便填一个占位符就行比如ollama-local因为本地服务根本不校验密钥。模型配置的大致内容如下具体字段名以你版本的默认配置为准model_providers: - name: local-ollama base_url: http://host.docker.internal:11434/v1 api_key: ollama-local models: - name: qwen2.5:7b-instruct enabled: true - name: deepseek-r1:7b enabled: true配置里最值得注意的就是base_url。再次强调OpenClaw 跑在容器里localhost指向的是容器自身不是宿主机。只有配上第 3.2 节那个extra_hosts参数host.docker.internal才能正确解析到宿主机。我在这一条上浪费了整整一个下午一开始填localhost:11434容器日志一直报连接拒绝后来改成host.docker.internal才通。如果你的模型后端不是 Ollama而是 DeepSeek 官方 API 或者云端千问思路完全一样只需要把base_url换成对应服务的地址、填上真实 API Key。4.2 渠道连接器Teams、飞书与本地终端模型接好之后还需要让 OpenClaw 能收消息、发消息。渠道连接器是 OpenClaw 比较有特色的设计——它不绑定任何单一平台而是通过一个个 connector 对接不同渠道。先说最简单的验证渠道本地终端。很多版本 OpenClaw 默认会启用一个终端交互入口你直接在 PowerShell 里执行openclaw chat或者通过容器进入交互模式就能和代理对话。第一轮配置我强烈建议先用终端渠道验证模型链路正常了再去接入 IM 工具避免两拨配置混在一起排查困难。然后是飞书渠道。在飞书开放平台创建应用拿到 App ID 和 App Secret再把 OpenClaw 配置成接收飞书消息的服务端。这里要注意飞书机器人和自建应用需要配置事件订阅地址这个地址必须让飞书服务器能访问到——如果你只是纯本地部署没有公网地址飞书渠道是不通的。我能给你的建议是本地测试期先用终端渠道等需要真正接飞书时再考虑把服务部署到有公网访问条件的环境或者用平台自带的长连接模式具体要看 OpenClaw 版本是否支持。Teams 渠道的逻辑类似。在 Azure 门户注册机器人、生成 Bot ID 和密码然后在 OpenClaw 配置里填上对应凭证。Teams 的难点同样是回调地址和飞书的问题如出一辙。所以我一直坚持先把终端渠道玩熟再碰复杂渠道。4.3 多 Agent 与 channel 匹配的思路OpenClaw 的 Agent 并不仅限于一个。和渠道建立连接之后你可以按照场景拆分成多个代理一个负责日程提醒一个负责文档总结一个负责群聊消息筛选。每个代理可以绑定不同的模型、不同的提示词和不同的渠道。在配置里channel 和 agent 的匹配逻辑通常是这样的渠道负责“接消息”代理负责“处理消息”。你可以让飞书的一个群绑定到“文档总结代理”另一个群绑定到“客服问答代理”互不干扰。这种一对多的关系非常实用相当于在同一台机器上同时开了好几个不同工种的 AI 同事。实际使用时我建议先从一个代理开始等跑稳了再增加。原因很简单会话状态是 OpenClaw 管理的重要资源多代理同时运行时每个代理会维护独立的会话文件排查问题时复杂度会成倍增加。5. 部署之后的三个常见故障与排查过程5.1 session file locked并发写会话文件导致的 60 秒超时这个错我印象太深了因为它的报错信息非常吓人agent failed before reply: session file locked (timeout 60000ms)第一次看到后半段我直接以为是服务卡死了重启大法用了一轮没用。后来冷静下来分析问题出在“会话文件锁”上。OpenClaw 会把每个会话的上下文、历史消息持久化到本地文件。当一个代理同时被多个请求触发或者前一个请求还没写完会话文件、后一个请求又尝试写入时就会产生文件锁竞争。系统默认给你 60000 毫秒去等锁释放等不到就直接放弃响应。排查链路是这样的先检查是不是起了多个 OpenClaw 实例。我那次的问题就出在之前用一键脚本启了服务后来又用 Docker Compose 起了一遍两个实例同时操作同一个数据目录会话文件被抢来抢去。确认只有单实例后检查数据目录里的会话文件。通常会看到一个.lock后缀的锁文件这是上次异常退出后没来得及清理的遗留物。确认当前没有活跃请求时手动删除锁文件。删除前建议把整个data目录备份一份反正也就几十兆买个安心。最后如果是高并发场景或者一个代理要处理大量消息把配置里的会话锁超时时间调大比如从 60000 毫秒调到 120000 毫秒同时限制同一代理的并发请求数让上下文的写入尽量串行化。处理完之后重启服务观察日志里没有再出现锁冲突问题就算解决了。这个错其实是“分布式锁”在日常单机部署里的一个典型体现理解了这个机制以后在任何用文件锁做持久化的应用里都不会慌。5.2 飞书消息输出被截断的处理另一个真实存在的坑是飞书渠道回复内容被截断。我当时让代理生成一篇完整项目周报结果飞书群里只收到了前几百字后面内容无声无息地消失了。原因是大多数 IM 平台的单条消息长度都有限制飞书和 Teams 都一样。代理生成的完整结果超过了单条消息上限输出阶段把超限部分吞掉了但代理本身并不知道这个结果被截断。我的处理方案是改输出策略在代理的提示词里明确要求回答超过一定长度必须按小节输出或者直接启用消息分片功能配置里把一条长回复拆成多条连续消息发送。两种方案各有好坏——按小节输出适合结构化报告消息分片适合流水式长文看你实际使用场景。这里还有一个容易被忽略的细节飞书的富文本卡片和普通文本消息长度限制还不一样。如果你配置的是富文本消息卡片要注意卡片内文本长度上限通常比纯文本更小。5.3 Windows 下容器闪退和端口占用问题在 Windows 上跑 Docker 容器最常见的问题不是 OpenClaw 本身而是容器莫名退出。排查思路按概率从大到小排列第一是资源不足。WSL2 默认会动态占用大量内存如果电脑只有 16GB 内存再同时跑 Docker Desktop、Ollama 和 OpenClaw 三个服务很容易触发内存压力导致容器被杀。此时最有效的做法是给 WSL2 设一个内存上限第 6 章会专门讲。第二是端口被占。Windows 上不少软件会随机占用端口特别是开发工具一开一大排。容器启动日志里如果看到address already in use用netstat -ano | findstr 端口号找到占用进程并处理掉。第三是 Docker Desktop 的集成问题。装了多个 Linux 发行版或者 Docker 配置被改过的情况下容器可能拉到宿主机网络的错误节点上。不要犹豫先把 Docker Desktop 的 WSL Integration 重新确认一遍比啥都强。5.4 配置变更不生效的隐藏原因行尾符和缓存这个坑值得单独立一条因为它太隐蔽了。我在 Windows 上用记事本编辑 YAML 配置文件改完重启 OpenClaw发现配置完全没有生效。不是路径错、不是语法错、更不是字段名错而是记事本默认把文件保存成了带 BOM 的编码而且换行符用的是 CRLF。YAML 解析器对这两件事很敏感。带 BOM 的文件可能让整个配置无法解析CRLF 行尾在某些版本的解析器里会导致字符串值和预期不一致最典型的表现是配置里的端口变成了8080\r这种带隐藏字符的值。处理办法很简单所有配置文件编辑完成后用 VS Code 打开并确认右下角显示UTF-8和LF。如果你用的是记事本强制另存为 UTF-8 并祈祷行尾正常。我的习惯是项目里所有配置文件的编辑一律用 VS Code坚决不用 Windows 记事本碰。另外还要注意OpenClaw 启动时会缓存部分配置。改完配置后光重启容器可能不够有时候需要把容器删掉重新创建或者手动清理配置缓存目录否则长时间调试时会遇到“改了几次都不生效”的错觉。6. 长期运行的资源控制与维护建议6.1 用 .wslconfig 控制 Windows 侧的资源占用OpenClaw 部署完成后如果不加任何限制Docker、WSL2 和 Ollama 会像饿了很久一样疯狂吃内存。尤其 WSL2 的内存回收机制并不积极用久了电脑会越用越卡。解决方式是在 Windows 用户目录下创建一个.wslconfig文件内容如下[wsl2] memory8GB processors4 swap2GB创建完成后执行wsl --shutdown让它生效。设置之后 WSL2 虚拟机的内存占用被限制在 8GB 以内Docker 容器和 Ollama 都在这个范围内运行给 Windows 主系统留出足够的余量。我的 32GB 机器设置的是 12GB 上限16GB 内存的机器建议从 6GB 起步。这个文件值得反复调整。本地跑大模型是一个吃资源的活要在“模型响应速度”和“日常办公不受影响”之间找平衡不是一劳永逸的事。6.2 日志膨胀与会话文件的定期清理OpenClaw 跑了几天之后数据目录会越来越膨胀。每一条对话都会写到会话文件里如果代理被频繁使用日志和会话文件加起来会达到好几个 GB。平时感觉不出来到 Docker 镜像升级或者备份数据的时候就会发现整台电脑都被它拖着走。我建议建立一套自己的维护节奏每两周检查一次data目录大小超过 2GB 就要着手清理旧会话。老会话如果不需要长期保留直接把对应会话文件删掉OpenClaw 会自动重建。日志文件轮转也要关注。Docker 容器默认会把所有 stdout 日志攒到一个 json 文件里时间长了可能占用几十 GB。可以在 Docker Compose 里加日志轮转限制logging: driver: json-file options: max-size: 50m max-file: 3这段配置的意思是单个日志文件最多 50MB最多保留三个文件超出就滚动覆盖。对于长期运行的部署来说这是必须做的一件事。6.3 与 WorkBuddy 类工具对比之后的选择建议在决定用 OpenClaw 之前我也对比过 WorkBuddy 这类同类产品。简单聊聊我的取舍给还在犹豫的朋友一个参考。WorkBuddy 这一类产品的强项是界面化工作流设计拖拽节点就能搭流程对不会写配置的人非常友好开箱即用的程度更高。但它的定制深度和渠道灵活性相对受限有时候想接一个冷门的内部系统发现官方没有对应插件就得等版本更新。OpenClaw 的强项恰恰相反配置驱动、渠道优先、本地离线友好、扩展性强。代价是有学习门槛你得愿意花时间读配置、理解会话机制、自己排错。这个特点高度适合我在前文描述的场景——私有部署、多模型切换、紧贴办公 IM 渠道的自动化需求。两者并不互斥。如果你只需要快速搭一个简单机器人WorkBuddy 可能更合适如果你想把 AI 代理深度嵌入自己的办公体系和知识库并且愿意长期维护OpenClaw 是更扎实的选择。我最终选择 OpenClaw核心原因还是它让我能完全掌控这套系统。最后再分享一个习惯。每次部署完成我第一件事不是马上接入团队聊天空而是先在终端里跟代理聊几句让它整理一篇本地云文档目录再让它总结一条长网页内容。这三步做完模型接入、上下文管理、工具调用全部验证到位。确认没问题再去接飞书或者 Teams整个流程会顺畅很多。这套部署方案跑通之后你自己就能判断哪些环节值得继续折腾哪里需要见好就收。