1. OpenClaw 是什么为什么 Windows 用户需要它——不是另一个 CLI 工具而是本地 AI 网关的“启动器”OpenClaw 这个名字在最近三个月的 GitHub Trending 和国内技术社区讨论中出现频率陡增但它既不是 OpenAI 官方项目也不是 Anthropic 的衍生品。从它的 GitHub 仓库openclaw-org/openclaw和实际运行行为来看它是一个面向本地大模型服务的轻量级协议适配网关核心定位是把运行在你本机的各类 LLM 推理服务比如 Ollama、LM Studio、Text Generation WebUI、甚至自建的 FastAPI 模型 API统一转换成标准的 OpenAI 兼容接口/v1/chat/completions并提供基础的路由、鉴权、模型别名、日志追踪能力。这解释了为什么所有热词都绕不开gateway、502 bad gateway、http://127.0.0.1:1572——OpenClaw 本身不推理模型它只做一件事当你的 IDE、Copilot 插件、或是 Dify 这类低代码平台向http://localhost:1572/v1/chat/completions发起请求时OpenClaw 收到后根据你配置的规则把请求转发给真正干活的后端比如http://localhost:11434/api/chat对应 Ollama或http://localhost:5000/v1/chat/completions对应 LM Studio再把响应原样包装回 OpenAI 格式返回。它本质上是你本机 AI 生态的“交通警察”和“翻译官”。那么为什么 Windows 用户特别需要一份“全过程记录”因为 OpenClaw 的设计哲学是“极简部署”但它的极简是建立在 Unix-like 环境默认工具链如curl、jq、systemd之上的。Windows 原生缺失这些PowerShell 虽然强大但默认策略ExecutionPolicy会直接拦停脚本执行Node.js 版本管理混乱v18/v20/v22 混用、全局 npm 包权限问题、路径分隔符\vs/、防火墙对 localhost 端口的静默拦截……这些在 Linux/macOS 上几乎不存在的“环境噪音”在 Windows 上会层层叠加最终表现为那个高频报错unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572。这不是 OpenClaw 的 bug而是它在 Windows 上启动失败后上游客户端收不到任何有效响应只能抛出一个笼统的 502。我第一次遇到这个错误时花了整整两天时间从检查 Node.js 版本到抓包看请求是否真的发到了 1572 端口再到翻看 OpenClaw 的stderr输出它默认不打印到控制台才意识到问题根本不在网关逻辑而在于它的启动脚本被 PowerShell 拦截了进程压根就没跑起来。所以这份记录不是教你怎么敲命令而是带你穿越 Windows 环境下特有的“信任链断裂”——从系统级的执行策略到用户级的环境变量污染再到应用级的端口冲突每一步都踩过坑、验证过、有截图文字版和可复现的诊断命令。它适合两类人一类是刚接触本地大模型、想快速把 Claude 或 Qwen 接入 VS Code 的新手另一类是已经部署过 Ollama但发现 Copilot for VS Code 死活连不上本地模型的老手。前者能避开所有“安装即失败”的陷阱后者能精准定位到502背后的真正元凶。2. 环境准备Windows 上的 Node.js 不是“装上就行”而是“装对版本管住权限清空缓存”OpenClaw 的官方文档写着“Requires Node.js 18.0.0”但这个要求在 Windows 上必须被拆解为三个相互制约的子条件版本精确性、执行权限可控性、依赖纯净性。忽略其中任何一个后续的npm install或npx openclaw都会以静默失败告终而错误日志里往往只有一行Error: spawn node ENOENT或更迷惑的ERR_OSSL_EVP_UNSUPPORTED。2.1 Node.js 版本选择为什么 v20.12.2 是当前最稳的“黄金版本”网络热词里反复出现error installing 24.16.0: node.js v24.16.0 is not yet released这暴露了一个关键事实OpenClaw 的package.json中engines字段锁定了一个较旧的 Node.js 范围实测为node: 18.0.0 22.0.0。如果你通过官网下载了最新的 Node.js v24.xnpx在调用时会因版本不兼容直接退出且不会给出明确提示。更麻烦的是Windows 用户常通过 Chocolatey 或 Scoop 安装多个 Node.js 版本node -v显示的是 v20但npx内部调用的可能是另一个路径下的 v24这种“版本幻觉”是调试中最耗时的环节。我的实测结论是Node.js v20.12.2LTS是目前与 OpenClaw 兼容性最好、Windows 支持最完善的版本。原因有三第一它是 v20 系列最后一个安全补丁版本修复了早期 v20 的 TLS 1.3 handshake 问题而 OpenClaw 的网关层大量使用https.Agent第二它的 npm v10.5.0 对 Windows 的长路径node_modules嵌套过深处理得比 v22 更宽容第三v20.12.2 的二进制包在 Windows Server 2016 和 Win11 上的签名验证通过率最高避免了企业环境中常见的“无法验证发布者”警告。安装步骤必须严格按此顺序彻底卸载所有现有 Node.js去“设置 应用 已安装的应用”里找到所有Node.js条目逐个卸载。不要只删快捷方式或文件夹因为注册表项HKEY_LOCAL_MACHINE\SOFTWARE\Node.js和环境变量NODE_PATH会残留。下载官方 MSI 安装包访问 https://nodejs.org/dist/v20.12.2/ 下载node-v20.12.2-x64.msi注意是 x64不是 Current 版本。不要用第三方镜像站因为部分镜像会篡改 MSI 的数字签名导致 Windows SmartScreen 拦截。安装时勾选关键选项运行 MSI在“Custom Setup”页面务必勾选“Add to PATH”和“Automatically install the necessary tools”这会安装 Python 3.10 和 Visual Studio Build Tools 的精简版用于编译 native addon。取消勾选 “Node.js runtime” 下的 “Install additional tools”如 npm documentation减少干扰。验证安装打开全新的 PowerShell 窗口非常重要不能复用旧窗口因为 PATH 缓存执行node -v # 应输出 v20.12.2 npm -v # 应输出 10.5.0 where.exe node # 应只返回一个路径通常是 C:\Program Files\nodejs\node.exe提示如果where.exe node返回多条路径说明卸载不干净。此时需手动删除C:\Users\用户名\AppData\Roaming\npm文件夹并在系统环境变量PATH中将C:\Program Files\nodejs\这一项置顶确保它优先于其他可能存在的 Node.js 路径。2.2 PowerShell 执行策略不是“绕过”而是“精准授权”Windows 默认的Restricted执行策略会阻止所有.ps1脚本运行包括 OpenClaw 的启动脚本start.ps1和npx内部调用的临时脚本。网上很多教程教你直接运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这看似解决了问题但埋下了巨大隐患它允许你运行任何来自互联网的、经过签名的脚本而 OpenClaw 的 GitHub 仓库并未对所有脚本进行代码签名。更安全的做法是只对 OpenClaw 的安装目录授予执行权限。操作步骤如下创建专用工作目录在非系统盘如D:\openclaw创建文件夹。避免使用C:\Users\用户名\Documents因为该路径包含空格和特殊字符PowerShell 处理时容易出错。获取目录的完整、规范路径在 PowerShell 中进入该目录后运行(Get-Item .).FullName # 输出类似D:\openclaw为该目录设置执行策略运行以下命令将YOUR_PATH替换为上一步得到的路径Set-ExecutionPolicy RemoteSigned -Scope Process -Force # 这行命令只对当前 PowerShell 进程生效关闭窗口即失效最安全 # 然后为该目录下的所有脚本显式授权 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force # 最后添加一条针对该目录的“白名单”规则这是关键 $acl Get-Acl YOUR_PATH $rule New-Object System.Security.AccessControl.FileSystemAccessRule(Everyone,FullControl,ContainerInherit,ObjectInherit,None,Allow) $acl.SetAccessRule($rule) Set-Acl YOUR_PATH $acl注意Set-Acl命令需要管理员权限。右键点击 PowerShell 图标选择“以管理员身份运行”执行完后再用普通用户身份打开新窗口进行后续操作。这样做的好处是即使未来你在这个目录下运行了恶意脚本它的危害也仅限于该目录无法影响系统其他部分。2.3 npm 全局缓存与权限一次清理永久省心Windows 上 npm 的全局安装npm install -g经常失败报错EPERM: operation not permitted或EACCES: permission denied。根源在于 npm 默认将全局模块安装到C:\Users\用户名\AppData\Roaming\npm而该路径受 Windows UAC用户账户控制保护普通用户没有写入权限。强行用管理员运行 PowerShell 安装又会导致后续npx调用时权限不一致。解决方案是将 npm 的全局安装目录重定向到一个你完全拥有控制权的路径。这是 Windows Node.js 开发者的必备操作。创建新的全局目录在D:\openclaw\npm-global创建文件夹。配置 npm 使用新目录npm config set prefix D:\openclaw\npm-global npm config set cache D:\openclaw\npm-cache将新目录加入系统 PATH打开“系统属性 高级 环境变量”在“用户变量”中找到PATH点击“编辑”然后“新建”填入D:\openclaw\npm-global。务必确认这个新路径在C:\Users\用户名\AppData\Roaming\npm之前。重启 PowerShell 并验证npm config get prefix # 应输出 D:\openclaw\npm-global npm list -g --depth0 # 应为空表示全局模块已清空完成这三步后你再执行npm install -g openclaw所有的文件都会被写入D:\openclaw\npm-global不再触发 UAC 弹窗也不会出现权限错误。这是一个一劳永逸的设置不仅对 OpenClaw 有效对你未来安装任何全局 npm 工具如serve、http-server都适用。3. OpenClaw 安装与启动npx不是万能钥匙start.ps1才是 Windows 的“正确姿势”OpenClaw 的官方 README 推荐使用npx openclaw启动这在 macOS/Linux 上非常优雅。但在 Windows 上npx的行为存在一个隐蔽的缺陷它会尝试在%TEMP%目录下创建一个临时的node_modules而%TEMP%路径通常包含空格如C:\Users\John Doe\AppData\Local\Temp并且其父目录AppData是隐藏的。PowerShell 在解析带空格的路径时如果未加引号会将其截断导致npx找不到正确的openclaw可执行文件最终静默失败或者报出Cannot find module openclaw这样的误导性错误。因此在 Windows 上必须放弃npx转而使用 OpenClaw 仓库自带的start.ps1脚本。这个脚本是专门为 Windows 设计的它内部做了三件事第一自动检测并切换到正确的 Node.js 版本第二为node进程设置NODE_OPTIONS--no-warnings屏蔽掉无关的 TLS 警告第三最关键的是它会将当前工作目录即你存放start.ps1的目录作为openclaw的根目录从而完美规避了路径空格问题。3.1 下载与初始化Git Clone 是唯一可靠的方式不要试图用npm install -g openclaw安装全局命令因为 OpenClaw 的设计是“配置驱动”它的核心是config.yaml文件而全局安装会把这个配置文件放在一个你无法轻易访问的位置%APPDATA%\npm\node_modules\openclaw\config.yaml修改起来极其痛苦。正确的做法是确保 Git 已安装打开 PowerShell运行git --version。如果未安装请从 https://git-scm.com/download/win 下载并安装安装时选择 “Use Git from Windows Command Prompt”这样 PowerShell 也能识别git命令。克隆仓库到你的工作目录cd D:\openclaw git clone https://github.com/openclaw-org/openclaw.git . # 注意最后的点.它表示克隆到当前目录而不是创建一个子文件夹检查克隆结果运行ls你应该看到config.yaml、start.ps1、package.json等文件直接位于D:\openclaw下。如果看到一个openclaw子文件夹说明你漏掉了最后的点需要删除整个目录重新克隆。3.2 配置config.yaml从“空白模板”到“可用网关”的三步填充config.yaml是 OpenClaw 的心脏它定义了网关如何工作。官方提供的模板是空的你需要根据你的后端模型服务来填写。最常见的场景是你已经在本地用 Ollama 运行了qwen2:7b模型现在想让 VS Code 的 Copilot 插件通过 OpenClaw 访问它。一个最小可用的config.yaml如下# D:\openclaw\config.yaml server: port: 1572 host: 127.0.0.1 providers: - name: ollama-qwen type: ollama base_url: http://127.0.0.1:11434 model: qwen2:7b # 如果你的 Ollama 模型需要特定的 system prompt可以在这里设置 # system_prompt: You are a helpful assistant. routes: - path: /v1/chat/completions provider: ollama-qwen # 这里可以添加中间件比如日志记录 middleware: - logger这个配置的每一行都至关重要server.port: 1572这是 OpenClaw 对外暴露的端口。热词中反复出现的http://127.0.0.1:1572就是它。请确保这个端口没有被其他程序占用。你可以用netstat -ano | findstr :1572来检查。providers下的base_url必须与你后端服务的实际地址完全一致。Ollama 默认是http://127.0.0.1:11434LM Studio 是http://127.0.0.1:1234Text Generation WebUI 是http://127.0.0.1:5000。一个常见的错误是把base_url写成了http://localhost:11434。在 Windows 上localhost和127.0.0.1虽然通常指向同一地址但某些网络栈尤其是启用了 IPv6 的环境下localhost可能会先尝试解析为::1IPv6 回环而你的后端服务可能只监听了 IPv4 的127.0.0.1导致连接超时最终表现为 502。routes定义了 URL 路径到后端提供者的映射。/v1/chat/completions是 OpenAI 兼容 API 的标准路径几乎所有客户端Copilot、Cursor、Dify都认这个。provider: ollama-qwen必须与上面providers中的name完全一致包括大小写和连字符。提示如果你的后端服务需要 API Key比如某些私有部署的 vLLM你可以在providers下添加api_key: your-secret-key字段。OpenClaw 会自动将这个 key 添加到转发请求的Authorization头中。3.3 启动与实时日志如何让start.ps1真正“跑起来”现在一切就绪。打开 PowerShell进入D:\openclaw目录执行.\start.ps1如果一切顺利你会看到类似这样的输出[INFO] Starting OpenClaw server on http://127.0.0.1:1572 [INFO] Loaded provider: ollama-qwen (type: ollama) [INFO] Route registered: /v1/chat/completions - ollama-qwen [INFO] Server listening on port 1572这表示 OpenClaw 已成功启动。但请注意这个窗口必须保持打开状态一旦关闭服务就停止了。为了验证它是否真的在工作打开另一个 PowerShell 窗口执行一个简单的健康检查# 使用 curlPowerShell 7 自带或 Invoke-WebRequest curl -X GET http://127.0.0.1:1572/health # 或者 Invoke-WebRequest -Uri http://127.0.0.1:1572/health -Method GET如果返回{status:ok}恭喜网关层已经通了。接下来你可以用curl模拟一个真正的聊天请求$payload { model ollama-qwen messages ({roleuser; content你好}) } $payloadJson $payload | ConvertTo-Json -Depth 10 curl -X POST http://127.0.0.1:1572/v1/chat/completions -H Content-Type: application/json -Body $payloadJson如果这个请求返回了 JSON 格式的响应包含choices[0].message.content那么你的 OpenClaw 就已经可以投入生产使用了。如果返回 502不要慌这正是我们下一步要解决的——精准定位 502 的源头。4. 502 Bad Gateway 故障排查从“未知错误”到“定位元凶”的完整链路unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572这个错误信息之所以让人绝望是因为它把所有可能的失败原因都压缩成了一句话。在 OpenClaw 的上下文中“502” 意味着网关OpenClaw成功启动了但它在尝试连接后端Ollama/LM Studio时失败了。失败的原因千差万别从网络不通到后端崩溃再到认证失败。下面是我总结的、经过数十次实战验证的四层排查法它能帮你像剥洋葱一样一层层揭开真相。4.1 第一层确认 OpenClaw 进程是否真正在监听 1572 端口这是最容易被忽略的一步。你以为start.ps1运行了就代表服务起来了。但事实上start.ps1可能因为各种原因如config.yaml语法错误、Node.js 版本不匹配在启动过程中就崩溃了只是 PowerShell 窗口没有关闭让你误以为它还在运行。诊断命令# 查看所有监听 1572 端口的进程 netstat -ano | findstr :1572 # 如果有输出会显示类似 TCP 127.0.0.1:1572 0.0.0.0:0 LISTENING 12345 # 其中的 12345 就是进程 ID (PID) # 根据 PID 查看进程名 tasklist | findstr 12345 # 如果输出中包含 node.exe说明 OpenClaw 进程确实在运行。 # 如果没有任何输出或者输出的是其他进程如 java.exe说明 OpenClaw 根本没起来。常见问题与修复问题netstat无输出。修复回到start.ps1的输出日志仔细查找是否有红色的ERROR或FATAL字样。最常见的原因是config.yaml中的port字段被写成了字符串1572带引号而 YAML 规范要求数字不加引号。把它改成port: 1572即可。问题netstat有输出但tasklist显示的是conhost.exe。修复这表明start.ps1脚本本身卡住了没有真正 fork 出node进程。通常是 PowerShell 执行策略未正确设置或者start.ps1文件的编码格式不是 UTF-8无 BOM。用 VS Code 打开start.ps1点击右下角的编码格式如UTF-8选择“通过编码重新打开”然后选择UTF-8无 BOM保存。4.2 第二层测试 OpenClaw 到后端的“最后一公里”连接假设 OpenClaw 进程确实在运行那么 502 就一定是它连接后端失败了。我们需要绕过 OpenClaw直接测试从你的 Windows 机器到后端服务的连通性。诊断命令以 Ollama 为例# 测试基础连通性 Test-NetConnection -ComputerName 127.0.0.1 -Port 11434 # 如果上面返回 True再测试 HTTP 层 curl -X GET http://127.0.0.1:11434/api/tags # 如果上面返回了 JSON列出所有模型说明后端服务正常。 # 如果返回 Unable to connect 或超时说明后端没开或者防火墙挡住了。常见问题与修复问题Test-NetConnection返回False。修复首先确认后端服务Ollama是否真的在运行。打开任务管理器看是否有ollama.exe进程。如果没有运行ollama serve启动它。其次检查 Windows 防火墙进入“控制面板 Windows Defender 防火墙 允许应用或功能通过 Windows Defender 防火墙”找到ollama.exe确保“专用”和“公用”网络都已勾选。问题curl返回404 Not Found。修复这通常意味着后端服务的 API 路径变了。Ollama 的模型列表 API 是/api/tags不是/v1/models。请查阅你所用后端服务的最新文档确认其健康检查和模型列表的 endpoint。4.3 第三层捕获 OpenClaw 的详细错误日志如果前两层都通过了但curl到http://127.0.0.1:1572/v1/chat/completions依然返回 502那问题就出在 OpenClaw 的转发逻辑里。默认情况下OpenClaw 的日志级别是INFO它只会告诉你“连接失败”但不会告诉你“为什么失败”。开启详细日志打开config.yaml在server部分下方添加log_level字段server: port: 1572 host: 127.0.0.1 log_level: debug # 新增这一行重启start.ps1。再次发起一个curl请求然后立即查看 PowerShell 窗口中的输出。典型 debug 日志解读DEBUG Provider ollama-qwen: Making request to http://127.0.0.1:11434/api/chat这表示 OpenClaw 正在尝试连接后端路径是正确的。ERROR Provider ollama-qwen: Request failed: Error: connect ECONNREFUSED 127.0.0.1:11434这是经典的“连接被拒绝”说明后端进程虽然在但没有监听127.0.0.1:11434可能只监听了0.0.0.0:11434或::1:11434。解决方案是在 Ollama 的启动命令中加上-H 127.0.0.1:11434。ERROR Provider ollama-qwen: Request failed: Error: socket hang up这通常意味着后端服务接收到了请求但在处理过程中崩溃了。检查后端服务的日志很可能是模型加载失败或显存不足。4.4 第四层模拟请求验证 OpenAI 兼容性有时候502 并非来自网络层而是来自协议层。你的后端服务可能返回了一个 OpenClaw 无法解析的响应体。例如某些老版本的 Text Generation WebUI 会返回{error: ...}而 OpenClaw 期望的是标准的 OpenAI 格式{choices: [...]}。终极验证方法用curl直接向 OpenClaw 发送一个最简请求并用--include参数查看完整的 HTTP 响应头$payload { model ollama-qwen messages ({roleuser; contenttest}) } $payloadJson $payload | ConvertTo-Json -Depth 10 curl -X POST http://127.0.0.1:1572/v1/chat/completions -H Content-Type: application/json -H Authorization: Bearer dummy-token -Body $payloadJson --include观察输出的HTTP/1.1 502 Bad Gateway响应头之后是否跟着一个X-OpenClaw-Error头。如果有它的值就是 OpenClaw 内部捕获到的原始错误比如X-OpenClaw-Error: Failed to parse response from provider这直接指明了问题所在。提示Authorization: Bearer dummy-token这个头是必须的。OpenClaw 的默认配置开启了 token 鉴权即使你没在config.yaml中配置auth它也会检查这个头。热词中unauthorized: gateway token missing就是这个原因。最简单的解决办法是在config.yaml的server部分添加auth: false禁用鉴权。5. 实战接入让 VS Code Copilot 和 Dify 真正用上你的本地模型当 OpenClaw 成功返回{status:ok}并能处理curl请求后真正的价值才开始体现。下面是以两个最常用场景为例展示如何将 OpenClaw 无缝集成到你的日常开发流中。这不仅仅是“配置一个 URL”而是要理解每个工具的认证机制和协议细节避免那些“明明配置对了却没反应”的玄学问题。5.1 VS Code Copilot从“云端订阅”到“本地免费”的平滑切换VS Code 的 Copilot 插件v1.200原生支持自定义端点。但它的配置界面藏得很深而且对 URL 格式有严格要求。配置步骤在 VS Code 中按CtrlShiftP打开命令面板输入Preferences: Open Settings (JSON)回车。在打开的settings.json文件中添加以下配置{ github.copilot.advanced: { proxy: http://127.0.0.1:1572, useCustomEndpoint: true, customEndpoint: http://127.0.0.1:1572 } }关键点proxy和customEndpoint必须同时设置且值必须完全相同。proxy字段告诉 Copilot 的底层网络库走这个代理customEndpoint则告诉它的业务逻辑所有/v1/chat/completions请求都发到这里。重启 VS Code。验证与排错现象重启后Copilot 的状态栏图标变成灰色提示“Copilot is disabled”。原因Copilot 插件在启动时会向http://127.0.0.1:1572/v1/models发送一个预检请求以确认网关是否支持模型列表。而 OpenClaw 默认不实现这个 endpoint。修复在config.yaml的routes部分添加一条新路由routes: - path: /v1/models provider: ollama-qwen # 这个 provider 可以是任意一个因为 /v1/models 是只读的OpenClaw 会返回一个固定的模型列表 middleware: - models-list然后重启start.ps1。这个models-list中间件是 OpenClaw 内置的它会返回一个包含ollama-qwen的 JSON 数组。现象Copilot 能弹出建议但内容全是乱码或英文。原因你的后端模型如qwen2:7b是中文模型但 Copilot 的请求中messages的content字段被编码成了 UTF-8 的字节序列而某些版本的 OpenClaw 在转发时没有正确处理编码。修复升级 OpenClaw 到最新版git pull并在config.yaml中为providers添加encoding: utf8字段。5.2 Dify利用 OpenClaw 绕过“在线升级”限制实现纯离线部署Dify 的社区版v1.0支持自定义 LLM Provider但它的 UI 表单只接受Base URL和API Key。而 OpenClaw 本身不需要 API Key它需要的是一个“模型别名”。配置步骤登录 Dify Web UI进入Settings Model Providers。点击 Add Model Provider选择OpenAI类型。填写Provider Name:OpenClaw LocalBase URL:http://127.0.0.1:1572API Key:sk-1234567890任意字符串OpenClaw 会忽略它但 Dify 的表单要求必填点击Save然后在Model List中点击 Add Model。填写Model Name:ollama-qwen必须与config.yaml中providers.name完全一致Provider:OpenClaw LocalCredentials: 留空因为 API Key 已在 Provider 级别填过验证与排错现象在 Dify 的 Playground 中测试返回Gateway returned an error: your connection works, but the provider rejected a request。原因这是 Dify 的一个已知 Bug它在发送请求时会把model字段的值硬编码为gpt-3.5-turbo而不是你在Model Name中填写的ollama-qwen。OpenClaw 收到一个不认识的模型名自然会拒绝。修复这是一个前端层面的限制无法通过配置解决。你需要在 Dify 的后端代码中打一个