我猜你最近八成是被 OpenClaw 刷屏了随手一搜就是“AI Agent 框架”“个人 AI 助理开源平替”这些词。OpenClaw 在国内社区有个更接地气的名字叫“龙虾”跟它的开源 logo 一样一只张牙舞爪的龙虾看着就很有攻击性。这个项目本质上是一个开源的 AI 智能体框架核心玩法是把接入不同聊天平台比如钉钉、飞书、Discord、Teams 这些的个人助手统一收拢到一套配置里让它自己看网页、读文档、操作本地文件甚至帮你跑完一套工作流。这篇文章我打算认真讲讲在 Windows 上本地部署 OpenClaw 的完整路径。不是那种装完就跑的演示而是把每一步背后的逻辑都拆开——为什么对 Windows 用户来说 WSL2 Docker 这条路最省心为什么本地模型地址填不对会报出各种迷惑错误以及最常见的 “session file locked” 到底是怎么来的。只要你按下面这套流程走我踩过的坑你基本都能绕开。1. 环境准备为什么我对 Windows 原生 Docker 始终不放心1.1 先理解 OpenClaw 到底跑在什么环境里很多人看到“Windows 本地部署”五个字第一反应是“我是不是要装一堆乱七八糟的运行时”。这个想法没错但关键不是装什么而是搞清楚 OpenClaw 的组件结构再动手。OpenClaw 采用的是典型的客户端/服务端分离架构。服务端是整套框架的核心负责“记忆上下文、调度工具、对接模型和平台”客户端则弱化为一个交互壳你可以在浏览器里、命令行里、或者通过钉钉/飞书这些 messenger 渠道跟它说话。服务端本身跑在容器里最舒服因为它的依赖链很长官方维护的就是 Docker Compose 方案一套拉起来包括数据库、缓存、服务本体、还有可选的文件存储组件。你要在 Windows 上让这一整套东西稳定跑起来本质上是在 Windows 上搞一个能跑 Linux 容器的环境。这就引出一个经典选择Windows 原生 Docker Desktop还是 WSL2 里跑 Docker我见过太多教程直接让你装 Docker Desktop on Windows然后一路 Next。讲真Docker Desktop 本身不算错但它在 Windows 上有两个绕不开的老毛病一是底层 Windows 容器和 Linux 容器混着用容易出岔子二是 Hyper-V 和 WSL2 的资源调度在某些版本上会打架导致容器启动特别慢而且一旦 Docker 引擎崩了恢复成本很高。我也不是否定它只是想在你这篇文章里推荐一条更适合本地折腾的路径先装 WSL2再在 WSL2 的发行版里装 Docker Engine。这样用下来 OpenClaw 在 Linux 环境里跑兼容性最稳后面出任何诡异问题排查面也小。1.2 WSL2 安装与配置要点别一键到底WSL2 的安装Windows 10 2004 以上和 Windows 11 基本都支持。以管理员身份打开 PowerShell直接执行wsl --install这一步会把 WSL 核心、虚拟机平台和默认的 Ubuntu 发行版一次性装好。装完提示重启就重启。重启之后要确认默认版本是 v2也就是真正的轻量虚拟机不然后面性能会有明显差距wsl --set-default-version 2然后给 Ubuntu 留够资源。OpenClaw 本体加模型服务不是吃素的我建议至少给 WSL2 分配 4 核和 6GB 内存。这一步不是在 WSL 里设置而是在 Windows 用户目录下创建一个.wslconfig文件[wsl2] memory6GB processors4 swap8GB再强调一次.wslconfig放在C:\Users\你的用户名\.wslconfig改完要wsl --shutdown再重启 WSL 才会生效。这种“资源配额提前规划”的习惯等你同时跑 OpenClaw 服务和本地模型时就会发现有多重要了。1.3 在 WSL2 里装 Docker避开 Docker Desktop现在进入 Ubuntu 终端安装 Docker Engine。用官方 apt 源装最省事但国内网络拉download.docker.com有时候会慢得让人崩溃这里我给一个稳定的做法先用清华或阿里云镜像源替换 apt 源再装 Docker。大致步骤如下# Ubuntu 内先更新系统 sudo apt update sudo apt upgrade -y # 下载 docker 官方安装脚本脚本会自动检测系统并配置源 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 让当前用户免 sudo 操作 docker sudo usermod -aG docker $USER newgrp docker # 验证 docker version如果你在下载脚本那一步就卡住了也可以直接sudo apt install docker.ioUbuntu 自带的仓库里就有。装完 Docker 以后强烈建议顺手把镜像加速配了。编辑/etc/docker/daemon.json填入你信得过的加速器地址。这一步对 OpenClaw 部署来说几乎是必备的因为镜像拉取如果不加速光一个 openclaw 镜像可能就让你等十几分钟还经常拉一半断开。配置完成后sudo systemctl restart docker让配置生效。到这一步Windows 侧的环境底座已经算是搭好了下面进入 OpenClaw 本体的安装环节。2. OpenClaw 本体安装容器路线与源码路线的取舍2.1 快速理解 OpenClaw 的初始化交互流程OpenClaw 的官方安装工具设计得很有意思它不是让你一上来就去改配置文件而是通过命令交互一步步生成配置。先克隆仓库或者直接拉镜像然后执行初始化命令CLI 会问你几个问题项目目录放哪、数据库用哪种默认 SQLite本地单机完全够用、模型供应商选谁Ollama、OpenAI 或者兼容接口、要不要启动内置 Web UI 等等。这套交互设计对新手非常友好但有个代价——很多人没意识到答完之后其实是生成了一个openclaw.json或.env文件后续所有修改变得都得回到这个文件。我见过不少人初始化时选了默认“OpenAI”结果本地部署的模型地址根本没配进去然后说什么 OpenClaw 连不上模型。不是框架的问题是你配置的模型路径压根不对这一点后面单独讲。2.2 容器部署Compose 一把梭最推荐的还是容器方式。在 WSL2 里建个专门的工作目录比如~/openclaw然后从官方仓库拿docker-compose.yml。如果你是第一次部署我看到网络上的讨论和官方文档的走向会看到下面这种结构version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw ports: - 3000:3000 environment: - TZAsia/Shanghai - OPENCLAW_MODEL_PROVIDERollama - OPENCLAW_MODEL_BASE_URLhttp://host.docker.internal:11434 volumes: - ./data:/app/data - ./config:/app/config extra_hosts: - host.docker.internal:host-gateway这里有几个细节值得展开。先说host.docker.internal。容器里的服务要访问 Windows 宿主机上跑着的 Ollama后面要说的本地模型服务不能直接写localhost因为容器有自己的网络栈得用host.docker.internal这个特殊域名指向宿主机。但 Docker Engine on LinuxWSL2 里的 Docker 本质是 Linux 容器默认不支持这个域名需要extra_hosts手动把它映射到host-gateway。这一步不做你得在模型配置里改用 WSL2 的虚拟 IP特别麻烦。很多人在这一步被卡死我先给你打预防针。然后说OPENCLAW_MODEL_PROVIDERollama这种配置项。不同版本的 OpenClaw 配置键名会有微调如果你用的是官方 webui 引导初始化生成的文件里可能写成OPENAI_BASE_URL、OPENAI_API_KEY这种兼容格式指向任意一个 OpenAI 兼容 API 服务。不管是哪种核心思想就一个把 Base URL 指向你真实可用的模型服务地址。拉镜像可以用下面命令如果速度很慢回到前面说的改 daemon.json 镜像加速docker compose up -d看到容器状态 healthy 以后浏览器打开http://localhost:3000这一套就算起来了。之后 OpenClaw 的一切配置修改都从 Web UI 或挂载出来的./config目录里改不用再进容器内部折腾。2.3 源码部署适合改代码的人但成本明显更高如果你有改源码的需求比如要自己写工具、定制 agent 行为容器方式确实麻烦——每次改代码都要重新 build 镜像。源码部署路线通常建议在 WSL2 的 Ubuntu 里直接拉代码然后用 Node.js 跑。OpenClaw 服务端是基于 TypeScript 的先在 Ubuntu 里装好 Node.js 18 和 pnpm然后git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build pnpm start理论上这样也能跑起来但实际体验下来有几个坎第一依赖安装时间巨长pnpm 装完经常几百 MB 起步网络差一点就会遇到各种 ECONNRESET第二本地跑服务端和容器跑服务端对配置文件的路径要求不一样docker 挂载技术、源码方式直接用相对路径中途切来切去很容易把配置搞丢第三OpenClaw 的依赖里有原生模块在 Windows 原生环境下编译经常因为 node-gyp 翻车所以我不会建议你在 Windows 的 CMD 里直接跑源码除非你确认所有依赖都有预编译二进制。我的建议很明确如果你不是要改框架源码直接走 Docker Compose别折腾。本地部署 OpenClaw 的核心价值是“快速拥有一个可控的个人 AI 助理”不是跟编译环境斗智斗勇。3. 让“龙虾”真正开口本地模型服务的接入与配置3.1 为什么我建议本地部署模型而不是白嫖云端 APIOpenClaw 本身没有内置模型它对接入的模型只要求“兼容 OpenAI 的对话补全接口”。所以你有两条路接云端 API或者接本地模型。云端 API 配置简单、效果也好一点但有两个现实问题一是部分服务的接口地址在国内网络环境下访问不干脆二是你把个人对话数据全送去云端如果跑的是私人助理场景数据就不在你自己手里了。本地模型路线现在是主流相关热搜词里的“DeepSeek 本地部署”、“Ollama 本地部署”都是这条路。核心思路是用 Ollama 或者 vLLM 这类推理服务在本机把模型权重加载成 OpenAI 兼容 API让 OpenClaw 通过一个本地 HTTP 端口来调用。如果你之前已经为了本地玩 AI 装过 Ollama那恭喜你省了 80% 的功夫。3.2 Ollama 部署与模型选择清单在 Windows 本机装 Ollama 很简单官方安装包双击就行装完 Ollama 默认监听在127.0.0.1:11434。启动一个小模型在 CMD 里执行ollama pull qwen2.5:7b ollama run qwen2.5:7b为什么不直接拉 70B 的大模型这里有个现实门槛本地跑大模型参数规模基本被显存卡死。我实测下来 7B 的量化版大概要 6–8GB 显存8B 的稍微多一点如果你机器是 16GB 内存且无独显跑 7B 已经比较吃力了。选择模型的时候不要盲追参数合适才是对的。OpenClaw 这边把 provider 指向 Ollama 的 OpenAI 兼容端点http://host.docker.internal:11434/v1模型名填qwen2.5:7b。这套搭配我一直觉得是 Windows 本地部署 OpenClaw 的黄金组合OpenClaw 本体吃内存Ollama 吃显存二者互不干扰关机能干干净净。3.3 模型服务地址填错的经典报错集锦接入本地模型最常见的坑不是模型没下载好而是地址配错。容器内的 OpenClaw 访问不了你本机的localhost:11434这是网络命名空间隔离导致的跟代码逻辑没关系。我整理一下我实际踩过的几个错误场景方便你对号入座配置位置错误写法正确写法错误现象OpenClaw 环境变量OPENCLAW_MODEL_BASE_URLhttp://localhost:11434/v1http://host.docker.internal:11434/v1容器内连接拒绝报 ECONNREFUSED不带 /v1http://host.docker.internal:11434加/v1404 或者提示 endpoint 不存在Ollama 没启动服务未启动先启动 Ollama 再启动 OpenClaw连接超时或空响应模型名不匹配qwen2.5:7b与 Ollama 中实际 pull 的名字完全一致模型欠拟合报 404 或 400很多人看到 OpenClaw 启动成功就以为万事大吉等到对话时才发现模型不通。这里有一个快速诊断方法先在 WSL2 终端里用 curl 直接测一下 Ollama 是否通了curl http://host.docker.internal:11434/v1/chat/completions -d { model: qwen2.5:7b, messages: [{role: user, content: 你好}] }只要这个命令能返回一段 JSON说明链路没问题。如果这个都返回不了就不要纠结 OpenClaw 那边了先排查 Ollama。3.4 进阶让本地对话质量更可控的几个参数接入模型只是第一步。我把实践里最有用的三个参数给你列一下纯本地部署调这三个体验提升最明显temperature控制在 0.2–0.5本地模型本身不如云端大模型稳定温度高了容易跑偏。max_tokens默认比较保守如果你希望助手能一口气帮你写长文把上限调到 2048 或 4096。system promptOpenClaw 的 agent 行为高度依赖 system prompt。想让它更像“私人助理”而不是“问答机”就要在配置里把角色设定写得具体比如“你是一个帮助我管理日程和文件的助手回答问题要简洁”。这些参数在 OpenClaw 的 Web UI 或openclaw.json里都能改改完重启服务生效。4. 让 agent 变成“多面手”channel 选择与多端接入4.1 channel 是什么怎么选才不给自己添堵OpenClaw 里的“channel”指的是消息渠道也就是你跟 agent 对话的入口。官方目前支持了不少Discord、Slack、Microsoft Teams、钉钉、飞书、Telegram还有本地终端和 Web UI。很多新手一上来就想把 Discord、Teams、钉钉全接了恨不得所有地方都能召之即来。我的建议是先冷静一下channel 接入是有成本的——每个渠道都要配 Bot Token、回调地址、权限范围。接得越多调试成本越高安全暴露面也越大。我给你的选择决策表使用场景推荐 channel配置难度备注自己单机调试Web UI / 终端★☆☆初始化默认就有建议先玩通移动端快速聊天钉钉 / 飞书★★☆国内环境连接最稳回调配置需要公网或内网穿透团队协作场景Microsoft Teams★★★配置复杂需要企业应用权限国际社区 / 在线社区Discord / Slack★★☆适合海外网络环境国内有连接但有一定延迟我个人的实践是单机阶段只留 Web UI 和终端 channel代码和 agent 行为完全跑通以后加一个钉钉 channel 用来手机端随时访问。这样既保证了核心功能的可用性也没有把时间浪费在不需要的渠道配置上。4.2 实战接入钉钉 channel 的完整步骤钉钉接入 OpenClaw 大致要四步在钉钉开放平台创建一个企业内部应用拿到AppKey和AppSecret在应用里配置机器人获得 Webhook 地址在 OpenClaw 的 channel 配置区里添加 dingtalk填入 AppKey/AppSecret重启 OpenClaw 服务在钉钉群里 机器人发起对话。这里面最麻烦的是回调。钉钉机器人要求你的服务必须能接收它发来的回调请求。如果你只是本地部署、没有公网 IP就需要用内网穿透工具把 OpenClaw 的 webhook 端口暴露出去。这也是我建议先单机玩通 Web UI 再去接手机端的原因本地跑通不涉及网络暴露一旦接钉钉你的本地服务就相当于出了一道口子到公网对安全意识的要求就高了。4.3 Microsoft Teams 接入的特殊注意事项最近问 Teams 接入的人特别多我这里单说一下。Teams 的 channel 接入走的是 Microsoft Bot Framework配置项更多而且它要求回调地址必须是 HTTPS不能是 HTTP。这就意味着本地环境直接接 Teams 几乎不可能要么你把服务部署到一台有 HTTPS 证书的服务器上要么在本机做 TLS 终止然后反代。很多人在这一步卡住不是 OpenClaw 的问题是微软平台的强制安全要求。如果你确实需要 Teams建议先用容器方式把 OpenClaw 跑起来再把 Web 服务反代到一个 HTTPS 域名最后在 Bot Framework 里填回调地址。涉及证书和反代的细节比较多这篇就不展开了给个方向。5. 高频问题排查与避坑实录5.1 agent failed before reply: session file lockedtimeout 60000ms这个报错在我见过的 OpenClaw 部署场景里出现频率极高值得单独拎出来写。中文直译就是“会话文件锁定等待 60 秒超时”。出现这个问题的根因大多数情况是 OpenClaw 内部对会话状态做了文件锁保护防止同一会话被并发修改。当你上一次请求还在处理或者服务异常退出没来得及释放锁下一次对话进来就会卡住。尤其在 Windows Docker 的环境里文件系统层面的锁机制和容器卷挂载的兼容性会放大这个问题。几个有效的处理办法按顺序尝试重启 OpenClaw 容器简单粗暴但常常有效docker compose restart openclaw如果有残留的 node 进程占用锁文件在 WSL2 里找到对应进程并清理ps aux | grep openclaw kill -9 pid检查启动日志看是不是上一个请求卡在模型调用上。模型超时也会导致锁一直不释放极端情况下直接删掉对话历史如果是个人调试损失可以接受。这里有个重要的排查思路这个报错只是“结果”不是“原因”。真正要修的是后端挂起的任务——多半是模型调用超时或者某个工具调用卡住。所以问题复现时不要只盯着锁文件先去看 OpenClaw 和模型服务的日志。5.2 端口占用与 Windows 下命令行闪退的修复思路部署 OpenClaw 或 Ollama 时偶尔会遇到“端口被占用”这类问题。常见冲突对象是 3000 端口OpenClaw Web UI和 11434Ollama。Windows 下排查端口占用老规矩netstat -ano | findstr 3000 taskkill /f /pid PID只要知道 PID直接杀掉对应进程就行。但如果你发现 PID 显示的是一个系统进程或者一直在变化的 PID那可能是服务本身在自动重启也可能是 Hyper-V 的动态端口占用这种就建议你直接改 OpenClaw 的对外绑定端口别硬跟系统抢。还有一个 Windows 特色问题写好的.bat或 PowerShell 脚本双击运行闪退窗口一闪而过什么都看不到。这在部署一键启动脚本时太常见了。解决办法很简单不要双击先在 PowerShell 里执行脚本错误信息会留在窗口里。或者干脆用 OpenClaw 的 Docker Compose 方式把“启动”交给 Docker不需要你自己写脚本少去一大类问题。5.3 数据库选型与数据持久化的坑OpenClaw 默认数据库是 SQLite存储到本地文件。Windows 本地部署场景我建议就用默认不要一上来就上 PostgreSQL、MySQL除非你有明确的多客户端并发需求。SQLite 单文件形式备份就是复制一个文件对个人用户实在够用。但有一个坑必须注意如果你用 Docker Compose 部署./data卷一定要挂载出来否则容器一删数据全没了。我自己有过教训容器升级后忘了把旧卷带上所有对话历史、配置、记忆信息一夜清零。这个真的能让人崩溃。检查一下你的 compose 文件确保 database 和配置文件都挂载到宿主机路径。5.4 常见问题速查表症状可能原因解决动作浏览器打不开localhost:3000容器未启动或端口映射异常查看docker compose logs openclaw对话时“模型未连接”Base URL 写错Ollama 没启动先 curl 直接测模型服务第一次响应很慢模型加载中或容器在湖边冷启动等 10–30 秒再重试中文字符乱码终端编码问题在 WSL2 下运行或在 PowerShell 里chcp 65001会话上下文没记忆数据库丢失卷没挂载检查 compose 文件 volumes 配置Docker 拉镜像特别慢网络环境限制配置国内镜像加速器再重启 Docker升级 OpenClaw 后配置丢失配置文件没持久化恢复宿主机上的./config备份排查这类问题我总结出一个底层心法分层排查。先说网络通不通、再说服务起来没有、再说配置对不对、最后说数据丢没丢。从底层往上层走永远是最快的路径千万别一条道走到黑地盯着某一个报错信息死磕。6. 部署完成后的第一件事让它变成一个真能用的助手6.1 优先调通单一闭环再扩展功能很多人在 OpenClaw 部署成功后会进入一种“我要接十个工具、配五个 channel、让它会搜索会读网页会写文章”的兴奋期。我的建议刚好相反先让它在一个最简单的场景里跑通闭环——你发一句话它调用一个固定工具给你一个正常回复。举一个我自己的例子部署完先只让它做“文件管理助手”给它配置一个简单的本地文件读取工具然后问它“帮我看看/home/user/demo.txt里写了什么”。等这个流程走通OpenClaw 的 agent 调度机制、工具调用规范、上下文记忆这些都验证过了再去扩展别的工具就顺理成章了。一上来堆十几个工具ed 效果看起来很炫实际调试时你会分不清到底是哪一环出了问题——是 prompt 没写对、工具参数不对、还是模型理解能力不够别给自己上难度先打简单副本。6.2 日常使用中的资源监控本地部署的最大的坑不是部署而是跑起来之后没人管。OpenClaw Ollama 两个服务常驻内存/显存占用都不低。我建议给 WSL2 里加一个定时任务抽查一下资源占用情况docker stats --no-stream如果发现内存占用长期接近 100%回到前面那个.wslconfig把内存配额加大或者考虑给 WSL2 设置自动回收。这个不用太激进但定期看一眼总没有坏处。6.3 升级与备份策略OpenClaw 迭代速度很快功能更新频繁。容器方式升级很爽docker compose pull docker compose up -d但升级前一定记得先备份数据目录。把./data和./config两个目录打包复制一份成本极低收益极大。我之前有一次升级后配置格式不兼容全靠备份救回来。6.4 最后说一下我踩过印象最深的一个坑有一次我在 Windows 本机上同时开着 Ollama 的桌面版和 WSL2 里的 Docker 版 OpenClawOpenClaw 一直报连接超时。排查了半天最后发现是 Ollama 在 Windows 侧只监听了 IPv4 的127.0.0.1而 WSL2 通过host.docker.internal访问时走的是虚拟网卡的另一个 IPOllama 默认没开外网监听。解决办法是把 Ollama 的环境变量OLLAMA_HOST设为0.0.0.0让它在所有网卡上监听然后重启 Ollama。这个坑非常隐蔽也不容易从报错信息里看出端倪。如果你也遇到了“WSL2 里 curl 能通、但 OpenClaw 容器里总超时”的情况先查一下你的 Ollama 到底监听了哪个地址这是我能给出的最直接的排查建议了。Windows 本地部署 OpenClaw 这件事说难也难说简单也简单。把网络、容器、模型服务这三层理清楚剩下的就是跟着报错信息逐步拆解的事。