OpenClaw Windows 安装与配置教程

---

---

🚀 SEO 摘要

本教程详细讲解在 Windows 系统上安装和配置 OpenClaw AI 工具的完整流程。核心内容包括：一键安装脚本（支持 PowerShell 一键部署）、两种安装方式对比（npm 与 Git 源码安装的优缺点）、高级安装参数（指定版本、跳过引导等）、Gateway 服务管理、环境变量配置以及常见问题排查（如执行策略限制、Node.js 版本过低、PATH 未生效等）。无论你是普通用户还是开发者，都能通过本文快速完成 OpenClaw 的安装与初始化。

📝 前言

OpenClaw 是一款基于 Node.js 的 AI 工具，支持通过 npm 或 Git 源码两种方式安装，内置 Gateway 服务，便于 AI 模型调用和配置管理。本文旨在解决 Windows 用户在安装 OpenClaw 过程中可能遇到的各种问题，提供从系统要求检查、一键安装、高级配置到故障排除的完整指南。适合以下读者：

• AI 开发者：需要快速部署 OpenClaw 进行 AI 应用开发
• Windows 用户：希望在 Windows 环境下使用 OpenClaw
• 运维人员：需要配置和管理 OpenClaw Gateway 服务
• 初学者：希望了解 OpenClaw 的基本安装和使用方法

通过阅读本文，你将掌握 OpenClaw 在 Windows 上的完整安装流程，并能根据自身需求选择最适合的安装方式。

📋 目录

• 1. 简介
• 2. 系统要求
• 3. 一键安装
• 4. 高级安装参数
• 5. 安装方式对比
• 6. 首次启动与引导配置
• 7. 手动安装依赖
• 8. 常用命令
• 9. Gateway 服务管理
• 10. 环境变量配置
• 11. 常见问题排查

---

1. 简介

OpenClaw 是一款基于 Node.js 的 AI 工具，支持通过 npm 或 Git 源码两种方式安装。它内置 Gateway 服务，支持 AI 模型调用和配置管理。

• 官网：https://openclaw.ai
• 安装脚本：https://openclaw.ai/install.ps1
• GitHub：https://github.com/openclaw/openclaw

---

2. 系统要求

项目	要求
操作系统	Windows 10 / 11（x64 或 ARM64）
PowerShell	5.0 或更高版本
Node.js	v22.19 或更高版本
Git	最新版（安装脚本会自动下载）
内存	建议 8GB+（构建时需要 8GB 堆空间）

检查 PowerShell 版本

$PSVersionTable.PSVersion

检查 Node.js 版本

node -v

如果版本低于 v22.19，安装脚本会自动帮你安装。

---

3. 一键安装

以管理员身份打开 PowerShell，执行：

iwr -useb https://openclaw.ai/install.ps1 | iex

或使用标准格式：

irm https://openclaw.ai/install.ps1 | iex

⚠️ 如果遇到执行策略限制，先运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

安装脚本将自动完成：

1. ✅ 检测并安装 Node.js（v22.19+）
2. ✅ 检测并安装 Git
3. ✅ 通过 npm 全局安装 OpenClaw
4. ✅ 配置 PATH 环境变量
5. ✅ 启动引导设置流程（onboard）

安装完成后，重启终端以确保 PATH 生效。

---

4. 高级安装参数

安装脚本支持以下参数：

irm https://openclaw.ai/install.ps1 | iex -Args "-Tag","beta","-NoOnboard"

参数	类型	默认值	说明
-Tag	字符串	latest	安装版本。可选 latest、beta、beta.x、精确版本号（如 1.0.0）、本地 .tgz 文件路径
-InstallMethod	字符串	npm	安装方式：npm（全局安装）或 git（源码克隆）
-GitDir	字符串	~\openclaw	Git 源码克隆目录（仅 git 方式使用）
-NoOnboard	开关	关闭	跳过安装后的引导设置
-NoGitUpdate	开关	关闭	禁用 git pull 更新（仅 git 方式）
-DryRun	开关	关闭	模拟运行，仅显示配置信息而不实际安装

安装指定版本

irm https://openclaw.ai/install.ps1 | iex -Args "-Tag","1.0.0"

安装 Beta 版本

irm https://openclaw.ai/install.ps1 | iex -Args "-Tag","beta"

跳过引导设置

irm https://openclaw.ai/install.ps1 | iex -Args "-NoOnboard"

使用 Git 源码安装

irm https://openclaw.ai/install.ps1 | iex -Args "-InstallMethod","git"

预览安装配置（不实际执行）

irm https://openclaw.ai/install.ps1 | iex -Args "-DryRun"

---

5. 安装方式对比

npm 安装（推荐）

优点	缺点
简单快速，一行命令搞定	需要 npm 全局目录权限
自动处理依赖	不方便修改源码
升级方便	—

Git 源码安装

优点	缺点
可修改源码	安装时间较长（需构建）
可切换分支/版本	需要 pnpm + 构建环境
适合开发者	需要 8GB+ 内存用于构建

💡 普通用户选 npm，开发者选 git。

---

6. 首次启动与引导配置

安装完成后，首次运行会自动进入引导设置（onboard）：

openclaw onboard

引导流程通常包含：

1. API Key 配置 — 设置 AI 模型的 API 密钥
2. 模型选择 — 选择默认使用的 AI 模型
3. 工作目录设置 — 指定项目文件存放位置
4. Gateway 服务 — 配置后台服务

如果跳过了引导（-NoOnboard），可随时手动运行：

openclaw onboard

配置检查

安装或升级后，运行诊断命令检查配置状态：

openclaw doctor

---

7. 手动安装依赖

如果自动安装失败，可手动安装依赖。

7.1 安装 Node.js

方式一：winget（推荐）

winget install OpenJS.NodeJS.LTS

方式二：Chocolatey

choco install nodejs-lts -y

方式三：Scoop

scoop install nodejs-lts

方式四：官网下载

前往 https://nodejs.org 下载 v22+ LTS 安装包，手动安装。

7.2 安装 Git

方式一：winget

winget install Git.Git

方式二：官网下载

前往 https://git-scm.com/download/win 下载安装。

7.3 便携式安装（自动）

安装脚本在无法使用包管理器时，会自动下载便携式依赖到：

%LOCALAPPDATA%\OpenClaw\deps\
├── portable-node\       ← Node.js 便携版
└── portable-git\        ← MinGit 精简版

---

8. 常用命令

# 查看帮助
openclaw --help

# 查看版本
openclaw --version

# 启动 Gateway 服务
openclaw gateway start

# 检查服务状态
openclaw gateway status

# 重启 Gateway 服务
openclaw gateway restart

# 运行配置诊断
openclaw doctor

# 重新运行引导设置
openclaw onboard

---

9. Gateway 服务管理

OpenClaw 内置 Gateway 服务，安装后可作为后台服务运行。

安装 Gateway 服务

openclaw gateway install

启动服务

openclaw gateway start

查看状态

openclaw gateway status

重启服务

openclaw gateway restart

强制重装 + 重启

openclaw gateway install --force
openclaw gateway restart

检查 Gateway 是否在运行（脚本方式）

openclaw daemon status --json

---

10. 环境变量配置

安装过程中会自动配置以下环境变量：

安装相关环境变量

环境变量	说明
OPENCLAW_INSTALL_METHOD	安装方式（npm / git）
OPENCLAW_GIT_DIR	Git 源码目录
OPENCLAW_NO_ONBOARD=1	跳过引导设置
OPENCLAW_GIT_UPDATE=0	禁用 git pull 更新
OPENCLAW_DRY_RUN=1	模拟运行模式

Node.js 内存优化

Git 安装方式会自动设置 Node 内存：

NODE_OPTIONS=--max-old-space-size=8192

如需手动调整，编辑系统环境变量：

# 查看当前设置
[Environment]::GetEnvironmentVariable("NODE_OPTIONS", "User")

# 设置新的堆空间（例如 16GB）
[Environment]::SetEnvironmentVariable("NODE_OPTIONS", "--max-old-space-size=16384", "User")

npm 配置优化

安装脚本会自动设置以下 npm 配置以优化安装体验：

npm config set loglevel error
npm config set update-notifier false
npm config set fund false
npm config set audit false

---

11. 常见问题排查

问题 1：执行策略限制

现象：无法加载文件，因为在此系统上禁止运行脚本

解决：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

问题 2：Node.js 版本过低

现象：安装提示 Node.js 版本不符合要求

解决：

# 卸载旧版本
winget uninstall OpenJS.NodeJS

# 安装最新 LTS
winget install OpenJS.NodeJS.LTS

# 重启终端后验证
node -v

问题 3：PATH 未生效

现象：安装完成后输入 openclaw 提示命令不存在

解决：

1. 关闭当前终端，重新打开一个新的
2. 如果仍然无效，手动添加 PATH：

# 查看 npm 全局目录
npm config get prefix

# 将输出的路径添加到用户 PATH
# 设置 → 系统 → 高级系统设置 → 环境变量 → 用户变量 → Path → 新建

问题 4：Git 安装方式构建失败

现象：pnpm build 报错或内存不足

解决：

# 确保有足够的内存
$env:NODE_OPTIONS = "--max-old-space-size=8192"

# 清除 node_modules 重试
Remove-Item -Recurse -Force node_modules
pnpm install
pnpm build

问题 5：npm 安装权限问题

现象：EACCES permission denied

解决：

# 方法一：以管理员身份运行 PowerShell
# 方法二：修改 npm 全局目录
npm config set prefix "$env:APPDATA\npm"

问题 6：安装后 Gateway 服务异常

解决：

# 强制重装 Gateway
openclaw gateway install --force
openclaw gateway restart

# 检查状态
openclaw gateway status --json

问题 7：查看安装失败日志

安装失败时，npm 会生成调试日志：

# 查找最近的 npm 日志
Get-ChildItem "$env:APPDATA\npm-cache\_logs" -Filter "npm-debug-*.log" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1 |
  Get-Content -Tail 120

---

📁 安装路径参考

组件	路径
npm 全局安装	npm config get prefix 查看
Git 源码目录	%USERPROFILE%\openclaw
便携式依赖	%LOCALAPPDATA%\OpenClaw\deps\
Git wrapper（git 方式）	%USERPROFILE%\.local\bin\openclaw.cmd
npm 配置	%APPDATA%\npm\etc\npmrc

---

🔄 升级 OpenClaw

npm 方式升级

npm install -g openclaw@latest

或重新运行安装脚本（会自动识别升级）：

irm https://openclaw.ai/install.ps1 | iex

Git 方式升级

cd $env:USERPROFILE\openclaw
git pull --rebase
pnpm install
pnpm build
openclaw doctor --non-interactive

---

🔗 官方网站：https://openclaw.ai