OpenClaw的Windows安装与Debug，算是给MiniPC i3-N305这类无GPU机型准备的一份完整操作指南。先说几个核心判断：OpenClaw核心用TypeScript编写，Node是官方推荐的运行时——Bun在Gateway网关（特别是WhatsApp/Telegram集成）上存在已知bug，尽量避开。配套应用方面，macOS菜单栏应用和iOS/Android移动节点已经就位，Windows和Linux原生应用正在路上，但Gateway网关本身在Windows上完全可用，推荐通过WSL2来跑。好了，直接进入正题。
一、前置条件
1. 系统要求
- Windows 10 / 11
- x64 CPU（i3-N305完全在射程内）
- 至少8GB RAM，16GB更稳当
2. 必须安装的依赖
OpenClaw本质上是基于Node.js的命令行工具，所以环境搭建是第一步：
Node.js ≥ 22.12.0，从nodejs.org下载，安装时记得勾选“Add to PATH”。
VS Build Tool（绕不过去的坎）——解决node-gyp和llama.cpp编译失败的核心手段。必须安装Microsoft Visual Studio Build Tools，加上Desktop C++ workload。下载地址是visualstudio.microsoft.com/visual-cpp-build-tools/，安装时勾选：
- Desktop development with C++
- Windows SDK（默认选项）
这一步如果跳过，后面编译llama.cpp时你会看到一大串红色报错，然后卡在原地。
3. PowerShell 允许执行脚本
解决经典的“npm.ps1 cannot be loaded”问题——以管理员身份打开PowerShell，执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
二、安装 OpenClaw（最终正确流程）
1. 全局安装（指向最新版本）
管理员PowerShell里直接敲：
npm install -g openclaw@latest
如果遇到：
EBADENGINE Unsupported engine requires node >=22.12.0
那就是Node版本太低，升级Node后再重试。
2. 验证安装
openclaw --help
如果看到完整的命令列表，说明安装成功。
三、常见错误与完整 Debug 过程（基于你的实际日志）
下面列出你遇到过的错误，加上对应的解决方式，整理成一份可以反复参考的Debug手册。
错误 1：npm.ps1 cannot be loaded
原因：PowerShell默认禁止脚本执行。
解决：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
错误 2：node-llama-cpp 反复 Clone llama.cpp / 编译失败
关键日志长这样：
Failed to download cmake Failed to build llama.cpp ERR! find VS Could not find Visual Studio installation You need “Desktop development with C++”
原因：机器缺少C++编译链，没法构建llama.cpp。
解决：安装VS Build Tools + C++ Workload，就是前置条件里那一步。
错误 3：ENOENT: Could not read package.json
比如：
Could not read package.json: C:Users..._npxxxxxpackage.json
原因：npm缓存损坏。
解决：清空缓存目录：
Remove-Item -Recurse -Force "$env:LOCALAPPDATAnpm-cache_npx"
错误 4：Vulkan 支持失败
The prebuilt binary with Vulkan support is not compatible falling back to building from source
你的Mini PC没有独立GPU，Vulkan支持自然失败——这其实是正常警告，可以忽略。OpenClaw会自动回退到CPU模式。
错误 5：Gateway 无法访问（127.0.0.1 refused）
原因通常有两类：Gateway没启动，或者端口未开放/被占用。
正确启动方式：
openclaw gateway
然后访问 https://127.0.0.1:18789 或 https://localhost:18789（端口可能随配置不同）。如果启用了dev模式，端口会变成19001：
openclaw --dev gateway
四、安装完成后如何启动 Dashboard
全流程依次执行：
openclaw setup openclaw onboard openclaw gateway openclaw dashboard
各命令的作用：
- setup：初始化 ~/.openclaw 目录
- onboard：引导配置
- gateway：启动核心服务
- dashboard：打开控制面板
首次使用必须按顺序跑一遍。之后日常使用只需启动：
openclaw gateway
浏览器访问 https://localhost:18789 即可。
五、休眠 / 睡眠的影响（关键）
Windows一旦进入sleep或hibernate，CPU停止、内存冻结，所有OpenClaw服务都会暂停——OpenClaw无法在睡眠中运行。解决方案：
- 禁用睡眠（推荐）
- 或者把OpenClaw装在Always-ON的设备上（NAS、小主机等）
六、推荐的 Windows 永不休眠设置
适合当作AI自动化节点来用：
设置 → 系统 → 电源与睡眠 → 睡眠 = 从不 设置 → 屏幕 = 可关闭 高级电源设置 → 睡眠之后 = 从不
七、最终验证
打开PowerShell，执行：
openclaw doctor
如果看到类似这样的输出：
✔ Gateway running ✔ Workspace OK ✔ Browser OK
那就意味着系统完全正常，可以放手干活了。
最终总结
你成功解决了五个核心问题：
- PowerShell 执行权限不足 → 开启 RemoteSigned
- Node 版本过低 → 升级 Node >= 22.12
- 缺少 C++ 编译链 → 安装 VS Build Tools（最关键的一步）
- npm 缓存损坏 → 清理 _npx 缓存
- Gateway 未启动 → Dashboard 无法连接 → 手动启动
openclaw gateway
现在，你这台 i3-N305 Mini PC 已经可以作为一个本地AI自动化服务器（OpenClaw Agent Node）来用了。随时可以通过：
openclaw gateway
启动服务，然后开始你的AI自动化之旅。
