在Windows上装Openclaw，我前前后后折腾了两轮才算把整个链路走顺。第一次纯粹是低估了环境依赖的麻烦程度，第二次又栽在配置文件的字段理解上。这项目本身很有意思——它本质上是一个本地运行的自主AI代理框架，你给它一个目标，它会自己拆解任务、调用工具、逐步执行，而不是像普通聊天机器人那样一问一答等着你喂下一步指令。对想在本地跑一个“能干活”的AI助手、又习惯Windows开发环境的人来说，Openclaw是个很值得一试的开源方案。
但说实话，官方文档对macOS和Linux的照顾明显更多，Windows用户基本属于“自己摸索”的状态。这篇指南就是把我踩过的坑、验证过的步骤、以及最后稳定运行的那套配置完整记录下来。不管是完全没接触过Node生态的新手，还是已经玩过一阵子AI代理的老手，照着这篇走，应该都能少花几个晚上的时间。
1. 安装前先想清楚：Openclaw是什么、跑在哪一层
很多人一上来就急着敲命令，结果装完跑不起来，回头查文档才发现一开始就跑偏了。所以我建议先花十分钟搞清楚Openclaw在系统里的定位，这会直接影响后面的选择。
1.1 Openclaw的核心定位：本地化自主智能体
Openclaw可以理解成一个“自带手脚”的AI助手。它不止有对话能力，还内置了浏览器控制、终端命令执行、文件读写、网页内容抓取等一堆工具。你给它一个类似“帮我把某个网页上的商品价格整理成表格”的任务，它会自己规划步骤：先打开浏览器、再定位元素、提取数据、最后写文件。整个过程你可以全程看到日志，也可以随时打断。
这意味着它不是那种调个API就完事的脚本，而是一个有状态、能持久化记忆、能调用外部工具的运行时环境。所以在Windows上装它，本质上是在装一个“AI应用服务器”——你的机器既是脑子也是手脚，所有工具调用都在本地完成，数据也留在本地。
1.2 先做选择题：原生Windows还是WSL2
这是Windows用户第一个要决策的点。Openclaw官方仓库的文档里不少命令是Linux风格的，很多教程也默认你在Linux环境操作，但这不代表Windows不能用。
| 方案 | 优点 | 缺点 | 适合人群 |
|---|---|---|---|
| 原生Windows | 路径简单、剪贴板/浏览器控制直接、无需虚拟机层 | 某些依赖需要手动装编译工具 | 大多数入门用户 |
| WSL2 | Linux环境更干净、跟Docker配合好 | 跨文件系统IO慢、浏览器自动化多一层网络转发 | 后续要容器化部署的进阶用户 |
我的建议非常简单：如果你是第一次装，直接选原生Windows。原因有两个：一是Openclaw的浏览器自动化模块在原生Windows下访问本机浏览器最直接；二是WSL2里访问Windows侧的文件经常出现权限错乱，排查起来比Windows本身的问题还头疼。等你在原生环境跑通了，真需要隔离环境再迁WSL2也不迟。
1.3 硬件和系统要求：别拿老爷机硬跑
Openclaw本身的资源占用大头在模型推理上。如果你用的是云端API（比如OpenAI兼容接口），那本机只负责逻辑编排和工具调用，内存占用不算夸张，8GB内存的机器跑起来也还行。但如果你想接本地模型（比如通过Ollama跑量化模型），那建议至少16GB内存、独立显卡更好。
系统方面，Windows 10 22H2或Windows 11都可以，但务必保证是64位系统。32位系统就别想了，Node生态和现代浏览器自动化框架早就放弃32位支持了。另外磁盘空间至少留出5GB，项目本身不大，但依赖下载、日志缓存、模型缓存这些都会占空间。
2. 环境准备：Node、Git、包管理器的版本与Windows差异
Openclaw是TypeScript项目，跑起来之前需要先把Node环境弄干净。这步是Windows用户最容易心态爆炸的地方，因为很多报错不是Openclaw的问题，而是Node链路上的问题。
2.1 Node.js版本：认准LTS，别追新
Node.js的版本选择直接影响依赖安装是否顺利。我实测的建议是安装当前最新的LTS版本，比如Node 20.x或22.x。太老的版本（16以下）会导致很多依赖包直接拒绝安装；太新的Current版本（非LTS）又可能跟某些原生模块存在兼容性问题。
如果你机器上已经装了其他Node版本，或者以后想在不同项目之间切换，强烈建议装一个nvm-windows。这东西不是npm包，需要单独去它的GitHub Releases页面下载安装包，安装完成后用管理员权限打开PowerShell执行：
nvm install 20 nvm use 20 node -v看到v20.x.x的输出就说明Node部分搞定了。这里多说一句：不要图省事直接在官网下载安装包然后一路Next，那样以后想切版本非常痛苦，而且卸载不干净还会污染环境变量。
2.2 Git与PowerShell执行策略
Openclaw的源码需要从Git拉取，所以Git是必须的。Windows下装Git没什么好说的，官网下载安装包，一路默认即可。唯一要注意的是在安装选项里把“调整PATH环境变量”选成“推荐设置”，否则后面在终端里敲git命令会提示找不到。
PowerShell执行策略也是Windows特有的一个坑。默认情况下PowerShell禁止运行任何.ps1脚本，而npm包的某些postinstall脚本就是.ps1文件。不调整的话，你会看到一堆禁止运行脚本之类的红色报错。解决办法是用管理员身份打开PowerShell：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令的意思是：本地创建的脚本可以运行，从网上下载的脚本需要数字签名。日常使用足够安全，又不会挡住安装流程。
2.3 包管理器：推荐pnpm，但npm也能用
Openclaw这类依赖很多的TypeScript项目，用pnpm能省不少磁盘空间，安装速度也快。安装pnpm最简单的方式是先用npm把corepack启用：
npm install -g pnpm或者如果你用的是Node 20以上，可以直接：
corepack enable pnpm装完后验证一下pnpm -v。如果提示“无法识别”，多半是全局bin目录没加入PATH。npm全局目录一般在%APPDATA%\npm，手动加进环境变量就行。
2.4 node-gyp的Windows依赖：这一步不做，后面必踩坑
很多原生依赖包（比如SQLite相关的、某些加密库）在安装的时候需要本地编译，编译工具链在Windows上不是自带的。你会在pnpm install中间看到类似node-gyp rebuild然后报错的情况。
提前装好Visual Studio Build Tools可以避开绝大多数问题。具体操作：去Visual Studio官网下载Build Tools安装器，运行后勾选“使用C++的桌面开发”工作负载，右侧细节里确保包含Windows SDK。这个安装包比较大，但值得等。装完之后重启终端，再跑后续安装就顺畅了。
提示：如果公司电脑不方便装VS Build Tools，可以试试
npm install --global windows-build-tools（已废弃但部分场景仍可用），或者直接绕过需要编译的依赖，但那样可能失去部分功能。我的经验是：能装 Build Tools 就装，这是最省心的路。
3. 拉取项目与安装依赖：三个容易卡住的环节
环境准备好之后，真正装Openclaw反而没什么高难度动作。但我在这个阶段遇到过三个容易让人抓狂的问题，逐个说清楚。
3.1 获取源码：目录命名是个隐形地雷
既然是开源项目，源码直接从官方仓库拉。假设你在终端里执行：
git clone <Openclaw官方仓库地址> openclaw cd openclaw这里我要单独强调路径问题：项目目录绝对不能放在含有中文或空格的路径下。比如D:\项目\openclaw这种，后期node_modules里的某些工具会解析路径出错，报一堆你根本想不到的错。最好放在纯英文路径下，比如D:\dev\openclaw。
另外建议直接放在磁盘根目录一级，不要嵌套太多层。Windows的路径长度默认限制是260个字符，node_modules装完后目录层级深得离谱，路径一长就容易触发ENAMETOOLONG报错。虽然新版Node支持长路径，但没必要冒险。
3.2 pnpm install：别让网络和缓存卡死你
在项目根目录执行：
pnpm install这一步会拉取上百个依赖包。如果网络状况一般，大概率会碰到某个包下载超时然后整个安装失败。我的处理方案是给pnpm配置镜像源：
pnpm config set registry https://registry.npmmirror.com注意：镜像源只改下载地址，不改lockfile的完整性校验逻辑，所以不用担心依赖被“掉包”。装完之后可以改回来，也可以留着，影响不大。
如果安装过程中卡在某个阶段超过三分钟没动静，直接Ctrl+C中断后重新跑。pnpm有缓存，重新跑会跳过已下载的包，速度反而更快。千万别挂在那干等，我之前有一次等了二十分钟没动，最后发现是某个包的postinstall脚本在等待输入，而终端根本没显示提示。
3.3 安装后先看结构：找到配置文件和启动脚本
依赖安装完成后，先别急着启动。花两分钟看一下项目根目录的结构，通常你会看到：
package.json：项目入口和脚本命令openclaw.config.ts（或.json）：主配置文件，后面所有核心设置都在这data/：运行时数据目录，包括日志、记忆存储等tools/或src/：内置工具和源码
用编辑器打开package.json，找到scripts节点，了解一下有哪些可用的命令。一般会有start、dev、build之类的。Windows下执行pnpm start之前，建议先看一眼start脚本的内容，确认入口文件是编译后的dist还是直接用tsx跑源码，这会影响你改配置后需不需要重新构建。
4. 配置模型与运行参数：让代理真正“开口说话”
Openclaw本身只是个框架，它需要连接一个大模型才能具备决策和推理能力。所以配置的核心就是告诉它：用哪个模型接口、用哪个密钥、允许多长的执行链路。
4.1 必须配置的核心项：模型接口、API Key、端口
打开配置文件，你会看到类似这样的结构（不同版本字段名可能有差异，但逻辑一致）：
export default { model: { // 兼容OpenAI接口的任意模型服务 provider: "openai-compatible", baseURL: "https://api.example-llm.com/v1", apiKey: "sk-xxxx", name: "your-model-name", temperature: 0.2, maxTokens: 4096 }, server: { host: "127.0.0.1", port: 3210 }, tools: { enabled: ["browser", "terminal", "filesystem", "web_search"] }, memory: { enabled: true, type: "sqlite" } }这里解释一下几个关键字段：
provider填openai-compatible，意味着任何兼容OpenAI接口格式的模型服务都能接。大厂API、开源模型网关、甚至本地跑的模型服务都可以，只要暴露的是标准/v1/chat/completions接口。apiKey就是你的密钥。建议不要直接硬编码在配置里，而是通过环境变量注入。baseURL是接口地址。如果你接的是代理网关或者本地模型，这里填对应的地址就行。temperature控制随机性。做任务型代理建议调低到0.2左右，让它按部就班执行；搞创意写作再调高。port是Openclaw本地服务的监听端口。默认3210我用着没跟其他服务冲突，但如果你的机器上有别的服务占用了，改成别的端口即可。
4.2 环境变量的优先级：密钥永远不要写进代码
配置文件里直接写API Key最大的问题是：如果哪天你把项目分享出去或者上传到远程仓库，密钥就泄露了。正确做法是用环境变量占位：
apiKey: process.env.OPENCLAW_API_KEY || "",然后在项目根目录新建一个.env文件：
OPENCLAW_API_KEY=sk-xxxx OPENCLAW_MODEL_NAME=your-model-name OPENCLAW_PORT=3210很多项目框架会自动加载根目录下的.env文件。如果没有，需要安装dotenv或在启动命令里指定node --env-file=.env。具体看你项目用的Node版本，Node 20.6以上直接支持--env-file参数。
4.3 工具权限配置：能不开的尽量不开
配置里有一块非常值得花心思：启用哪些工具。很多人为了省事直接全开，但我强烈不建议一上来就给终端和文件系统权限。你想想，一个AI代理如果拿到了终端执行权限，它就能运行任意命令——万一它理解错你的意图，执行了一个破坏性命令，后果是你自己承担。
我个人的保守配置是：
tools: { enabled: ["browser", "filesystem"] }先用这两个跑通基础任务，对它的行为模式有底了，再逐步开启终端权限。另外注意，Openclaw通常支持allowlist和denylist按路径/域名做限制，比如只允许它读写D:\work\output下的文件，只允许它访问example.com域名。这种限制建议尽早配置，尤其当你要交给AI执行自动化任务时。
4.4 其他值得调的参数：最大步数、工作目录、超时时间
maxSteps：限制AI执行任务的最大步骤数。默认可能比较宽松，但为了防止它进入死循环无限调用，建议设个50步左右的上限。workdir：AI操作文件时的工作目录。把它指向一个专门的沙箱目录，别让它默认在项目根目录里乱翻。timeout：单次工具调用的超时时间。网络请求类的工具建议设60秒以上，文件类操作可以设短一点。
这些参数在官方文档里一般都比较零散，但实际跑起来特别有用。我第一次跑任务时AI在网页里定位元素失败后反复重试，如果没有maxSteps限制，它能把自己卡在那里一晚上。
5. 首次启动与任务实测：从日志里读懂运行状态
配置写好了，启动就是临门一脚。但首启往往伴随各种意外，我建议先明确预期：启动日志里看到什么才算正常，跑一个什么任务才算真正验证成功。
5.1 启动命令与正常日志
如果你拉取的版本默认入口是编译后的代码，那直接：
pnpm start如果是开发模式（改动配置后自动热重载）：
pnpm dev正常启动后，终端输出大致长这样：
[info] Openclaw server listening on http://127.0.0.1:3210 [info] Model connected: your-model-name [info] Tools registered: browser, filesystem [info] Memory loaded: 0 records看到这几行，说明整个链路已经通了。此时你可以打开浏览器访问http://127.0.0.1:3210，应该能看到一个简单的管理界面或API文档页面。如果管理界面打不开，先确认端口写没写对，再看防火墙有没有拦截。
5.2 用一个小任务验证“规划→执行→产出”链路
很多人启动成功后问的第一句“我能做什么”，我建议不要直接拿一个复杂的真实任务去试，先用最简单的来验证：让AI创建一个Markdown文件并写入指定内容。例如：
“创建一个test.md文件，内容是一个标题为‘安装验证’的文档，里面写上‘Openclaw运行正常’。”
如果配置没问题，你会看到AI这样行动：先调用文件系统工具创建文件，再调用写入操作，最后回复你“已完成”。然后你去工作目录验证一下文件确实存在且内容正确。
这个任务虽然简单，但它验证了三个关键能力：模型调用正常、配置生效、文件系统工具真的能用。这三样没问题，后续换复杂任务只是增加工具调度，不会再有链路性的故障。
5.3 观察执行过程：理解它的“思考链”
在任务执行过程中，终端或管理界面会实时输出AI的推理摘要和工具调用记录。第一次跑的时候大家都容易忽略这部分，但我建议刻意观察一下。比如你会发现AI在创建文件前会先检查目录是否存在，这不算多余，而是LLM在规划阶段自己整理出来的步骤。你也能通过日志判断模型是不是真的理解了你给的目标，如果它反复做无用功，可能是模型温度太高、指令不够清晰，或者工具权限缺了某项。
5.4 首启常见错误与应急处理
| 错误现象 | 可能原因 | 解决办法 |
|---|---|---|
EADDRINUSE | 端口被占用 | 换端口，或netstat -ano查占用进程后结束它 |
Cannot find module | 依赖没装完 | 删除node_modules后重新pnpm install |
MODULE_NOT_FOUND但指向内置模块 | 版本不匹配 | 检查Node版本，切到LTS |
| 模型请求超时 | API地址不可达或密钥错 | 先用curl测试API连通性，再核对配置 |
| 中文乱码 | 终端编码不对 | 在PowerShell执行chcp 65001，或改用Windows Terminal |
6. Windows下的高频报错与排查清单
这个章节是重点，我把在Windows上跑Openclaw过程中真正让我浪费过时间的报错整理出来，按排查顺序和优先级讲，遇到问题可以直接对照。
6.1 权限类报错：EPERM、EACCES、Access denied
这类报错在Windows上出现的频率远高于Linux，因为它们对应的往往是文件占用或权限策略，而不是源码问题。
比如EPERM: operation not permitted, unlink ...，多半是杀毒软件或Windows Defender实时保护正在扫描node_modules目录，导致pnpm删除文件时被锁定。解决办法是把项目目录加入Defender的排除列表，或者临时关闭实时保护后重新安装依赖。
另外不要用管理员权限跑Openclaw。听起来反直觉，但在Windows上，用管理员身份运行的进程反而可能触发UAC虚拟化，导致文件路径“看起来存在但实际访问不到”。普通用户权限跑本地服务完全够用。
6.2 终端类问题：命令识别不了、脚本路径找不到
最常见的是pnpm: 无法识别，即使你已经npm install -g pnpm。原因基本是npm的全局bin目录不在PATH里。执行下面的命令看输出路径：
npm prefix -g然后把输出目录加入系统环境变量PATH。加入后需要重启终端或重开PowerShell窗口才会生效。
还有个很隐蔽的问题：如果你在PowerShell里执行的是pnpm.cmd命令，有时Windows会弹出安全提示“是否允许此应用对你的设备进行更改”，点了“否”就会报错。本质是执行策略和SmartScreen的干扰。给当前用户设置RemoteSigned后基本可以避免（前面已经讲过）。
6.3 安装卡死与网络问题
pnpm install卡死，除了网络原因还有一种可能是抗病毒软件对大量文件操作的实时扫描导致CPU打满。你可以开任务管理器看一眼，如果MsMpEng.exe（Defender进程）CPU占用接近100%，基本就是它在拖后腿。把项目目录加入排除列表，重新安装，速度会快得让你怀疑人生。
如果换了镜像源还是超时，可以试试在 pnpm 配置里增加超时时间和重试次数：
pnpm config set fetch-timeout 120000 pnpm config set fetch-retries 56.4 浏览器自动化启动失败：找不到浏览器或CDP端口冲突
Openclaw的任务里如果涉及网页操作，本质上是在本地启动一个浏览器实例或连接已运行的浏览器。Windows下常见报错是“找不到可执行浏览器”或“Chrome版本不匹配”。解决办法通常是安装Chromium内核的浏览器，或者确保你本机Chrome/Edge版本足够新。
如果提示CDP端口被占用，说明上一次任务结束后浏览器进程没有完全退出。打开任务管理器，把所有浏览器子进程结束掉，重新试试。为了避免这种残留进程问题，我习惯在配置里给浏览器工具设置一个独立的调试端口，比如9222，并开启超时自动关闭。
6.5 防火墙拦截导致本机服务访问不了
理论上监听127.0.0.1的服务不会触发防火墙，但如果你改成了0.0.0.0，或者系统有第三方安全软件，就可能出现服务启动了但浏览器访问不了的情况。排查时先确认监听地址：
netstat -ano | findstr 3210如果监听地址是[::]或0.0.0.0，防火墙大概率会弹窗询问是否允许通信。你要是手滑点了“取消”，后续所有网络请求都会失败。这时候去“Windows安全中心”→“防火墙和网络保护”→“允许应用通过防火墙”，手动添加Node.js的可执行文件。
6.6 排查方法论：永远先看日志，再猜原因
在Windows上报错的一个通病，是大家习惯于看到红字就发群里问，而不是自己看日志。Openclaw会把运行日志写到项目目录下的data/logs里，多深的报错都会被记录。遇到问题先打开这个日志文件，翻到最后几十行，再对照报错信息定位。我在实际排查中，超过七成的问题在日志里都能直接看到根因，根本不需要猜。
7. 从“能跑”到“好用”：记忆、MCP与自动化扩展
安装只是开始，真正让Openclaw发挥价值的是把它变成你的自动化助手。Windows环境下，下面这三个扩展方向最实用。
7.1 让AI记住上下文：持久化记忆配置
Openclaw的记忆模块默认可能只是运行时的，关掉进程就忘光了。你可以配置持久化记忆，让它记住你的工作习惯、常用命令、甚至是偏好设置。配置里memory.type可以选sqlite（轻量但够用），也可以选支持向量的类型做语义记忆。
语义记忆的好处是：你之前让AI处理过类似任务，下次再遇到它会主动参考上次的处理方式。实测下来，这个功能在重复性办公任务中特别省心。比如我让它定期整理某个文件夹的报表格式，它记住一次模板之后，后续每次处理都直接套用，不再需要重新描述格式要求。
7.2 接入MCP扩展：把Openclaw变成连接器
如果你之前接触过MCP协议，那理解起来很容易——MCP就是给AI代理接入外部数据工具的标准接口。Openclaw支持作为MCP客户端连接各类MCP服务器，这意味着你能让AI操作数据库、读取私有知识库、甚至连接到团队内部系统。
Windows下启用MCP主要是配置文件里加一段mcpServers：
{ "mcpServers": { "local-docs": { "command": "npx", "args": ["some-mcp-server", "--path", "D:/docs"] } } }这里command可以用绝对路径避免npx在Windows下解析不到的问题。接入MCP服务器后，AI的判断能力会上一个台阶——它不再只会调用内置工具，而是能查到你公司的内部数据再给出决策。
7.3 定时任务与自动化：规划你的无人值守流程
Windows下可以用“任务计划程序”定时触发Openclaw的任务API。比如每天早上9点让AI读取某个文件夹里新增的文档，提取摘要后保存到指定目录、并把结果发送到你的即时通讯工具。配置计划任务时，操作里填：
- 程序：
node - 参数：
path/to/trigger-script.js - 起始于：
D:\dev\openclaw
触发脚本本质上就是调用Openclaw的HTTP API发送创建任务的请求。这种方式的好处是AI每次运行都会有日志，你可以回溯它干了什么，且不占用你自己的手工操作时间。
7.4 运行维护：日志清理、进程管理、资源占用
Openclaw跑久了会积累两类东西：日志文件和记忆数据。日志文件如果不清理，几个月能攒好几个GB。我自己的习惯是写一个简单的批处理脚本，每周清理一次超过30天的日志。记忆数据不建议随便删，因为那是AI的“经验”，删了它对你的了解就清零了。
进程管理方面，Windows下关闭Openclaw不要直接关终端窗口，那样可能出现子进程残留（尤其是浏览器自动化进程）。正确做法是在管理界面调用关闭接口，或者按Ctrl+C让进程走正常退出流程。如果发现端口还被占用，按前面文章里提到的方法用netstat找到残留进程并结束它。
最后再分享一点个人的使用心得
这套Windows安装流程我走完一遍之后，最大的体会是：Openclaw这类自主代理框架，难点从来不是“装起来”，而是“用好它”。装好只是第一步，更关键的是理解它的运行逻辑——它不是一个简单的调用接口，而是一个会自己规划、自己执行、偶尔还会跑偏的AI智能体。
给准备入门的你三个建议：第一，第一次跑任务务必先用小任务验证，别一上来就让它操作重要文件；第二，工具权限要一步步给，先文件系统后终端命令，宁缺毋滥；第三，日志是最好的老师，Windows下的报错五花八门，但绝大多数看日志就能找到答案。把这些基础打好，Openclaw在你机器上就能真正成为一个靠谱的数字助手，而不是一个装完就吃灰的玩具。
