Windows 安装 OpenClaw

在 Windows 环境（特别针对无独立 GPU、Mini PC 等型号）下安装 OpenClaw 的详尽排障与部署指南，帮助开发者跨越 Node-gyp 编译及环境配置陷阱。

返回列表

概述

本指南专门针对在 Windows 系统（特别是类似 i3-N305 这类无独立 GPU 的 Mini PC 工作站）上部署 OpenClaw 时可能遇到的环境依赖与编译报错，提供了一条彻底的排障与最终正确安装的工作架构流。

环境前置条件预检

1. 基础系统要求

操作系统：Windows 10 / 11 64-bit。
处理器架构：x64 CPU（如 N100 / i3-N305 等低功耗或标压体系均完全兼容）。
物理内存：最低 8GB RAM（涉及大模型与本地向量库构建，强烈推荐 16GB 及以上，以确保网关数据流转稳定）。

2. 核心底层依赖准备（必装项）

由于 OpenClaw 底层涉及诸多基于 C++ 开发的原生二进制扩展组件（如 node-llama-cpp 等），您必须补齐 Windows 的底层编译连工具，否则必定报错：

Node.js 运行环境 (≥ 22.12.0)
- 前往 Node.js 官网下载安装包。
- 安装过程中务必勾选 “Add to PATH”（将其注入系统环境变量大表中）。
Microsoft Visual Studio Build Tools (核心编译工具链) 这是解决 node-gyp 以及 llama.cpp 在初始编译阶段直接崩溃退出的绝对核心。
- 前往官方依赖下载地址。
- 打开安装程序 (Installer) 后，必须强制勾选：
  - Desktop development with C++ (使用 C++ 的桌面开发配置)
  - 并在其右侧侧边栏详细扩展列表中确认已勾选 Windows SDK 组件（通常为默认选中，千万不能取消）。

3. 解除 PowerShell 本地脚本阻塞

系统的安全策略极易导致 npm.ps1 cannot be loaded 报错。请键盘敲击 Win + X 呼出隐藏菜单，以管理员身份运行终端 (PowerShell)，并推上安全补丁命令：

# 仅对当前用户放开本地脚本执行权限策略，提升执行顺畅度并防止 npm 相关脚本执行被拦截切断
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

全局安装 OpenClaw

1. 载入核心程序

继续维持在刚才放开权限的管理员 PowerShell 终端下，拉去云端分发的 OpenClaw 核心套件：

npm install -g openclaw@latest

提示：如果此时终端抛出红字 EBADENGINE Unsupported engine requires node >=22.12.0，这意味着您系统的 V8 引擎底层版本严重过旧。请将其卸载，干净重装 Node.js 最新 LTS 长期支持版后重启终端再试。

2. 校验文件树注入成功与否

openclaw --help

如果系统能够顺利吐出完整的 CLI 命令帮助列表输出日志，则代表 OpenClaw 的骨干依赖雏形已经成功植入主机。

终极常见阻断运行时 Debug 诊疗手册

以下是 Windows 生态下高频爆发的环境拦截错例及其终极溯源解决范式。

错误 1：npm.ps1 cannot be loaded

故障溯源：出于操作系统的安全围栏保护，PowerShell 拦截了非微软签名的自举加载执行文件。 修复方案：请严格执行前文前置准备阶段中的第 3 步命令，解除本机的最高层脚本运行禁制：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

错误 2：反复拉取 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++ 编译能力，因为系统根本找不到 cl.exe 链接器更不存在 CMake。 修复方案：没有捷径，请直接回退补做前置步骤第 2 项，下载并静待安装那几个 GB 大小的 Visual Studio Build Tools + C++ Workload 开发包链条。

错误 3：ENOENT: Could not read package.json

主要表现特征日志：

Could not read package.json:
C:\Users\Admin\AppData\Local\npm-cache\_npx\xxxx\package.json

故障溯源：极高的概率是因为 npm 在远端下载拉取高阶模块的阶段遭遇到了本地网络的丢包打断现象，进而导致其对应的缓存哈希文件发生了残破锁死不可恢复的情况。 修复方案：物理清毁遭受破坏的文件链缓存暂存区块：

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

错误 4：Vulkan 驱动兼容性警告

主要表现特征日志：

The prebuilt binary with Vulkan support is not compatible
falling back to building from source

故障溯源：鉴于部分微缩型计算节点本身缺少独立的物理级 GPU（显卡卡槽），自然也无法通过对应底层硬件呼出并使用针对 GPU 准备的配套 Vulkan 加速渲染指令集。 修复方案：OpenClaw 底层内建有良好的异常吞吐与退级方案，上述该流仅仅是告知性警告，它已确认底层成功 Fallback 降维到了无显卡条件下的纯粹 CPU 硬算计算模式，直接忽略即可。

错误 5：网关控制面板无法打开（127.0.0.1 refused 拒绝连接）

故障溯源：通常在开发者刚部署好时直接扑向浏览器敲打本地主地址。而这个时候 OpenClaw 这一个无头后置系统本质上它的心跳网管系统根本没有得到“拉起启动”的点火触发动作；或者是设定的 HTTP 监听基准端口被主机上的其他类似数据库等应用程序进行了静默强制霸占。 修复方案：请必须先在挂机的终端拉起网关主进程打好守护的地基：

openclaw gateway

此时再去使用浏览器工具访问它的数据出口端：http://localhost:18789

第一次的正确启动周期指引

这是一套符合健康运行原则的初次交互行为。在顺利安转无误的前提下，请强制自己按步骤且单列一条条地执行完，直到生命周期闭环呈现：

# 1. 向物理磁盘写盘基础配置文件，建立系统级用户态依赖树 (~/.openclaw)
openclaw setup

# 2. 开启自检引导对话机器人，配合它去逐步填充一些必要的通讯云连接点密文秘钥参数信息
openclaw onboard

# 3. 将整个网关底台拉伸推送到运行计算内存里面以维持进程存活工作状态
openclaw gateway

# 4. （在第 3 步开跑不打算挂掉它的同时，再新呼叫一个 terminal 小端触发仪表盘 UI 调用呈现到 Web 面版里。）
openclaw dashboard

随后只要设备不遭遇断电重启等外力，平时要介入使用机器做调度的时候仅仅只需触发 openclaw gateway 这个发条组件就足够让设备持续保持苏醒服从。

构建永不休眠的无人值守 AI 节点（极度关键）

Windows NT 内核默认配置的主机一旦进入睡眠（Sleep）或休眠（Hibernate），系统的核心物理总线表现形式如下：

系统处理器进入了深度挂起保护策略从而中止一切循环队列。
WebSocket / Socket 长连接链路管道在数秒内相继报废失联熄灭。
其底层的内部定时任务，外在接受通信响应监听均统统随之宕机瘫痪。

OpenClaw 没有也不应当具有直接去越俎代庖打破系统唤醒逻辑边界的“流氓能力”，这注定了如果它的计算母体陷入休眠停摆期，那么这台服务器将不再充当一台可通信节点的服务体！

Windows 电源供电系统改造指引

如果您试图把这台设备化身为 24Hx7 发光发热的计算中心：进入系统控制面板的「设置」-「系统」-「电源与睡眠」策略设定栏：

屏幕策略：您可以无忧地对显示器开启比如 3 到 5 分钟后强行关闭供货电源。显示器不会左右芯片层调度。
睡眠策略：请绝对不加变通地更改状态定义为 「从不 (Never)」。
按下**「其他电源设置」**继续打开高级详细页面，修改其“唤醒时间规划表”，直接将“硬盘进入低功耗待命”阶段这个属性强行写死更改为：0 分钟或者设置成了从不。

链路环境全面归档体检

一切调整改造就绪之后，让我们借用最后一个集成式诊断化验命令工具让中枢为您签发生命体征表报：

openclaw doctor

倘若您的系统能在随后不带一丝犹豫地倾泻打印出这列带着“纯正对钩”色彩的信息状态墙的话：

✔ Gateway running
✔ Workspace OK
✔ Browser OK

那么非常荣幸，代表着一台充满生命力的智能 AI 中继站点机器已经被您使用您的心血在这个世界上所构筑塑造激活完毕。