# Windows 部署 OpenClaw 完整指南

## 📋 目录

1. [系统要求](#系统要求)

2. [快速开始](#快速开始)

3. [详细安装步骤](#详细安装步骤)

4. [配置 Gateway](#配置-gateway)

5. [开机自启动设置](#开机自启动设置)

6. [常见问题排查](#常见问题排查)

7. [管理命令参考](#管理命令参考)

---

## 系统要求

### 硬件要求

- **CPU**: 双核处理器或更高

- **内存**: 最低 2GB，推荐 4GB+

- **磁盘空间**: 至少 1GB 可用空间

- **网络**: 需要网络连接（支持离线模式）

### 软件要求

- **操作系统**: Windows 10/11 (64 位)

- **Node.js**: 版本 22 或更高

- **PowerShell**: 5.1 或更高（Windows 自带）

- **浏览器**: Chrome 92+、Edge、Firefox（用于访问 Control UI）

### 检查 Node.js 版本

```powershell

node --version

```

如果未安装或版本低于 22，请访问 [Node.js 官网](https://nodejs.org/) 下载安装。

---

## 快速开始

### 5 分钟快速部署

```powershell

# 1. 克隆仓库（或下载源码）

git clone https://github.com/openclaw/openclaw.git

cd openclaw

# 2. 安装依赖

pnpm install

# 3. 配置 Gateway Token

pnpm openclaw config set gateway.auth.mode token

pnpm openclaw config set gateway.auth.token "your-token-here"

# 4. 启用 Control UI 安全策略（HTTP 访问必需）

pnpm openclaw config set gateway.controlUi.allowInsecureAuth true

pnpm openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true

# 5. 启动 Gateway

pnpm openclaw gateway run --port 18789

# 6. 访问 Control UI

# 浏览器打开：http://127.0.0.1:18789/#token=your-token-here

```

---

## 详细安装步骤

### 步骤 1：获取源码

#### 方法 A：Git 克隆（推荐）

```powershell

git clone https://github.com/openclaw/openclaw.git

cd openclaw

```

#### 方法 B：下载 ZIP

1. 访问 https://github.com/openclaw/openclaw

2. 点击 "Code" → "Download ZIP"

3. 解压到任意目录（如 `C:\OpenClaw`）

4. 在文件夹中打开 PowerShell

### 步骤 2：安装依赖

#### 使用 pnpm（推荐）

```powershell

# 安装 pnpm（如果未安装）

npm install -g pnpm

# 安装项目依赖

pnpm install

```

#### 使用 npm

```powershell

npm install

```

### 步骤 3：初始化配置

```powershell

# 设置 Gateway 认证模式为 token

pnpm openclaw config set gateway.auth.mode token

# 生成或设置你的 Gateway Token

# 方法 1：自动生成（推荐）

$token = -join ((65..90) + (97..122) + (48..57) | Get-Random -Count 64 | ForEach-Object {[char]$_})

pnpm openclaw config set gateway.auth.token "$token"

Write-Host "Gateway Token: $token" -ForegroundColor Green

# 方法 2：手动指定

# pnpm openclaw config set gateway.auth.token "your-custom-token-here"

```

### 步骤 4：配置 Control UI 访问

```powershell

# 允许 HTTP 访问（开发环境必需）

pnpm openclaw config set gateway.controlUi.allowInsecureAuth true

pnpm openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true

# 配置端口（可选，默认 18789）

pnpm openclaw config set gateway.port 18789

pnpm openclaw config set gateway.bind loopback

```

---

## 配置 Gateway

### 查看当前配置

```powershell

pnpm openclaw config get gateway

```

### 常用配置项

```powershell

# 修改监听端口

pnpm openclaw config set gateway.port 8080

# 修改绑定地址（loopback=仅本地，any=所有网卡）

pnpm openclaw config set gateway.bind any

# 设置网关模式（local=本地，remote=远程）

pnpm openclaw config set gateway.mode local

# 配置 Tailscale（可选，用于远程访问）

pnpm openclaw config set gateway.tailscale.mode on

```

### 配置文件位置

```

C:\Users\<你的用户名>\.openclaw\openclaw.json

```

---

## 开机自启动设置

### 方案一：任务计划程序（⭐⭐⭐⭐⭐ 推荐）

#### 安装服务

```powershell

# 以管理员身份运行 PowerShell

# 右键点击开始菜单 → "Windows PowerShell (管理员)"

cd E:\openclaw

.\scripts\install-service.ps1

```

**安装成功后会显示：**

```

======================================

安装成功！

======================================

任务名称：OpenClaw Gateway

启动时间：用户登录时自动启动

管理命令:

  查看状态：Get-ScheduledTask 'OpenClaw Gateway'

  立即启动：Start-ScheduledTask 'OpenClaw Gateway'

  停止任务：Stop-ScheduledTask 'OpenClaw Gateway'

  卸载服务：.\scripts\uninstall-service.ps1

```

#### 验证安装

```powershell

# 查看任务状态

Get-ScheduledTask "OpenClaw Gateway"

# 立即启动测试

Get-ScheduledTask "OpenClaw Gateway" | Start-ScheduledTask

# 等待 5 秒后访问浏览器

Start-Sleep -Seconds 5

```

#### 管理命令

```powershell

# 禁用服务（不删除）

Disable-ScheduledTask "OpenClaw Gateway"

# 启用服务

Enable-ScheduledTask "OpenClaw Gateway"

# 查看详细信息

Get-ScheduledTask "OpenClaw Gateway" | Select-Object *

# 卸载服务

.\scripts\uninstall-service.ps1

```

### 方案二：启动文件夹（简单但功能有限）

```powershell

# 1. 打开启动文件夹

shell:startup

# 2. 创建快捷方式

# 目标指向：E:\openclaw\scripts\start-gateway.bat

# 名称：OpenClaw Gateway

# 3. 设置最小化运行（可选）

# 右键快捷方式 → 属性 → 运行方式：最小化

```

---

## 常见问题排查

### 问题 1：ERR_CONNECTION_REFUSED

**症状**：浏览器显示 "127.0.0.1 拒绝了我们的连接请求"

**原因**：Gateway 未启动或端口被占用

**解决方法**：

```powershell

# 1. 检查 Gateway 是否在运行

netstat -ano | findstr :18789

# 2. 如果没有看到 LISTENING，启动 Gateway

pnpm openclaw gateway run --port 18789

# 3. 如果端口被占用，杀死旧进程

Get-Process | Where-Object {$_.Id -eq <PID>} | Stop-Process -Force

# 4. 重新启动

pnpm openclaw gateway run --port 18789

```

### 问题 2：WebSocket 连接失败（disconnected 1000）

**症状**：Control UI 显示 "disconnected (1000): no reason"

**原因**：Control UI 安全策略限制

**解决方法**：

```powershell

# 确保已配置以下选项

pnpm openclaw config set gateway.controlUi.allowInsecureAuth true

pnpm openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true

# 重启 Gateway

Get-ScheduledTask "OpenClaw Gateway" | Stop-ScheduledTask

Start-Sleep -Seconds 2

Get-ScheduledTask "OpenClaw Gateway" | Start-ScheduledTask

```

### 问题 3：Token 认证失败

**症状**：显示 "unauthorized: gateway token missing/mismatch"

**解决方法**：

```powershell

# 1. 查看当前 Token

pnpm openclaw config get gateway.auth.token

# 2. 重新设置 Token

pnpm openclaw config set gateway.auth.token "new-token-here"

# 3. 使用带 Token 的 URL

# http://127.0.0.1:18789/#token=your-token-here

```

### 问题 4：PowerShell 脚本无法执行

**症状**：运行 `.ps1` 脚本时报错 "禁止在此系统上运行脚本"

**解决方法**：

```powershell

# 以管理员身份运行 PowerShell

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 或者临时允许

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

```

### 问题 5：开机自启动不工作

**症状**：重启后 Gateway 没有自动启动

**排查步骤**：

```powershell

# 1. 检查任务状态

Get-ScheduledTask "OpenClaw Gateway" | Select-Object State, LastRunResult

# 2. 查看任务历史

# 打开"任务计划程序" → 找到"OpenClaw Gateway" → 查看"历史记录"

# 3. 手动触发测试

Get-ScheduledTask "OpenClaw Gateway" | Start-ScheduledTask

# 4. 检查日志

Get-Content "$env:LOCALAPPDATA\Temp\openclaw\*.log" -Tail 50

```

### 问题 6：磁盘空间不足（ENOSPC）

**症状**：日志显示 "Error: ENOSPC: no space left on device"

**解决方法**：

```powershell

# 1. 清理 C 盘空间

# 删除临时文件、回收站等

# 2. 清理 OpenClaw 旧日志

Remove-Item "$env:LOCALAPPDATA\Temp\openclaw\*.log" -ErrorAction SilentlyContinue

# 3. 重启 Gateway

pnpm openclaw gateway restart

```

---

## 管理命令参考

### Gateway 管理

```powershell

# 启动 Gateway

pnpm openclaw gateway run --port 18789

# 后台运行（无窗口）

Start-Process node -ArgumentList "scripts/run-node.mjs","gateway","run","--port","18789" -WindowStyle Hidden

# 停止 Gateway（如果在后台运行）

Get-Process node | Where-Object {$_.CommandLine -like "*gateway*"} | Stop-Process -Force

# 查看 Gateway 状态

pnpm openclaw gateway status

# 查看日志

Get-Content "$env:LOCALAPPDATA\Temp\openclaw\openclaw-$(Get-Date -Format 'yyyy-MM-dd').log" -Tail 50

```

### 任务计划程序管理

```powershell

# 查看状态

Get-ScheduledTask "OpenClaw Gateway"

# 立即启动

Get-ScheduledTask "OpenClaw Gateway" | Start-ScheduledTask

# 停止

Get-ScheduledTask "OpenClaw Gateway" | Stop-ScheduledTask

# 禁用（保留配置）

Disable-ScheduledTask "OpenClaw Gateway"

# 启用

Enable-ScheduledTask "OpenClaw Gateway"

# 卸载

.\scripts\uninstall-service.ps1

```

### 配置管理

```powershell

# 查看配置

pnpm openclaw config get gateway

# 修改配置

pnpm openclaw config set gateway.<key> <value>

# 示例：修改端口

pnpm openclaw config set gateway.port 8080

# 重置配置

pnpm openclaw config reset gateway

```

### 诊断工具

```powershell

# 检查端口占用

netstat -ano | findstr :18789

# 检查进程

Get-Process | Where-Object {$_.ProcessName -eq "node"}

# 检查防火墙规则

Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*OpenClaw*"}

# 测试 WebSocket 连接

# 使用浏览器开发者工具或 wscat 工具

```

---

## 附录

### A. 文件结构说明

```

openclaw/

├── scripts/

│   ├── start-gateway.bat          # 批处理启动脚本

│   ├── install-service.ps1        # 安装开机自启动

│   └── uninstall-service.ps1      # 卸载开机自启动

├── dist/                          # 编译后的代码

├── package.json                   # 项目配置

└── README.md                      # 项目说明

```

### B. 重要路径

```

配置文件：C:\Users\<用户名>\.openclaw\openclaw.json

日志文件：C:\Users\<用户名>\AppData\Local\Temp\openclaw\

会话数据：C:\Users\<用户名>\.openclaw\sessions\

设备配对：C:\Users\<用户名>\.openclaw\devices\

```

### C. 相关资源

- **官方文档**: https://docs.openclaw.ai/

- **GitHub 仓库**: https://github.com/openclaw/openclaw

- **问题反馈**: https://github.com/openclaw/openclaw/issues

- **Control UI**: http://127.0.0.1:18789/

---

## 快速参考卡片

```powershell

# ==================== 日常使用 ====================

# 启动 Gateway

pnpm openclaw gateway run --port 18789

# 访问 Control UI

# http://127.0.0.1:18789/#token=<your-token>

# 查看状态

pnpm openclaw gateway status

# ==================== 开机自启动 ====================

# 安装

.\scripts\install-service.ps1

# 查看状态

Get-ScheduledTask "OpenClaw Gateway"

# 卸载

.\scripts\uninstall-service.ps1

# ==================== 故障排查 ====================

# 查看日志

Get-Content "$env:LOCALAPPDATA\Temp\openclaw\*.log" -Tail 50

# 检查端口

netstat -ano | findstr :18789

# 重启 Gateway

Get-ScheduledTask "OpenClaw Gateway" | Stop-ScheduledTask

Start-Sleep -Seconds 2

Get-ScheduledTask "OpenClaw Gateway" | Start-ScheduledTask

```

---

**最后更新**: 2026-02-22  

**适用版本**: OpenClaw 2026.2.22+  

**适用系统**: Windows 10/11 (64 位)