当前位置：首页 > news >正文

OpenClaw 2.6.6 Windows 安装与深度配置指南

news 2026/7/17 20:39:26

1. 项目概述：这不是又一个“点下一步”的安装教程

OpenClaw 2.6.6 这个版本在 Windows 平台上的安装，远不止是双击一个 exe 文件那么简单。它本质上是一套面向开发者与技术型用户的本地化智能体运行时环境，核心定位是让大模型能力能像调用本地命令一样被集成进日常工作流——比如用openclaw ask "帮我总结这份周报"直接调用 Claude 或本地 Llama 模型，或者用openclaw skill run web-scraper --url https://example.com启动一个预置的网页抓取技能。我从去年开始在三台不同配置的 Windows 设备（一台 i5-8250U 笔记本、一台 Ryzen 7 5800H 台式机、一台 Surface Pro 9）上反复部署 OpenClaw，从 2.4.x 到现在的 2.6.6，踩过所有你能想到的坑：PATH 环境变量错位导致命令无法识别、WSL2 与原生 Windows 混用引发的端口冲突、Node.js 版本不兼容触发的 sharp 构建失败、甚至因为系统语言设置为简体中文但区域格式设为美国，导致某些 JSON 配置文件解析出错。这些都不是文档里轻描淡写的“请确保 Node 已安装”就能绕过去的。这篇指南，就是把那些藏在 GitHub Wiki 背后、Discord 频道里零散讨论、以及我自己在 PowerShell 控制台里敲了上百次命令才摸清的实操逻辑，全部摊开来讲清楚。它不教你怎么“复制粘贴”，而是告诉你每一步背后为什么必须这样操作，哪个参数改了会崩，哪个路径漏了就永远找不到openclaw命令。如果你刚在百度搜到“openclaw : 无法将‘openclaw’项识别为 cmdlet”，或者正对着openclaw gateway status返回一堆红色错误发呆，那你来对地方了——这是一份写给真实 Windows 用户的生存手册，不是给搜索引擎看的 SEO 套餐。

2. 安装方案深度拆解：为什么官方推荐脚本，而你可能得手动绕开它

2.1 官方一键脚本的底层逻辑与隐藏前提

OpenClaw 官方提供的 PowerShell 安装脚本iwr -useb https://openclaw.ai/install.ps1 | iex，表面看是“三秒安装”，但它背后其实是一套精密的依赖链自动编排系统。这个脚本不是简单下载一个二进制包，而是要完成四个关键动作：检测当前 Windows 版本与架构（x64/ARM64）、判断 Node.js 是否已安装及版本是否 ≥22.16、若缺失则静默下载并安装 Node.js 24 LTS、最后才执行npm install -g openclaw@2.6.6并注册为系统服务。它的设计哲学非常明确：牺牲可控性，换取首次上手的流畅度。这在干净的、全新安装的 Windows 10/11 系统上确实高效，我实测在一台刚重装系统的 ThinkPad X1 Carbon 上，从打开 PowerShell 到openclaw --version正常返回，耗时 2 分 17 秒。但问题恰恰出在“干净”二字上——现实中的 Windows 电脑，90% 以上都早已装有 Python、Java、Git、VS Code、Docker Desktop 等一堆开发工具，它们各自修改了 PATH、注册了环境变量、甚至劫持了某些全局命令（比如git命令可能来自 Git for Windows，也可能来自 WSL2 的 Ubuntu）。当官方脚本试图往C:\Users\{user}\AppData\Roaming\npm下安装全局 CLI 时，它根本不会去检查这个路径是否已被其他工具写入过权限异常的符号链接，也不会判断你的 PowerShell 执行策略（ExecutionPolicy）是否被公司组策略锁死为AllSigned。这就是为什么大量用户反馈“脚本执行一半就报错”，错误信息五花八门：The term 'node' is not recognized、Access is denied、Cannot bind argument to parameter 'Path' because it is null。这些报错不是脚本的 Bug，而是它主动选择忽略的复杂性。

2.2 三种替代路径的适用场景与风险评估

当你发现一键脚本失败，别急着卸载重来，先根据你的实际环境选择最匹配的替代方案。我把它分成三类，按推荐顺序排列：

第一类：npm 全局安装（最推荐给已有 Node 生态的用户）
如果你电脑上已经装有 Node.js（哪怕只是 18.x），并且npm -v和node -v都能正常返回，那么直接走npm install -g openclaw@2.6.6是最稳妥的。它的优势在于完全复用你现有的 Node 环境，不会引入第二个 Node 运行时，避免了多版本共存带来的混乱。但这里有个致命细节：npm 的全局安装路径默认是C:\Users\{user}\AppData\Roaming\npm，而这个路径必须被加入系统的PATH环境变量，否则终端永远找不到openclaw命令。很多人卡在这一步，以为安装失败，其实是 PATH 没配。验证方法很简单：在 PowerShell 里执行$env:PATH -split ';' | Select-String "AppData"，如果没输出，说明路径没加进去。手动添加的命令是[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")，执行完后必须重启 PowerShell 才生效。这是整个安装过程中最常被忽略、却最影响后续所有操作的基础环节。

第二类：pnpm 全局安装（适合追求极致性能与磁盘空间的用户）
pnpm 是 npm 的超集，它用硬链接和符号链接的方式管理 node_modules，能节省高达 80% 的磁盘空间，并且安装速度比 npm 快 2-3 倍。对于 OpenClaw 这种依赖树深、包数量大的 CLI 工具，pnpm 的优势非常明显。安装命令是pnpm add -g openclaw@2.6.6，但注意它有一个 npm 没有的强制步骤：首次安装后必须运行pnpm approve-builds -g。这是因为 OpenClaw 的某些依赖（如sharp图像处理库）包含需要编译的原生模块，pnpm 默认禁止自动构建，必须显式授权。跳过这一步，后续openclaw doctor就会报sharp not found错误，导致所有涉及图片处理的技能（比如截图分析、PDF 转文字）全部失效。我测试过，在一台 512GB SSD 的笔记本上，用 npm 安装 OpenClaw 占用 1.2GB 空间，而 pnpm 仅占 380MB，且首次启动快 1.8 秒。代价是学习成本略高，你需要额外记住这个approve-builds命令。

第三类：源码编译安装（仅限开发者与深度定制需求者）
如果你打算贡献代码、调试某个特定技能、或者需要修改 OpenClaw 的默认网关端口（比如公司防火墙封了 3000 端口），那么从 GitHub 源码安装是唯一选择。流程是git clone https://github.com/openclaw/openclaw.git→cd openclaw→pnpm install && pnpm build && pnpm ui:build→pnpm link --global。这里的关键陷阱在于pnpm link --global命令。它不是把代码复制到全局目录，而是创建一个指向你本地仓库的符号链接。这意味着只要你没删掉那个openclaw文件夹，openclaw命令就永远指向你正在编辑的代码。好处是改一行代码就能立刻看到效果；坏处是如果你不小心git pull了不稳定分支，整个 CLI 就可能崩溃。我建议普通用户永远不要碰这个方案，除非你清楚自己在做什么。一个真实的教训：有位用户在pnpm link后，又运行了npm install -g openclaw，结果两个全局命令冲突，openclaw --version有时返回 2.6.6，有时返回 2.5.0，排查了三天才发现是符号链接和 npm 包共存导致的 PATH 优先级混乱。

2.3 WSL2 与原生 Windows：一个被严重低估的决策点

OpenClaw 官方文档里那句“WSL2 更稳定”，绝不是客套话，而是基于 Linux 内核与 Windows NT 内核本质差异得出的工程结论。在原生 Windows 上，OpenClaw 的 Gateway（网关服务）需要监听 HTTP 端口、管理进程、读写临时文件，这些操作在 Windows 的 ACL（访问控制列表）机制下异常脆弱。比如，当 Gateway 尝试在C:\Users\{user}\AppData\Local\Temp下创建一个 socket 文件时，Windows Defender 可能会因“可疑行为”将其拦截；当它尝试 fork 一个子进程运行 Python 技能时，Windows 的作业对象（Job Object）限制可能导致子进程被意外终止。而在 WSL2 中，这一切都运行在标准的 Linux 用户空间里，内核调度、文件系统、网络栈都是经过数十年锤炼的成熟方案。我做过对比测试：同一台机器，原生 Windows 下连续运行 OpenClaw 72 小时后，Gateway 有 37% 的概率出现EADDRINUSE（端口被占用）错误，必须手动taskkill /f /im node.exe；而 WSL2 下 168 小时无故障。但 WSL2 不是银弹，它要求你的 Windows 版本 ≥22H2，且 BIOS 中必须开启虚拟化（VT-x/AMD-V），很多企业电脑的 BIOS 是被 IT 部门锁死的。所以我的建议很务实：如果你的电脑是个人使用、能自由控制 BIOS，优先装 WSL2；如果是公司配发的笔记本，且 IT 政策严格，那就老老实实啃原生 Windows 的坑，重点加固 PATH 和权限配置。

3. 核心配置详解：从环境变量到网关端口，每一个参数都关乎成败

3.1 环境变量：PATH 是命门，NODE_OPTIONS 是暗线

在 Windows 上，PATH环境变量不是可选项，而是 OpenClaw 能否存活的生命线。它的作用机制非常朴素：当你在 PowerShell 里输入openclaw，系统会依次检查PATH中列出的每一个目录，看里面有没有叫openclaw.cmd或openclaw.ps1的可执行文件。一旦找到，就立即执行。问题在于，npm/pnpm 的全局 bin 目录（C:\Users\{user}\AppData\Roaming\npm）永远不会被 Windows 自动加入PATH，这是微软刻意为之的安全设计。所以，99% 的“命令未识别”错误，根源都在这里。修复方法有两种，我强烈推荐第二种：

方法一（临时）：在当前 PowerShell 会话中追加
$env:PATH += ";C:\Users\$env:USERNAME\AppData\Roaming\npm"
这个命令只对当前窗口有效，关掉就失效，适合快速验证安装是否成功。
方法二（永久）：写入用户环境变量
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")
这个命令会把路径永久写入当前用户的环境变量注册表项HKEY_CURRENT_USER\Environment\PATH，重启 PowerShell 后依然有效。注意，它只影响当前用户，不影响系统级服务，这对安全性反而是加分项。

但光有 PATH 还不够。OpenClaw 2.6.6 引入了一个关键的底层依赖：sharp库，它负责所有图像处理（截图、OCR、图表生成）。sharp在 Windows 上编译时，会尝试链接系统级的libvips图像处理库。如果用户之前装过 ImageMagick 或其他图像工具，它们可能已向系统注入了旧版libvips.dll，导致sharp加载失败，报错Error: The specified module could not be found。官方给出的解决方案是设置环境变量SHARP_IGNORE_GLOBAL_LIBVIPS=1，强制sharp使用自带的静态链接版本。这个变量必须在openclaw命令执行前就存在。最可靠的做法，是在用户环境变量里新增一个名为SHARP_IGNORE_GLOBAL_LIBVIPS的变量，值设为1。这样，无论你用 PowerShell、CMD 还是 VS Code 的终端启动 OpenClaw，它都会生效。我见过太多用户在 PowerShell 里set SHARP_IGNORE_GLOBAL_LIBVIPS=1，然后换到 CMD 里运行openclaw，结果还是报错——因为环境变量是进程级的，不是系统级的。

3.2 网关（Gateway）配置：端口、日志、HTTPS 的三角平衡

OpenClaw 的 Gateway 是整个系统的大脑，它提供一个本地 Web 服务（默认http://localhost:3000），所有技能、模型调用、UI 界面都通过它中转。它的配置文件是~/.openclaw/config.json，但官方文档没告诉你的是，这个文件不是安装时自动生成的，而是在你第一次运行openclaw onboard（新手引导）时才创建。这意味着，如果你跳过引导直接openclaw gateway start，它会用一套硬编码的默认值启动，其中就包括那个著名的 3000 端口。在企业网络里，3000 端口经常被监控软件或代理服务器占用，导致openclaw gateway status显示inactive。解决方法是修改配置文件，在config.json的gateway对象里添加"port": 3001（或其他空闲端口）。但这里有个连官方都没强调的细节：端口修改后，必须同时修改openclawCLI 的默认网关地址。因为 CLI 内部硬编码了http://localhost:3000来跟 Gateway 通信。所以，你不仅要改配置文件，还要在 PowerShell 里执行：
[Environment]::SetEnvironmentVariable("OPENCLAW_GATEWAY_URL", "http://localhost:3001", "User")
否则，CLI 命令（如openclaw ask）会一直向 3000 端口发请求，而 Gateway 在 3001 端口监听，结果就是超时。

另一个常被忽视的配置是日志级别。默认情况下，Gateway 只记录error和warn级别的日志，这对于排查问题远远不够。你可以在config.json里添加"logLevel": "debug"，然后重启 Gateway。日志文件默认存放在~/.openclaw/logs/gateway.log，里面会详细记录每一次 HTTP 请求、模型响应时间、技能执行堆栈。我曾靠这个日志定位到一个诡异问题：某次openclaw skill run pdf-extract失败，日志显示timeout after 30000ms，但技能代码里明明设置了 60 秒超时。最终发现是 Windows 防火墙的“出站连接”规则，对 Node.js 进程做了 30 秒连接限制。没有 debug 日志，这个问题根本无从下手。

至于 HTTPS，OpenClaw 2.6.6 默认不启用，因为它需要你提供合法的 SSL 证书。但如果你打算让 OpenClaw 的 UI 界面通过公司内网域名（如https://ai-tools.internal）访问，就必须配置。方法是在config.json的gateway下添加：

"ssl": { "key": "/path/to/your/key.pem", "cert": "/path/to/your/cert.pem" }

注意，这里的路径必须是 WSL2 的 Linux 路径（如/home/user/certs/key.pem），而不是 Windows 的C:\certs\key.pem，因为 Gateway 进程在 WSL2 环境下运行。这是一个典型的跨系统路径陷阱，新手极易填错。

3.3 多国语言与区域设置：中文 Windows 的隐藏雷区

OpenClaw 2.6.6 官方支持 20+ 种语言，包括简体中文，但它的语言切换逻辑不是简单的“读取系统语言”，而是依赖于 Node.js 的IntlAPI 和操作系统的区域格式（Region Format）。这就导致一个常见现象：你的 Windows 显示语言是中文，但区域格式设为“英语（美国）”，结果 OpenClaw 的 UI 界面全是英文，而openclaw doctor的错误提示却是中文，造成一种诡异的混搭感。根本原因在于，Intl.DateTimeFormat()这类 API 在 Windows 上会读取“区域格式”设置，而不是“显示语言”。修复方法很简单：进入 Windows 设置 → 时间和语言 → 语言和区域 → 区域 → 将“区域格式”改为“中文（简体，中国）”。改完后，重启 Gateway，UI 界面就会变成纯正的简体中文。

更深层的问题是编码。OpenClaw 的配置文件、技能脚本、日志文件，全部默认使用 UTF-8 编码。但 Windows 记事本（Notepad）在保存.json文件时，默认用的是ANSI（即 GBK）编码。如果你用记事本编辑config.json，然后保存，文件里所有的中文字符都会变成乱码，导致openclaw doctor报SyntaxError: Unexpected token in JSON at position 100。这个错误极其隐蔽，因为文件在记事本里看起来完全正常。唯一的解决办法，是永远不用记事本编辑任何 OpenClaw 相关的文本文件。我强制自己只用 VS Code 或 Notepad++，并在保存时明确选择“UTF-8 with BOM”（带签名的 UTF-8）。VS Code 的设置里有一行关键配置："files.encoding": "utf8"，必须确保它是开启的。这是一个用血泪换来的经验：在一台新电脑上，我花了 4 小时排查一个看似随机的 JSON 解析错误，最后发现罪魁祸首就是记事本。

4. 实操全流程：从零开始，手把手带你跑通第一个`openclaw ask`

4.1 前置准备：清理、检测、备份三步法

在动手安装前，我坚持执行一个铁律：绝不直接在现有环境中覆盖安装。尤其是当你之前装过旧版本（2.4.x 或 2.5.x），残留的配置文件、全局包、环境变量，会成为新版本的定时炸弹。我的标准清理流程如下：

第一步：卸载所有旧版 OpenClaw
以管理员身份打开 PowerShell，执行：

npm uninstall -g openclaw pnpm remove -g openclaw # 如果用过源码安装，删除全局链接 pnpm unlink openclaw

然后，手动删除以下目录（它们是 OpenClaw 的数据根目录，不会被 npm/pnpm 自动清理）：

C:\Users\{user}\.openclaw（主配置与数据）
C:\Users\{user}\AppData\Roaming\openclaw（旧版配置，2.5.x 之前使用）
C:\Users\{user}\AppData\Local\openclaw（缓存与临时文件）

提示：删除前，建议先压缩备份C:\Users\{user}\.openclaw\config.json，以防里面有你自定义的重要 API Key。

第二步：全面检测系统状态
运行以下命令，逐项确认基础环境：

# 检查 PowerShell 执行策略（必须是 RemoteSigned 或 Unrestricted） Get-ExecutionPolicy -List # 检查 Node.js 版本（必须 ≥22.16） node -v # 检查 npm 全局路径（确认是否在 AppData 下） npm prefix -g # 检查 PATH 中是否已包含 npm 全局 bin $env:PATH -split ';' | Select-String "AppData.*npm" # 检查 3000 端口是否被占用（Windows 默认端口） netstat -ano | findstr :3000

如果Get-ExecutionPolicy返回AllSigned，说明公司组策略锁死了脚本执行，你必须联系 IT 部门，或者改用 CMD + npm 方式安装（CMD 的执行策略是独立的）。

第三步：创建纯净的安装沙盒
新建一个专用的 PowerShell 配置文件，避免污染你的主环境。在C:\Users\{user}\Documents\PowerShell\Microsoft.PowerShell_profile.ps1里，添加以下内容：

# 为 OpenClaw 创建专属 PATH $openclawPath = "$env:USERPROFILE\AppData\Roaming\npm" if ($env:PATH -notlike "*$openclawPath*") { $env:PATH += ";$openclawPath" } # 强制设置关键环境变量 $env:SHARP_IGNORE_GLOBAL_LIBVIPS = "1" $env:OPENCLAW_GATEWAY_URL = "http://localhost:3000"

这样，每次你打开新的 PowerShell，它都会自动加载这套干净的配置，与你原有的开发环境完全隔离。

4.2 安装与初始化：执行、验证、微调三阶段

现在，进入真正的安装环节。我以npm 全局安装为例，全程记录每一步的预期输出与可能的异常：

阶段一：执行安装
在已加载上述配置文件的 PowerShell 中，运行：

npm install -g openclaw@2.6.6

正常情况下，你会看到滚动的日志，最后以+ openclaw@2.6.6结尾。如果卡在sharp的gyp编译步骤，大概率是libvips冲突，此时立即中断（Ctrl+C），然后运行：

$env:SHARP_IGNORE_GLOBAL_LIBVIPS="1" npm install -g openclaw@2.6.6

这次应该能顺利通过。

阶段二：基础验证
安装完成后，立刻验证三个核心能力：

# 1. CLI 是否可用 openclaw --version # 应返回 "openclaw/2.6.6 win32-x64 node-v22.16.0" # 2. 健康检查 openclaw doctor # 应返回 "✅ All checks passed" # 3. 网关状态（此时应为 inactive，因为我们还没启动） openclaw gateway status # 应返回 "Gateway is not running"

如果openclaw --version报错，回到 3.1 节，重新检查 PATH；如果openclaw doctor报sharp not found，说明SHARP_IGNORE_GLOBAL_LIBVIPS没生效，检查环境变量设置。

阶段三：启动与微调
运行新手引导，它会帮你生成初始配置并启动 Gateway：

openclaw onboard --install-daemon

这个命令会做三件事：创建~/.openclaw/config.json、启动 Gateway 作为后台服务、注册开机自启（通过 Windows 计划任务）。等待约 10 秒，再次运行：

openclaw gateway status

如果返回active (running)，恭喜，基础安装成功！此时，打开浏览器访问http://localhost:3000，你应该能看到 OpenClaw 的 Web UI 界面。

注意：--install-daemon参数是关键。如果不加它，Gateway 只会在当前 PowerShell 窗口里运行，关掉窗口服务就停了。加上它，OpenClaw 会创建一个 Windows 计划任务，名称为OpenClaw Gateway，触发器是“用户登录时”，操作是启动C:\Users\{user}\AppData\Roaming\npm\openclaw.cmd。你可以通过taskschd.msc（任务计划程序）查看和管理它。

4.3 运行第一个命令：`openclaw ask`的完整链路解析

现在，让我们真正用起来。在 PowerShell 里输入：

openclaw ask "你好，今天天气怎么样？"

这条命令的执行链路，远比看上去复杂，它完整展现了 OpenClaw 的架构设计：

CLI 层：openclaw ask命令首先被解析，CLI 读取~/.openclaw/config.json，确认当前默认模型（通常是claude-3-haiku或llama-3-8b）。
网关层：CLI 将请求 POST 到http://localhost:3000/api/v1/chat/completions，Gateway 接收后，进行鉴权（检查 API Key）、速率限制、日志记录。
模型层：Gateway 根据配置，将请求转发给对应的模型提供商（如 Anthropic 的 API，或本地 Ollama 的http://localhost:11434/api/chat）。
响应层：模型返回的流式响应（streaming response），被 Gateway 截获、组装成标准 OpenAI 格式，再返回给 CLI。
渲染层：CLI 接收到 JSON 响应后，提取choices[0].message.content字段，并以彩色文本形式打印在终端上。

如果这一步失败，错误通常出现在第 2 或第 3 步。openclaw doctor会告诉你 Gateway 是否健康，但不会告诉你模型 API Key 是否正确。这时，你需要手动测试模型连接：

# 测试 Gateway 是否能连通模型（以 Ollama 为例） curl -X POST "http://localhost:3000/api/v1/chat/completions" ` -H "Content-Type: application/json" ` -d '{ "model": "llama3", "messages": [{"role":"user","content":"hi"}] }'

如果返回{"error":"Model not found"}，说明模型没注册；如果返回{"error":"Unauthorized"}，说明 API Key 错了。这个 curl 命令，是我排查所有openclaw ask失败问题的终极武器。

5. 常见问题与独家排查技巧：那些文档里不会写的真相

5.1 “无法将‘openclaw’项识别为 cmdlet” 的七种死因与解法

这个错误是 Windows 用户的头号噩梦，它看似单一，实则背后有七种完全不同的技术成因。我按发生频率排序，并给出精准诊断命令：

排查顺序	根本原因	诊断命令	解决方案
1	`PATH`未包含 npm 全局 bin 目录	`$env:PATH -split ';' \| Select-String "AppData.*npm"`	运行`[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Users\$env:USERNAME\AppData\Roaming\npm", "User")`
2	PowerShell 执行策略阻止脚本	`Get-ExecutionPolicy -List`	运行`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
3	`openclaw.cmd`文件权限被拒绝	`icacls "$env:USERPROFILE\AppData\Roaming\npm\openclaw.cmd"`	右键该文件 → 属性 → 安全 → 编辑 → 给当前用户“完全控制”权限
4	Node.js 版本低于 22.16	`node -v`	卸载旧版，从 https://nodejs.org/ 下载 22.16.0 LTS 安装
5	`openclaw.cmd`文件被杀毒软件误删	`dir "$env:USERPROFILE\AppData\Roaming\npm\openclaw.*"`	临时禁用杀软，重新`npm install -g openclaw`
6	系统用户名含空格或特殊字符（如`C:\Users\John Doe`）	`echo $env:USERPROFILE`	这是 npm 的已知 Bug，改用`pnpm add -g openclaw`可绕过
7	Windows 的“开发者模式”未开启（影响某些原生模块）	`Get-WindowsOptionalFeature -Online -FeatureName "DeveloperMode"`	运行`Enable-WindowsOptionalFeature -Online -FeatureName "DeveloperMode" -NoRestart`

实操心得：我写了一个一键诊断脚本oc-diagnose.ps1，内容就是上面七条命令的组合。每次遇到这个错误，我只需双击运行它，几秒钟就能定位到具体是哪一条。脚本最后会用Write-Host以不同颜色标出问题项，绿色表示正常，红色表示异常。这个小工具，帮我节省了数百小时的重复排查时间。

5.2 Gateway 启动失败的三大幻影错误

openclaw gateway status显示inactive，但openclaw doctor却说✅ All checks passed，这种矛盾让人抓狂。以下是三个最狡猾的“幻影错误”：

幻影一：“端口被占用”但netstat查不到
Windows 的netstat有时会漏掉由node.exe创建的SOCK_STREAM类型连接。真正的杀手是TCPView（Sysinternals 工具）。下载tcpview.exe，以管理员身份运行，按Port列排序，查找3000端口。你会发现，一个名为conhost.exe（控制台宿主）的进程正霸占着它。这是因为之前一次异常退出的 Gateway，其子进程node.exe没有被彻底杀死，conhost.exe作为它的控制台窗口，还持有端口句柄。解决方案：在 TCPView 中右键该进程 →End Process Tree，然后重启 Gateway。

幻影二：“证书错误”导致 HTTPS 重定向失败
如果你在config.json中启用了 HTTPS，但证书不被系统信任，Gateway 启动时不会报错，而是静默降级为 HTTP。但 CLI 仍会尝试用https://协议连接，结果就是超时。验证方法：在浏览器中直接访问https://localhost:3000，如果出现“您的连接不是私密连接”警告，点击“高级”→“继续前往 localhost（不安全）”，如果能打开 UI，说明就是证书问题。解决方案：要么用mkcert工具生成本地可信证书，要么干脆关闭 HTTPS，专注在 HTTP 上调试。

幻影三：“模型未加载”但doctor不报错
openclaw doctor只检查 Gateway 进程是否存在，不检查它内部的模型注册状态。所以，即使 Gateway 运行着，openclaw ask也可能返回{"error":"Model not found"}。诊断命令是：

curl "http://localhost:3000/api/v1/models"

正常应返回一个 JSON 数组，列出所有已加载的模型。如果返回空数组[]，说明模型配置有误。检查~/.openclaw/config.json中的models数组，确认id、name、endpoint字段拼写完全正确，特别是endpoint的 URL 末尾不能有多余的/，http://localhost:11434/api/chat/是错的，http://localhost:11434/api/chat才是对的。

5.3 技能（Skill）执行失败的现场还原法

当你运行openclaw skill run web-scraper --url https://example.com失败时，错误信息往往非常笼统，比如Skill execution failed。这时，你需要进入“现场还原”模式：

找到技能的物理位置：所有预置技能都存放在C:\Users\{user}\AppData\Roaming\npm\node_modules\openclaw\dist\skills\下，每个技能是一个独立的文件夹。web-scraper就在web-scraper\文件夹里。
查看技能的入口脚本：打开web-scraper\index.js，找到export async function execute(...)函数。这就是技能的主逻辑。
手动执行技能代码：在 PowerShell 中，进入web-scraper文件夹，然后运行：
```
node -e "require('.').execute({url: 'https://example.com'})"
```
这样，Node.js 会直接执行技能代码，并把原始的 JavaScript 错误堆栈（包括行号）打印出来，而不是被 OpenClaw 的封装层吃掉。我曾用这个方法，发现一个技能的axios库版本太老，不支持 HTTP/2，而目标网站强制要求 HTTP/2，结果就是ERR_HTTP2_INADEQUATE_TRANSPORT_SECURITY。升级axios后，问题迎刃而解。

最后一个小技巧：OpenClaw 的日志文件~/.openclaw/logs/gateway.log默认是滚动的，只保留最近 10MB。如果你需要长期追踪某个技能的执行，可以修改config.json，添加"logFileMaxSize": "100mb"和"logFileMaxCount": 5，这样就能保留 5 个 100MB 的日志文件，方便回溯。