OpenClaw 在 Windows 上的简单安装教程从零到跑通的完整记录先说明一下这篇教程聊的是 OpenClaw——一个能在本地跑起来的 AI 智能体Agent框架。这么说可能有点抽象换个角度你可以把它理解成一个“机器人管家”给它接上飞书、微信等聊天渠道再配上一个大模型比如通义千问它就能自动回复消息、定时执行任务、帮你处理信息流。之前我在这类工具上踩过不少坑尤其是 Windows 环境下的部署网上资料零零散散所以这次把自己的安装过程完整记下来写给那些想在 Windows 上快速把 OpenClaw 跑起来的朋友参考。这个教程适合谁一句话总结想本地部署 AI 智能体但不想碰 Linux、不想折腾复杂环境的 Windows 用户。你不需要太深的编程基础只要会打开命令行、能照着复制粘贴基本就能跟着走完。1. 安装前先搞清楚思路OpenClaw 到底解决什么问题1.1 别急着敲命令先弄懂 OpenClaw 是什么在做任何安装操作之前我建议你先花三分钟理解一下这个工具的本质。OpenClaw 本质上是一个开源的个人 AI 助理框架它做的事情可以拆成三层接入层负责连接各种聊天平台比如飞书、Discord、Telegram让智能体有一个“耳朵”和“嘴巴”。大脑层调用大模型 APIOpenAI、通义千问、DeepSeek 等把接收到的消息转化成意图和动作。执行层根据意图调用工具比如查天气、写文件、跑脚本、发通知。这三层结构听起来复杂但安装的时候你不需要全部搞懂只需要知道一点OpenClaw 的核心是一个 Node.js 服务外加一个配置文件。你给它一个 API Key告诉它“你的大脑用哪个模型”然后告诉它“你在哪个渠道上值班”它就能开始干活了。为什么我强调要先理解这个框架因为我在实际安装过程中发现很多人卡住的根本原因不是命令不会敲而是不知道自己在装什么、改了什么配置文件会对哪个环节产生影响。比如说你改了模型配置没生效可能是因为服务没重启服务没重启可能是因为你不知道 OpenClaw 是读取哪个文件来加载配置的。1.2 Windows 环境的两条路线WSL vs 原生安装OpenClaw 的官方文档更倾向于 Linux 和 macOS 环境Windows 上则要自己做选择。目前主流路线有两条路线优点缺点适合人群WSL2 Docker环境干净、隔离性好、卸载方便需要安装 WSL2、Docker Desktop占磁盘空间想长期使用、对稳定性要求高的人Windows 原生 Node.js安装快、不依赖虚拟机、直接跑偶尔遇到依赖编译问题环境相对“脏”只想快速试一下、机器配置一般的人这两条路线我都实测过。先说我个人的结论如果你只是想在 Windows 上体验一下 OpenClaw建议直接用原生 Node.js 方式如果你想把它当作长期服务运行建议用 Docker 方式。为什么这么建议原生方式的问题在于OpenClaw 的一些依赖包在 Windows 上偶尔需要编译如果你的电脑没装 Visual Studio Build Tools可能就会卡在某个包的安装上。而 Docker 方式虽然前期准备麻烦一点但一旦跑起来后续升级、迁移、备份都是在容器层面操作省心很多。我在下文会给出两条路线的完整步骤。就像做饭先备菜一样我把每一条路线需要的环境清单先列出来你对照自己的情况二选一就行。2. 环境准备Windows 上装 OpenClaw 的必修课2.1 路线一原生 Node.js 安装速度快适合先试水如果不是选 Docker 方式那第一步就是装 Node.js。注意这里有一个关键版本要求OpenClaw 的要求是 Node.js 18 或以上版本我自己实测用的是 20 LTS 版本运行很稳定。去 Node.js 官网下载 LTS 版本安装包就是带“长期支持”标识的那个一路下一步安装即可。装完之后我们需要验证一下环境变量是否生效。打开 PowerShell 或者 CMD输入node -v npm -v如果能看到版本号说明 Node.js 和 npm 都可用。如果提示“不是内部或外部命令”说明环境变量没配好。这时候去检查“系统属性”里的 PATH 变量看有没有包含 Node.js 的安装目录一般在C:\Program Files\nodejs\。2.2 路线二WSL2 Docker 部署环境干净适合长期跑如果选择 Docker 路线前置条件会多一些我一项一项拆开说。第一步安装 WSL2。在 Windows 11 或者较新的 Windows 10 上打开管理员权限的 PowerShell执行wsl --install这条命令会自动帮你启用 WSL 功能并安装默认的 Ubuntu 发行版。装完之后重启电脑系统会要求你设置一个 Linux 用户名和密码这个密码是 WSL 里的 sudo 密码建议用个能记住的后面经常要用。第二步安装 Docker Desktop。下载 Docker Desktop for Windows安装时保持默认选项即可。启动 Docker Desktop然后在设置里找到“Resources” - “WSL Integration”把 “Enable integration with my default WSL distro” 勾选上并在下面的列表里选择你刚装的 Ubuntu。这一步很关键漏掉它的话后面在 WSL 里敲 docker 命令会提示连不上 Docker 引擎。我当时就在这里卡了一回一直以为是 Docker 没启动其实是 WSL 集成没打开。第三步验证 Docker 环境。打开 WSL 终端在 PowerShell 里输入wsl即可进入执行docker --version docker compose version只要能看到版本信息环境就算备好了。2.3 无论如何都需要准备的东西Git 和 API Key不管走哪条路线你都需要 Git因为 OpenClaw 的源码托管在 GitHub 上安装过程通常要克隆仓库。Windows 下安装 Git 很简单官网下载安装包一路下一步。装完后在 PowerShell 里验证一下git --version然后是大模型 API Key。OpenClaw 本身不带大模型它需要调外部模型 API。目前兼容 OpenAI 格式的接口都可以用包括 OpenAI 官方 Key、通义千问的 DashScope Key、DeepSeek 等。国内用户我建议优先选通义千问或者 DeepSeek因为网络连接稳定不用折腾代理问题。这个 Key 你先去对应的模型服务商官网申请好后面配置那一步会用到。提示模型 API Key 属于敏感信息平时不要截图发到群里配置到 OpenClaw 后也注意别把配置文件上传到公开仓库。3. 两种安装方式实测从一键脚本到 Docker Compose3.1 方式A原生 Windows 一键脚本安装新手首选如果你选择原生路线OpenClaw 提供了一个自动安装脚本这是最简单的方式。在 PowerShell 中执行irm https://raw.githubusercontent.com/openclaw/openclaw/main/install.ps1 | iex这里解释一下这条命令是在干什么irm是 PowerShell 里下载网页内容的命令下载回来的是一个安装脚本然后再通过管道符传给iex来执行。整个过程就是在下载并运行远程脚本所以如果 Windows 安全中心弹出警告需要手动允许运行。脚本执行后会自动完成几件事安装必要的 npm 依赖包、生成默认配置文件、创建 .openclaw 目录。整个过程可能需要几分钟取决于网络状况。等脚本跑完OpenClaw 并没有直接启动而是提示你还需要进行配置。这时候我们先验证安装是否成功执行openclaw --version如果能看到版本号说明安装成功。如果提示找不到命令可能需要重启一下 PowerShell 让 PATH 变量生效。还有一点要提醒在国内网络环境下从 GitHub 下载脚本或依赖有时会比较慢甚至失败。如果你遇到这种情况可以使用国内的镜像源或者多试几次。npm 的话可以临时设置一下 registry 为淘宝镜像npm config set registry https://registry.npmmirror.com3.2 方式BDocker Compose 部署生产环境推荐Docker 路线稍微多几个步骤但逻辑更清晰。首先在 WSL 终端里克隆 OpenClaw 的仓库git clone https://github.com/openclaw/openclaw.git cd openclaw仓库里有现成的 Docker Compose 文件。执行docker compose up -d这里解释一下-d参数的作用它让容器在后台运行这样你关闭终端后服务不会停止。第一次执行时Compose 会拉取镜像、构建容器耗时比较长要耐心等。启动完成后执行docker ps如果看到 openclaw 相关的容器状态是 Up说明服务已经跑起来了。后续查看日志的话用docker logs -f openclaw这跟原生方式相比的好处是所有运行环境都被隔离在容器里不会污染 Windows 系统。你要是哪天不想用了直接docker compose down就能清理。3.3 安装完成后做好基础验证不管用哪种方式装好都建议走一遍基础验证流程确认服务真的在跑。OpenClaw 安装完成后会在本地起一个 HTTP 服务默认端口是 3000。你在浏览器里访问http://localhost:3000如果能看到一个简单的页面或者 JSON 响应说明服务运行正常。我当时看到的是类似{status:ok}的 JSON 数据确认服务在线。另外OpenClaw 在安装时会创建一个.openclaw目录用来存放配置和日志。原生安装下这个目录在用户主目录下C:\Users\你的用户名\.openclaw\Docker 方式下则在仓库目录里。后面改配置、看日志都在这里。4. 核心配置把 OpenClaw 真正用起来的关键设置4.1 修改主配置告诉智能体用什么模型安装只是第一步真正让 OpenClaw“听懂人话”的是配置。OpenClaw 的主配置文件是一个 JSON 文件在.openclaw目录下名叫openclaw.json。用编辑器打开这个文件你会看到类似这样的结构{ model: { provider: openai, name: gpt-4o-mini, apiKey: sk-xxxx } }这里面最核心的三个字段就是provider模型供应商、name模型名称、apiKeyAPI Key。如果使用通义千问以 DashScope 的兼容模式为例配置大致如下{ model: { provider: custom, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, name: qwen-plus, apiKey: sk-你的千问APIKey } }这里要注意baseURL是模型服务商提供的接口地址。OpenAI 格式的接口都长得差不多所以很多国产模型服务商都支持这种“兼容模式”直接填对地址就能用。提示有些模型服务商的 SDK 地址和 OpenAI 兼容地址不一样配置时一定以对方文档里写的“OpenAI 兼容地址”为准。填错了模型名字或者地址启动时会在日志里报 404 或 401 错误。4.2 Channel 配置让智能体在哪个渠道值班OpenClaw 支持多个渠道官方叫 Channel其实就是消息平台。配置文件里通常有一块channels的配置比如飞书{ channels: { feishu: { appId: cli_xxx, appSecret: your_app_secret } } }这里的 appId 和 appSecret 需要你在飞书开放平台创建应用后获取。创建应用的时候记得给应用添加“机器人”能力然后发布上线否则消息发不到你的智能体上。如果在同一台机器上跑多个 OpenClaw 实例或者给不同任务接不同渠道你可以在启动时通过命令行参数指定用哪个 Channelopenclaw start --channel feishu如果没有加这个参数OpenClaw 会启动配置里启用的所有 Channel。这个细节很容易被忽略——我在给飞书机器人配完之后发现另一个测试渠道也在同步启动日志里全是无关消息排查了半天才发现是没指定 Channel。4.3 配置完必须重启服务改配置不生效问题这一点我必须单独拿出来说因为这是我在多个群里看到新手问得最多的问题——改了配置文件但智能体行为没变化。原因很简单OpenClaw 在启动时一次性加载配置运行期间不会自动监听文件变化。所以每次改完openclaw.json都需要重启服务才能生效。原生方式下在 PowerShell 里执行openclaw stop openclaw startDocker 方式下因为配置文件通常挂载在容器里你需要重建容器让配置重新加载docker compose restart openclaw4.4 给智能体写一个“人设”系统提示词配置说实话很多人在这一步就放弃了——以为装好了就能用结果发现智能体回消息冷冰冰的完全没有“助理”的感觉。别急OpenClaw 是支持配置系统提示词System Prompt的。你可以在配置里加一个persona字段用一段自然语言描述智能体的性格、职责和行为边界。比如{ persona: 你是一个耐心的个人助理回答简洁明了不确定的事情如实说明不编造信息。 }这个字段会作为初始指令传给大模型相当于给智能体“画了一个人设”。用好这个配置体验会提升一大截。5. 踩坑实录从报错到权限的高频问题排查5.1 Agent failed before reply: session file locked这个报错我印象太深了它的完整信息长这样agent failed before reply: session file locked (timeout 60000ms)出现这个报错的原因通常是上一个 OpenClaw 进程没有正常退出导致会话文件被锁住。比如你直接关掉了 PowerShell 窗口而不是执行openclaw stop进程其实还在后台跑着下次启动时新的进程发现会话文件被旧进程占用等了一分钟还没等到锁释放就直接报错。解决办法也很直接打开任务管理器找到所有 node 进程右键结束任务。删除.openclaw目录下的会话缓存文件通常在sessions子目录下。重新启动 OpenClaw。这里最需要记住的是OpenClaw 不是关窗口就能停掉的要养成用openclaw stop停服务的习惯。5.2 飞书输出容易被截断有朋友在热搜词里提到“openclaw在飞书输出容易被截断”我也遇到过类似问题。这其实是飞书机器人自身的消息长度限制在作祟飞书单条消息最长 4096 字节超出就会被截断。解决思路是从 OpenClaw 侧输出做文章在配置里找到输出相关设置开启“分片发送”或“分段落发送”机制让智能体把长内容拆成多条消息发出来。如果 OpenClaw 版本没有这个功能备选方案是在提示词里明确要求“分点回答控制单次回复长度”靠模型自己收敛长度。这个方法治标不治本但实测能缓解大部分截断问题。比较长的文本输出比如代码、长报告建议还是让智能体写成文件再把文件发给你。5.3 端口占用、版本兼容等高频问题速查这里我把这段时间遇到过的、以及身边朋友常问的问题整理成一张速查表问题现象可能原因解决办法启动报 EADDRINUSE3000 端口被其他程序占用换端口配置里改port字段或先找出占用进程杀掉模型回复报 401API Key 填错或失效检查openclaw.json里的 apiKey确认没有多余空格模型回复报 404model 名称填错或 provider 地址不对对照模型服务商文档确认 model 标识和 baseURL启动后 Web 页面打不开服务没真正启动或端口被防火墙拦截看日志有无报错检查 Windows 防火墙是否允许 node 入站WSL 里执行 docker 失败Docker Desktop 未启动或 WSL 集成未开启动 Docker Desktop检查 WSL Integration 设置PowerShell 提示执行策略不允许脚本系统默认禁止运行 ps1 脚本管理员权限执行Set-ExecutionPolicy RemoteSigned修改配置后不生效没有重启服务执行openclaw stop后再openclaw start5.4 其他安装过程中可能遇到的小麻烦还有一个比较隐蔽的问题Windows 原生方式下如果安装依赖时看到类似node-gyp相关的报错说明某些 npm 包需要本地编译。这通常是因为机器上没有安装 C 编译工具。解决办法是管理员权限的 PowerShell 执行npm install --global windows-build-tools不过这个包比较老在 Windows 11 上偶尔会失败。我的建议是与其折腾编译环境不如直接切到 Docker 路线省得在这一步消耗耐心。另外如果你是国内网络环境npm 装依赖超时是很常见的事。除了上面提到的换 registry 镜像还可以设置 npm 的超时时间npm config set fetch-retry-mintimeout 20000 npm config set fetch-retry-maxtimeout 1200005.5 日志排查问题的风向标最后再讲一下日志。遇到任何诡异问题第一时间别瞎猜去看日志。原生方式下日志在.openclaw/logs目录里Docker 方式下直接用docker logs openclaw查看。OpenClaw 的日志会记录每一个步骤模型请求发出去了没有、渠道消息收到没有、工具调用成功没有。排查问题的时候按照“消息入口 - 模型处理 - 消息出口”的顺序依次定位很快就能找出卡在哪一环。我调试过的绝大多数问题最后都是在日志里找到答案的。写在最后的一点体会这套流程走下来我的真实感受是OpenClaw 的门槛其实不高但 Windows 下的安装确实比 Linux 多一些弯路。如果你按照上面的顺序操作先把环境准备工作做足再选择一条路线装到能跑通最后把配置一项一项过一遍大概率一个小时以内就能看到一个能回消息的智能体。从我自己的实际体验来说还有一个建议刚开始不要配置太多渠道和功能。我见过不少人一上来就想把飞书、Discord、Telegram 全接通结果某个渠道配置错了导致整体启动失败排查起来特别费劲。先用一个渠道、一个模型跑通全流程再加功能这是最稳妥的顺序。另外OpenClaw 的配置项其实有很多细节包括记忆、任务调度、定时消息等这些等你把基础跑通之后再慢慢研究也不迟。工具这东西能用起来永远比“看懂所有文档”更有价值。希望这篇教程能帮你少踩几个坑顺利在 Windows 上把 OpenClaw 跑起来。