原生 Windows 安装 OpenClaw 完整指南 - 不装 WSL2 的替代方案¶

大家好！昨天我们发布了 WSL2 安装指南，收到了很多反馈。有朋友问："能不能在原生 Windows 上安装 OpenClaw？不想用 WSL2。"

答案是：可以，但有门槛。

今天这篇指南，我会详细演示如何在原生 Windows 上安装 OpenClaw，包括所有可能遇到的坑和解决方案。这是经过 30+ 次安装测试总结出的完整流程。

⚠️ 重要声明：官方态度 vs 实际可行性¶

官方文档立场： - OpenClaw 官方推荐使用 WSL2 - 原生 Windows 安装未正式文档化 - 社区反馈原生安装成功率约 60-70%

实际情况： - 原生 Windows 可以运行 OpenClaw - 需要完整的 C++ 编译环境 - 适合有 Windows 开发经验的用户 - 某些功能（如 WhatsApp 通道）可能有兼容性问题

本指南适用人群： - ✅ 有 Windows 开发经验，熟悉 PowerShell - ✅ 需要直接访问 Windows 文件系统 - ✅ 不想使用 WSL2 虚拟化 - ✅ 愿意花时间排查潜在问题

不建议使用原生安装的情况： - ❌ Windows 新手 - ❌ 需要 WhatsApp/Telegram 通道（WSL2 更稳定） - ❌ 追求最简单安装体验 - ❌ 生产环境部署

系统要求¶

组件	最低要求	推荐配置
操作系统	Windows 10 1903+	Windows 11 22H2+
Node.js	22.0.0+	22.x LTS 最新版
内存	4GB	8GB+
磁盘空间	5GB	10GB+
权限	管理员权限	管理员权限
网络	稳定互联网	能访问 GitHub/npm

完整安装流程¶

第一阶段：准备工作（关键！）¶

原生 Windows 安装失败的主要原因：依赖不完整。请严格按照顺序安装。

1.1 安装 Node.js 22+¶

步骤：

访问 Node.js 官网
下载 LTS 版本（22.x 或更高）
运行安装程序，选择默认选项
安装完成后，重启 PowerShell

验证：

node --version
npm --version

预期输出：

v22.x.x
10.x.x

⚠️ 常见错误： - 如果版本低于 22，请卸载后重新安装 - 如果命令不存在，检查 PATH 环境变量

1.2 安装 Git¶

OpenClaw 安装过程需要 Git 拉取依赖。

使用 winget 安装（推荐）：

winget install Git.Git

或者下载安装： 1. 访问 Git for Windows 2. 下载并运行安装程序 3. 选择默认选项即可

验证：

git --version

预期输出：

git version 2.x.x.windows.1

1.3 安装 CMake¶

node-llama-cpp 依赖需要 CMake。

使用 winget 安装：

winget install Kitware.CMake

验证：

cmake --version

预期输出：

cmake version 3.x.x

1.4 安装 Python（node-gyp 依赖）¶

某些 npm 包需要 Python 进行编译。

使用 winget 安装：

winget install Python.Python.3.11

⚠️ 重要： 安装时勾选 "Add Python to PATH"

验证：

python --version

1.5 安装 Visual Studio Build Tools（最关键！）¶

这是原生 Windows 安装最容易失败的环节。node-gyp 需要完整的 C++ 编译工具链。

方法一：使用 winget（推荐）

winget install Microsoft.VisualStudio.2022.BuildTools

方法二：手动下载 1. 访问 Visual Studio Build Tools 2. 下载并运行安装程序

安装后必须配置的组件：

打开 Visual Studio Installer → 选择 Modify → 勾选：

✅ Desktop development with C++（桌面 C++ 开发）
✅ MSVC v143 - VS 2022 C++ build tools
✅ Windows 10/11 SDK
✅ C++ CMake tools for Windows

验证：

# 检查 MSVC 编译器
cl

# 应该输出编译器版本信息

⚠️ 如果没有安装完整： 安装 OpenClaw 时会报错：

error MSB8020: The build tools for v143 cannot be found.
error: Failed to compile llama.cpp

第二阶段：安装 OpenClaw¶

2.1 清理旧安装（如果有）¶

# 卸载旧版本
npm uninstall -g openclaw

# 清理 npm 缓存
npm cache clean --force

# 删除配置目录（可选，会丢失配置）
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw -ErrorAction SilentlyContinue

2.2 安装 OpenClaw CLI¶

使用管理员权限打开 PowerShell，运行：

npm install -g openclaw@latest

安装过程可能持续 5-15 分钟，因为需要编译原生模块。

⚠️ PowerShell 注意事项：

PowerShell 不支持 && 语法，如果要执行多个命令，使用 ;：

# ❌ 错误（bash 语法）
npm cache clean --force && npm install -g openclaw

# ✅ 正确（PowerShell 语法）
npm cache clean --force; npm install -g openclaw

2.3 验证安装¶

openclaw --version
openclaw --help

预期输出：

openclaw/2026.x.x windows-x64 node-v22.x.x

第三阶段：初始化配置¶

3.1 运行配置向导¶

openclaw onboard --install-daemon

配置步骤：

选择网关类型： Local（本地）或 Remote（远程）
选择 AI 模型： Anthropic/OpenAI/Google 等
输入 API Key： 提前准备好
选择通信渠道： Web UI/Telegram/Discord 等
安装守护进程： 选择 Yes 实现开机自启

3.2 配置 Windows 开机自启¶

OpenClaw 的 daemon 在 Windows 上需要使用 任务计划程序。

手动创建任务计划：

打开 任务计划程序（Task Scheduler）
创建 基本任务
名称：OpenClaw Gateway
触发器：登录时
操作：启动程序

程序/脚本：

C:\Users\你的用户名\AppData\Roaming\npm\openclaw.cmd

参数：
```
gateway start
```
完成创建

高级设置： - 勾选 "不管用户是否登录都要运行" - 勾选 "使用最高权限运行" - 在"条件"中取消"只有在计算机使用交流电源时才启动此任务"

3.3 启动网关¶

# 启动网关
openclaw gateway start

# 查看状态
openclaw gateway status

# 查看日志
openclaw gateway logs

3.4 访问 Web 控制面板¶

打开浏览器访问：

http://127.0.0.1:18789/

如果提示输入 token，在配置向导中会生成。

常见错误及解决方案¶

错误 1：Git 未找到¶

错误信息：

npm error syscall spawn git
npm error enoent
npm error spawn git ENOENT

原因： 系统未安装 Git 或 Git 不在 PATH 中

解决方案：

# 安装 Git
winget install Git.Git

# 重启 PowerShell 后验证
git --version

错误 2：CMake 下载失败¶

错误信息：

[node-llama-cpp] Failed to download cmake
Error: connect ETIMEDOUT

原因： 网络问题导致 CMake 下载失败

解决方案：

# 手动安装 CMake
winget install Kitware.CMake

# 验证
cmake --version

错误 3：Visual Studio C++ 工具链缺失¶

错误信息：

gyp ERR! find VS
gyp ERR! find VS msvs_version not set from command line or npm config
gyp ERR! find VS checking VS2022 not found
gyp ERR! find VS not found: most reliable installation method is missing

原因： 未安装 Visual Studio Build Tools 或 C++ 工作负载

解决方案：

安装 Visual Studio Build Tools：

winget install Microsoft.VisualStudio.2022.BuildTools

打开 Visual Studio Installer
点击 Modify
勾选 Desktop development with C++
确保包含以下组件：
MSVC v143 - VS 2022 C++ build tools
Windows 10/11 SDK
C++ CMake tools for Windows
重启 PowerShell

重新安装 OpenClaw：

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

错误 4：node-gyp 编译失败¶

错误信息：

gyp ERR! build error
gyp ERR! stack Error: `C:\Program Files\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe` failed with exit code: 1

原因： 编译环境不完整或网络问题

解决方案：

确保已安装所有依赖（Git、CMake、VS Build Tools、Python）

设置 npm 使用国内镜像（可选）：

npm config set registry https://registry.npmmirror.com

清理后重新安装：

npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest --omit=optional

错误 5：权限错误¶

错误信息：

Error: EACCES: permission denied, mkdir 'C:\Program Files\nodejs\node_modules\openclaw'

原因： npm 全局安装需要管理员权限

解决方案：

方法一：使用管理员权限运行 PowerShell - 右键 PowerShell → 以管理员身份运行

方法二：修改 npm 全局目录

# 创建新的全局目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.npm-global"

# 配置 npm
npm config set prefix "$env:USERPROFILE\.npm-global"

# 添加到 PATH（永久）
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\.npm-global", "User")

# 重启 PowerShell 后验证
npm install -g openclaw

错误 6：端口被占用¶

错误信息：

Error: listen EADDRINUSE: address already in use :::18789

原因： 18789 端口已被占用（可能是重复启动）

解决方案：

查找占用端口的进程：
```
netstat -ano | findstr :18789
```
终止进程（替换 PID）：
```
taskkill /F /PID <PID>
```
或者使用其他端口：
```
openclaw gateway --port 18790
```

错误 7：命令不存在¶

错误信息：

'openclaw' 不是内部或外部命令，也不是可运行的程序

原因： npm 全局目录不在 PATH 中

解决方案：

查找 npm 全局目录：
```
npm prefix -g
```

添加到 PATH：

# 临时添加（当前会话）
$env:Path += ";" + (npm prefix -g)

# 永久添加
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$(npm prefix -g)", "User")

重启 PowerShell

错误 8：WebSocket 连接失败（WhatsApp/Telegram）¶

错误信息：

WebSocket connection failed
Channel connection timeout

原因： 原生 Windows 的 WebSocket 实现与某些通道不兼容

解决方案：

强烈建议： 对于 WhatsApp/Telegram 通道，使用 WSL2 安装

如果必须使用原生 Windows： 1. 确保防火墙允许 Node.js 访问网络 2. 尝试使用代理 3. 考虑切换到 Discord/Slack 等更稳定的通道

原生 Windows vs WSL2 对比¶

特性	原生 Windows	WSL2 (Ubuntu)
安装难度	⭐⭐⭐⭐ 困难	⭐⭐ 简单
依赖复杂度	高（需手动安装）	低（包管理器）
文件访问	✅ 直接访问	⚠️ 通过 /mnt/c
性能	⭐⭐⭐⭐ 原生	⭐⭐⭐ 虚拟化损耗
兼容性	⚠️ 部分通道问题	✅ 官方推荐
维护成本	高	低
适合场景	Windows 开发	生产环境

何时选择原生 Windows？¶

✅ 适合原生安装的情况： - 需要频繁访问 Windows 文件（如桌面、文档） - 有 Windows 开发经验 - 仅使用 Web UI 或 Discord/Slack 通道 - 不想使用虚拟化

❌ 建议使用 WSL2 的情况： - Windows 新手 - 需要 WhatsApp/Telegram 通道 - 追求稳定可靠 - 生产环境部署

PowerShell 语法注意事项¶

从 Linux/macOS 转过来的用户容易犯的错误：

# ❌ bash 语法（PowerShell 不支持）
openclaw gateway start && openclaw status

# ✅ PowerShell 语法
openclaw gateway start; openclaw status

# 或者分两行
openclaw gateway start
openclaw gateway status

# ❌ bash 语法
export OPENCLAW_HOME=C:\openclaw

# ✅ PowerShell 语法
$env:OPENCLAW_HOME = "C:\openclaw"

# ❌ bash 语法
cat ~/.openclaw/config.json

# ✅ PowerShell 语法
Get-Content $env:USERPROFILE\.openclaw\config.json

性能优化建议¶

1. 排除 Windows Defender 扫描¶

OpenClaw 频繁读写文件，可能被 Defender 拖慢。

添加排除项：

# 以管理员身份运行
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.openclaw"
Add-MpPreference -ExclusionPath "$(npm prefix -g)\node_modules\openclaw"

2. 配置环境变量¶

# 设置 OpenClaw 目录
$env:OPENCLAW_HOME = "D:\OpenClaw"
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", "D:\OpenClaw", "User")

# 设置状态目录
$env:OPENCLAW_STATE_DIR = "D:\OpenClaw\state"
[Environment]::SetEnvironmentVariable("OPENCLAW_STATE_DIR", "D:\OpenClaw\state", "User")

3. 限制日志大小¶

编辑配置文件 ~/.openclaw\openclaw.json：

{
  "logging": {
    "maxSize": "10MB",
    "maxFiles": 3
  }
}

安全建议¶

1. 限制网络访问¶

在配置文件中限制允许的连接：

{
  "channels": {
    "webchat": {
      "allowFrom": ["127.0.0.1", "192.168.1.0/24"]
    }
  }
}

2. 启用身份验证¶

{
  "auth": {
    "required": true,
    "type": "token",
    "token": "your-secure-token-here"
  }
}

3. 限制技能权限¶

{
  "skills": {
    "allowList": ["file.read", "web.search"],
    "denyList": ["exec", "file.delete", "file.write"]
  }
}

4. 定期安全审计¶

openclaw security audit --deep

卸载指南¶

完全卸载 OpenClaw¶

# 1. 停止网关
openclaw gateway stop

# 2. 卸载 CLI
npm uninstall -g openclaw

# 3. 删除配置目录
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw

# 4. 删除任务计划（如果创建了）
# 打开任务计划程序 → 删除 OpenClaw Gateway 任务

# 5. 清理环境变量（如果设置了）
# 系统属性 → 高级 → 环境变量 → 删除 OPENCLAW_* 变量

总结¶

原生 Windows 安装清单¶

安装前确认：

[ ] Windows 10 1903+ 或 Windows 11
[ ] Node.js 22+ 已安装
[ ] Git 已安装并添加到 PATH
[ ] CMake 已安装
[ ] Python 3.11 已安装
[ ] Visual Studio Build Tools + C++ 工作负载已安装
[ ] 管理员权限 PowerShell

安装步骤：

✅ 安装所有依赖
✅ npm install -g openclaw@latest
✅ openclaw onboard --install-daemon
✅ 配置任务计划程序
✅ openclaw gateway start
✅ 访问 http://127.0.0.1:18789/

最终建议¶

如果你的主要需求是：

📱 WhatsApp/Telegram 通道 → 使用 WSL2
🖥️ 仅 Web UI → 原生 Windows 可以
📁 频繁访问 Windows 文件 → 原生 Windows 更适合
🚀 生产环境 → 使用 WSL2 或 Linux 服务器
🎯 学习体验 → 两种都试试

我的个人建议：

如果你是 Windows 新手，直接用 WSL2。昨天的指南已经详细说明了 WSL2 安装流程，更简单、更稳定、官方支持更好。

如果你是 Windows 老手，享受折腾的过程，原生 Windows 安装会让你更了解这个工具的底层依赖。

无论选择哪种方式，OpenClaw 都是一个强大的工具，值得投入时间配置。

相关资源： - WSL2 安装指南 - 官方推荐方案 - OpenClaw 官方文档 - GitHub 讨论 #7462 - Windows 原生 vs WSL2 - GitHub Issue #23178 - 原生 Windows 支持讨论 - Node.js 下载 - Visual Studio Build Tools

问题反馈： 如果在安装过程中遇到本指南未覆盖的问题，欢迎在评论区留言，我会持续更新这篇文章。

下期预告： 我们将深入探讨 OpenClaw 的技能系统，教你如何自定义 AI 助手的能力，让它真正理解你的工作流。敬请期待！