OpenClaw完整部署指南-从安装到开机自启

绝不裸奔0012026-03-23 9:46

OpenClaw 完整部署指南：Windows WSL2 环境安装与开机自启动配置

文档版本 : 1.0
最后更新 : 2026-03-22
适用环境 : Windows 10/11 + WSL2 + Ubuntu 20.04/22.04/24.04
OpenClaw 版本 : latest (2026.3.13+)
作者: 小e工作室

📖 目录

  • [1. 概述](#1. 概述)
  • [2. 系统要求](#2. 系统要求)
  • [3. 架构说明](#3. 架构说明)
  • [4. 第一部分：安装 OpenClaw](#4. 第一部分：安装 OpenClaw)
    • [4.1 安装 WSL2](#4.1 安装 WSL2)
    • [4.2 配置 WSL2 Ubuntu](#4.2 配置 WSL2 Ubuntu)
    • [4.3 安装 Node.js](#4.3 安装 Node.js)
    • [4.4 安装 OpenClaw](#4.4 安装 OpenClaw)
  • [5. 第二部分：配置网络访问](#5. 第二部分：配置网络访问)
  • [6. 第三部分：配置开机自启动](#6. 第三部分：配置开机自启动)
    • [6.1 理解自动启动机制](#6.1 理解自动启动机制)
    • [6.2 配置 WSL 层服务](#6.2 配置 WSL 层服务)
    • [6.3 创建 Windows 启动脚本](#6.3 创建 Windows 启动脚本)
    • [6.4 配置 Windows 任务计划程序](#6.4 配置 Windows 任务计划程序)
  • [7. 验证与测试](#7. 验证与测试)
  • [8. 常见问题排查](#8. 常见问题排查)
  • [9. 维护与管理](#9. 维护与管理)
  • [10. 卸载指南](#10. 卸载指南)

1. 概述

本指南提供了在 Windows WSL2 环境中完整部署 OpenClaw 的端到端解决方案，包括：

  • ✅ 完整安装流程：从零开始安装 WSL2、Ubuntu、Node.js 和 OpenClaw
  • ✅ 网络配置：实现从 Windows 浏览器访问 WSL 中的 OpenClaw
  • ✅ 开机自启：配置 Windows 启动时自动运行 OpenClaw，无需手动登录 WSL
  • ✅ 生产就绪：包含日志管理、错误处理和故障排查

1.1 为什么选择 WSL2 部署？

优势：

  • 🎯 原生性能：接近 Linux 原生性能，优于虚拟机
  • 🔧 易于管理：集成 Windows 生态系统，便于文件共享
  • 🚀 自动启动：可实现开机自启，无需手动操作
  • 🛡️ 安全隔离：沙箱环境，不影响 Windows 系统
  • 💰 零成本：Windows 内置功能，无需额外虚拟化软件

适用场景：

  • Windows 用户需要使用 OpenClaw
  • 需要开机自动运行 OpenClaw 服务
  • 希望在 Windows 和 Linux 之间无缝切换
  • 开发和测试环境

2. 系统要求

2.1 硬件要求

组件 最低配置 推荐配置
操作系统 Windows 10 版本 2004+ Windows 11
处理器 双核 CPU 四核及以上
内存 4 GB RAM 8 GB+ RAM
磁盘空间 10 GB 可用空间 20 GB+ SSD
网络 稳定的互联网连接 宽带连接

2.2 软件要求

  • Windows 版本: Windows 10 (2004+) 或 Windows 11
  • WSL 版本: WSL2 (非 WSL1)
  • Linux 发行版: Ubuntu 20.04 / 22.04 / 24.04
  • Node.js: 22.16+ (推荐 24.x)
  • PowerShell: 5.1+ (Windows 内置)

2.3 检查系统环境

在开始之前，请运行以下命令检查您的环境：

powershell 复制代码 
# 在 PowerShell 中运行
# 检查 Windows 版本
winver

# 检查 WSL 版本
wsl --version

# 检查 WSL 状态
wsl --status

3. 架构说明

3.1 整体架构图

复制代码 
┌─────────────────────────────────────────────────────────────┐
│                         Windows 主机                        │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         Windows 任务计划程序 (Task Scheduler)         │  │
│  │  触发器: 开机后 30 秒                                 │  │
│  │  运行: 启动OpenClaw.ps1                              │  │
│  └───────────────────┬──────────────────────────────────┘  │
│                      │                                       │
│                      ▼                                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         WSL2 Ubuntu (Linux 子系统)                    │  │
│  │                                                       │  │
│  │  ┌────────────────────────────────────────────────┐ │  │
│  │  │  systemd 用户服务                              │ │  │
│  │  │  openclaw-gateway.service                      │ │  │
│  │  │  - 自动重启                                    │ │  │
│  │  │  - 日志管理                                    │ │  │
│  │  │  - 状态监控                                    │ │  │
│  │  └───────────────┬────────────────────────────────┘ │  │
│  │                  │                                     │  │
│  │                  ▼                                     │  │
│  │  ┌────────────────────────────────────────────────┐ │  │
│  │  │  OpenClaw Gateway                              │ │  │
│  │  │  - 监听端口: 127.0.0.1:18789                   │ │  │
│  │  │  - 提供 Web UI 和 API                          │ │  │
│  │  └───────────────┬────────────────────────────────┘ │  │
│  └──────────────────┼──────────────────────────────────┘  │
│                     │                                        │
└─────────────────────┼────────────────────────────────────────┘
                      │
                      ▼
              ┌─────────────────┐
              │  Windows 浏览器  │
              │  localhost:18789│
              └─────────────────┘

3.2 启动流程详解

复制代码 
Windows 启动
    ↓
等待 30 秒 (WSL 初始化时间)
    ↓
任务计划程序触发
    ↓
PowerShell 执行启动脚本
    ↓
启动 WSL Ubuntu (无需登录)
    ↓
执行: systemctl --user start openclaw-gateway.service
    ↓
systemd 启动 OpenClaw Gateway
    ↓
OpenClaw 监听 127.0.0.1:18789
    ↓
✅ 服务就绪，可访问

3.3 关键技术点

  1. 双层启动机制：

    • Windows 层：任务计划程序负责触发
    • Linux 层：systemd 负责服务管理

  2. 用户级服务 (user-level service)：

    • 使用 systemctl --user 而非 sudo systemctl
    • 更安全，无需 root 权限
    • OpenClaw 安装时自动创建

  3. 网络访问：

    • WSL2 自动 localhost 转发 (Windows 11 默认)
    • 无需额外端口转发配置

4. 第一部分：安装 OpenClaw

4.1 安装 WSL2

4.1.1 启用 WSL

打开 PowerShell (管理员)，执行：

powershell 复制代码 
# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启计算机
Restart-Computer
4.1.2 设置 WSL2 为默认

重启后，继续在 PowerShell (管理员) 中执行：

powershell 复制代码 
# 设置 WSL2 为默认版本
wsl --set-default-version 2
4.1.3 安装 Ubuntu

方法 A：从 Microsoft Store 安装 (推荐)

  1. 打开 Microsoft Store
  2. 搜索 "Ubuntu 24.04 LTS" 或 "Ubuntu 22.04 LTS"
  3. 点击"获取"或"安装"
  4. 等待安装完成

方法 B：使用命令行安装

powershell 复制代码 
# 查看可用的 Linux 发行版
wsl --list --online

# 安装 Ubuntu 24.04
wsl --install -d Ubuntu-24.04

# 安装完成后会提示重启
4.1.4 初始化 Ubuntu

首次启动会要求创建用户名和密码：

复制代码 
Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: parobot
Enter new UNIX password: ******
Retype new UNIX password: ******

⚠️ 重要：请记住您的用户名和密码，后续配置需要用到。

4.2 配置 WSL2 Ubuntu

4.2.1 更新系统包

在 WSL Ubuntu 终端中执行：

bash 复制代码 
# 更新软件包列表
sudo apt update

# 升级已安装的包
sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl git build-essential python3 make g++ cmake
4.2.2 验证安装
bash 复制代码 
# 检查 Ubuntu 版本
lsb_release -a

# 检查 WSL 版本
wsl --version

预期输出示例：

复制代码 
Distributor ID: Ubuntu
Description:    Ubuntu 24.04 LTS
Release:        24.04
Codename:       noble

4.3 安装 Node.js

OpenClaw 需要 Node.js 22.16 或更高版本。

4.3.1 方法 A：使用 NodeSource (推荐)
bash 复制代码 
# 添加 NodeSource 仓库 (Node.js 24.x)
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

预期输出：

复制代码 
v24.x.x
10.x.x
4.3.2 方法 B：使用 nvm (Node Version Manager)

如果需要管理多个 Node.js 版本：

bash 复制代码 
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# 重新加载配置
source ~/.bashrc

# 安装最新的 LTS 版本
nvm install --lts
nvm use --lts

# 验证
node --version

4.4 安装 OpenClaw

4.4.1 方法 A：使用官方安装脚本 (最简单)
bash 复制代码 
# 在 WSL Ubuntu 中执行
curl -fsSL https://openclaw.ai/install.sh | bash

如果不想运行 onboarding 向导，可以使用：

bash 复制代码 
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
4.4.2 方法 B：使用 npm 安装
bash 复制代码 
# 确保使用最新的 npm 版本
npm install -g npm@latest

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行 onboarding 配置向导
openclaw onboard --install-daemon
4.4.3 验证安装
bash 复制代码 
# 检查 OpenClaw 版本
openclaw --version

# 检查配置
openclaw doctor

# 查看 Gateway 状态
openclaw gateway status

预期输出示例：

复制代码 
openclaw: 2026.3.13
node: v24.0.0
...

Gateway: running (pid 1234, state active)
Listening: 127.0.0.1:18789
4.4.4 配置 OpenClaw

首次安装后，运行配置向导：

bash 复制代码 
openclaw onboard

按照提示完成：

  1. 配置 API 密钥 (如 OpenAI API)
  2. 设置默认模型
  3. 配置插件
  4. 启用网关服务

5. 第二部分：配置网络访问

OpenClaw 默认监听 127.0.0.1 (localhost)，在 WSL2 中可以直接从 Windows 浏览器访问。

5.1 检查当前网络配置

bash 复制代码 
# 在 WSL 中查看 Gateway 状态
openclaw gateway status

关键信息：

复制代码 
Gateway: bind=loopback (127.0.0.1), port=18789
Dashboard: http://127.0.0.1:18789/
Listening: 127.0.0.1:18789

5.2 从 Windows 访问

打开 Windows 浏览器，访问：

复制代码 
http://127.0.0.1:18789/

或

复制代码 
http://localhost:18789/

5.3 WSL2 网络模式说明

Windows 11 (22H2+) 默认行为：

  • ✅ 自动 localhost 转发
  • ✅ 无需额外配置
  • ✅ 直接访问 localhost:18789

Windows 10 或旧版本：

如果无法访问，需要配置端口转发（见 5.4）。

5.4 手动配置端口转发 (Windows 10)

如果自动转发不工作，在 PowerShell (管理员) 中执行：

powershell 复制代码 
# 1. 获取 WSL IP 地址
$wslIP = wsl hostname -I
Write-Host "WSL IP: $wslIP"

# 2. 添加端口转发规则
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIP

# 3. 配置防火墙规则
New-NetFirewallRule -DisplayName "OpenClaw WSL" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

# 4. 验证规则
netsh interface portproxy show all

删除端口转发规则：

powershell 复制代码 
netsh interface portproxy delete v4tov4 listenport=18789 listenaddress=0.0.0.0
Remove-NetFirewallRule -DisplayName "OpenClaw WSL"

5.5 配置镜像网络模式 (高级，Windows 11 22H2+)

编辑 Windows 用户目录下的 .wslconfig 文件：

powershell 复制代码 
# 在 PowerShell 中执行
notepad $env:USERPROFILE\.wslconfig

添加以下内容：

ini 复制代码 
[wsl2]
# 使用镜像网络模式 (Windows 11 22H2+)
networkingMode=mirrored
# 自动代理配置
autoProxy=true

保存后重启 WSL：

powershell 复制代码 
wsl --shutdown
wsl -d Ubuntu-24.04

6. 第三部分：配置开机自启动

本部分详细介绍如何实现 OpenClaw 随 Windows 自动启动。

6.1 理解自动启动机制

6.1.1 为什么需要双层机制？

  1. WSL2 的特性：

    • WSL2 不是传统虚拟机，不会自动启动所有服务
    • systemd 用户服务需要触发启动

  2. 解决方案：

    • WSL 层：使用 systemd 用户服务管理 OpenClaw
    • Windows 层：使用任务计划程序在启动时触发
6.1.2 OpenClaw 的服务架构

OpenClaw 安装时会自动创建用户级 systemd 服务：

bash 复制代码 
# 查看服务文件
ls ~/.config/systemd/user/openclaw-gateway.service

# 查看服务状态
systemctl --user status openclaw-gateway.service

关键点：

  • 服务文件位置：~/.config/systemd/user/openclaw-gateway.service
  • 这是用户级服务，不需要 root 权限
  • OpenClaw 安装时自动创建并启用

6.2 配置 WSL 层服务

6.2.1 检查现有服务

在 WSL Ubuntu 中执行：

bash 复制代码 
# 查看服务状态
systemctl --user status openclaw-gateway.service

# 查看服务是否启用
systemctl --user is-enabled openclaw-gateway.service

# 查看 Gateway 状态
openclaw gateway status

预期输出：

复制代码 
● openclaw-gateway.service - OpenClaw Gateway Service
   Loaded: loaded (/home/youruser/.config/systemd/user/openclaw-gateway.service; enabled)
   Active: active (running)
6.2.2 手动启用服务 (如果未启用)

如果服务显示 disabled，执行：

bash 复制代码 
# 启用开机自启
systemctl --user enable openclaw-gateway.service

# 启动服务
systemctl --user start openclaw-gateway.service

# 验证
systemctl --user status openclaw-gateway.service
6.2.3 配置 linger (保持用户服务运行)

为确保用户级服务在没有登录时也能运行，需要启用 linger：

bash 复制代码 
# 启用 linger
loginctl enable-linger $(whoami)

# 验证
loginctl show-user $(whoami) | grep Linger

输出应该是：

复制代码 
Linger=yes

⚠️ 重要：linger 允许用户服务在登出后继续运行，这是开机自启的关键。

6.3 创建 Windows 启动脚本

现在创建一个 PowerShell 脚本，用于从 Windows 启动 WSL 中的 OpenClaw 服务。

6.3.1 创建脚本文件

在 Windows 上创建文件：F:\OpenClaw_Installed\启动OpenClaw.ps1

powershell 复制代码 
# OpenClaw WSL Startup Script
# 功能: 通过 WSL 启动 OpenClaw Gateway 服务
# 作者: OpenClaw 社区
# 版本: 1.0

$ErrorActionPreference = "Continue"

# 配置参数
$WSLDistro = "Ubuntu-24.04"  # WSL 发行版名称
$LogPath = "$env:USERPROFILE\OpenClaw-Startup.log"

# 日志记录函数
function Write-Log {
    param([string]$Message)
    $Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $LogMessage = "[$Timestamp] $Message"
    Add-Content -Path $LogPath -Value $LogMessage
    Write-Host $Message
}

try {
    Write-Log "========================================"
    Write-Log "OpenClaw WSL Startup Script"
    Write-Log "========================================"
    Write-Log "Starting OpenClaw..."
    Write-Log "Using WSL distro: $WSLDistro"

    # 启动 OpenClaw 用户服务
    Write-Log "Starting OpenClaw gateway service..."

    $result = wsl -d $WSLDistro -- bash -c 'export XDG_RUNTIME_DIR=/run/user/$(id -u) && systemctl --user start openclaw-gateway.service' 2>&1
    Write-Log "Start command result: $result"

    # 等待服务启动
    Start-Sleep -Seconds 3

    # 检查服务状态
    Write-Log "Checking service status..."
    $status = wsl -d $WSLDistro -- bash -c 'export XDG_RUNTIME_DIR=/run/user/$(id -u) && systemctl --user is-active openclaw-gateway.service' 2>&1
    Write-Log "Service status: $status"

    # 检查 Gateway 状态
    Write-Log "Checking OpenClaw gateway..."
    $gateway = wsl -d $WSLDistro -- bash -c 'cd ~ && openclaw gateway status 2>&1' | Select-String -Pattern "running|active" -Context 0,2
    Write-Log "Gateway status: $gateway"

    Write-Log "========================================"
    Write-Log "OpenClaw startup completed!"
    Write-Log "Dashboard: http://127.0.0.1:18789/"
    Write-Log "========================================"

    Write-Host "SUCCESS: OpenClaw is running!" -ForegroundColor Green
    Write-Host "Access at: http://127.0.0.1:18789/" -ForegroundColor Cyan

} catch {
    Write-Log "Error occurred: $_"
    Write-Host "Error: $_" -ForegroundColor Red
    exit 1
}
6.3.2 测试脚本

在 PowerShell (普通用户) 中执行：

powershell 复制代码 
F:\OpenClaw_Installed\启动OpenClaw.ps1

预期输出：

复制代码 
Starting OpenClaw...
Using WSL distro: Ubuntu-24.04
Starting OpenClaw gateway service...
Start command result: ...
Checking service status...
Service status: active
Gateway status: running
========================================
OpenClaw startup completed!
Dashboard: http://127.0.0.1:18789/
========================================
SUCCESS: OpenClaw is running!
Access at: http://127.0.0.1:18789/
6.3.3 检查日志
powershell 复制代码 
# 查看日志文件
notepad $env:USERPROFILE\OpenClaw-Startup.log

6.4 配置 Windows 任务计划程序

现在创建 Windows 任务计划程序任务，实现开机自动运行启动脚本。

6.4.1 创建任务配置脚本

创建文件：F:\OpenClaw_Installed\创建任务计划程序.ps1

powershell 复制代码 
# OpenClaw AutoStart Task Creator
# 功能: 创建 Windows 任务计划程序任务
# 作者: OpenClaw 社区
# 版本: 1.0

# 配置参数
$TaskName = "OpenClaw WSL AutoStart"
$ScriptPath = "F:\OpenClaw_Installed\启动OpenClaw.ps1"
$DelaySeconds = 30  # 启动延迟(秒)

Write-Host "========================================" -ForegroundColor Cyan
Write-Host "OpenClaw AutoStart Task Creator" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan
Write-Host ""

# 检查管理员权限
$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

if (-not $isAdmin) {
    Write-Host "ERROR: This script requires administrator privileges!" -ForegroundColor Red
    Write-Host ""
    Write-Host "Please:" -ForegroundColor Yellow
    Write-Host "1. Right-click on PowerShell" -ForegroundColor Yellow
    Write-Host "2. Select 'Run as Administrator'" -ForegroundColor Yellow
    Write-Host "3. Run this script again" -ForegroundColor Yellow
    Write-Host ""
    $null = Read-Host "Press Enter to exit"
    exit 1
}

Write-Host "✓ Administrator privileges confirmed" -ForegroundColor Green
Write-Host ""

# 检查脚本文件
if (-not (Test-Path $ScriptPath)) {
    Write-Host "ERROR: Script file not found: $ScriptPath" -ForegroundColor Red
    $null = Read-Host "Press Enter to exit"
    exit 1
}

Write-Host "Configuration:" -ForegroundColor Cyan
Write-Host "  Task Name: $TaskName"
Write-Host "  Script: $ScriptPath"
Write-Host "  Startup Delay: $DelaySeconds seconds"
Write-Host ""

# 删除现有任务(如果存在)
$existingTask = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
if ($existingTask) {
    Write-Host "Existing task found. Removing..." -ForegroundColor Yellow
    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false
    Write-Host "✓ Existing task removed" -ForegroundColor Green
    Write-Host ""
}

# 创建触发器 (开机启动 + 延迟)
Write-Host "Creating task trigger..." -ForegroundColor Cyan
$trigger = New-ScheduledTaskTrigger -AtStartup
$trigger.Delay = "PT${DelaySeconds}S"

# 创建操作
Write-Host "Creating task action..." -ForegroundColor Cyan
$action = New-ScheduledTaskAction `
    -Execute "PowerShell.exe" `
    -Argument "-NoProfile -ExecutionPolicy Bypass -File `"$ScriptPath`"" `
    -WorkingDirectory "F:\OpenClaw_Installed"

# 创建设置
Write-Host "Configuring task settings..." -ForegroundColor Cyan
$settings = New-ScheduledTaskSettingsSet `
    -AllowStartIfOnBatteries `
    -DontStopIfGoingOnBatteries `
    -StartWhenAvailable `
    -DontStopOnIdleEnd

# 注册任务
Write-Host "Registering scheduled task..." -ForegroundColor Cyan
Register-ScheduledTask `
    -TaskName $TaskName `
    -Trigger $trigger `
    -Action $action `
    -Settings $settings `
    -Description "Automatically start OpenClaw WSL service at Windows startup" `
    -User "SYSTEM" `
    | Out-Null

Write-Host ""
Write-Host "========================================" -ForegroundColor Green
Write-Host "Task created successfully!" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Green
Write-Host ""

# 显示任务信息
Write-Host "Task Details:" -ForegroundColor Cyan
Get-ScheduledTask -TaskName $TaskName | Format-List Name, State, Description
Write-Host ""

Write-Host "Configuration Summary:" -ForegroundColor Cyan
Write-Host "  ✓ Task will run $DelaySeconds seconds after Windows startup" -ForegroundColor Green
Write-Host "  ✓ Log file: $env:USERPROFILE\OpenClaw-Startup.log" -ForegroundColor Green
Write-Host "  ✓ Task runs as SYSTEM user" -ForegroundColor Green
Write-Host ""

Write-Host "Management Commands:" -ForegroundColor Cyan
Write-Host "  Manual start:    Start-ScheduledTask -TaskName '$TaskName'" -ForegroundColor White
Write-Host "  Disable task:    Disable-ScheduledTask -TaskName '$TaskName'" -ForegroundColor White
Write-Host "  Enable task:     Enable-ScheduledTask -TaskName '$TaskName'" -ForegroundColor White
Write-Host "  Remove task:     Unregister-ScheduledTask -TaskName '$TaskName' -Confirm:`$false" -ForegroundColor White
Write-Host ""

# 询问是否立即测试
$response = Read-Host "Test the task now? (Y/N)"

if ($response -eq 'Y' -or $response -eq 'y') {
    Write-Host ""
    Write-Host "Starting task test..." -ForegroundColor Cyan
    Start-ScheduledTask -TaskName $TaskName
    Write-Host "✓ Task started. Please wait a few seconds..." -ForegroundColor Green
    Start-Sleep -Seconds 5

    if (Test-Path $env:USERPROFILE\OpenClaw-Startup.log) {
        Write-Host ""
        Write-Host "Recent log entries:" -ForegroundColor Cyan
        Get-Content $env:USERPROFILE\OpenClaw-Startup.log -Tail 15
    }

    Write-Host ""
    Write-Host "Test completed!" -ForegroundColor Green
}

Write-Host ""
$null = Read-Host "Press Enter to exit"
6.4.2 运行配置脚本
  1. 右键点击 PowerShell
  2. 选择 "以管理员身份运行"
  3. 执行脚本：
powershell 复制代码 
F:\OpenClaw_Installed\创建任务计划程序.ps1
  1. 按提示操作
  2. 选择 Y 立即测试
6.4.3 验证任务创建
powershell 复制代码 
# 查看任务状态
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 查看详细信息
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"

预期输出：

复制代码 
Name                          State
----                          -----
OpenClaw WSL AutoStart        Ready

7. 验证与测试

7.1 完整验证清单

7.1.1 WSL 服务检查
bash 复制代码 
# 在 WSL Ubuntu 中执行

# 1. 检查服务状态
systemctl --user status openclaw-gateway.service

# 2. 检查是否启用
systemctl --user is-enabled openclaw-gateway.service
# 输出应该: enabled

# 3. 检查 linger 状态
loginctl show-user $(whoami) | grep Linger
# 输出应该: Linger=yes

# 4. 检查 Gateway 状态
openclaw gateway status

预期输出示例：

复制代码 
● openclaw-gateway.service - OpenClaw Gateway Service
   Loaded: loaded (/home/parobot/.config/systemd/user/openclaw-gateway.service; enabled)
   Active: active (running)

Service: systemd (enabled)
Gateway: running (pid 1234, state active)
Listening: 127.0.0.1:18789
7.1.2 Windows 任务检查
powershell 复制代码 
# 在 PowerShell 中执行

# 1. 查看任务状态
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 2. 查看任务历史
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"

# 3. 查看日志文件
Get-Content $env:USERPROFILE\OpenClaw-Startup.log -Tail 20
7.1.3 网络访问测试
powershell 复制代码 
# 在浏览器中访问
# http://127.0.0.1:18789/

# 或使用 curl 测试
curl http://127.0.0.1:18789/

7.2 重启测试 (终极验证)

  1. 重启 Windows：
powershell 复制代码 
Restart-Computer

  1. 等待 40-60 秒 (30 秒延迟 + WSL 启动时间)

  2. 检查服务：

bash 复制代码 
# 在 WSL 中
systemctl --user status openclaw-gateway.service
  1. 访问 Dashboard：

打开浏览器访问 http://127.0.0.1:18789/

  1. 检查日志：
powershell 复制代码 
notepad $env:USERPROFILE\OpenClaw-Startup.log

7.3 性能检查

bash 复制代码 
# 检查服务资源使用
systemctl --user show openclaw-gateway.service -p CPUUsage,MemoryCurrent

# 查看进程
ps aux | grep openclaw

# 检查端口监听
ss -tlnp | grep 18789

8. 常见问题排查

8.1 OpenClaw 安装问题

问题 1: Node.js 版本不兼容

错误信息：

复制代码 
error: openclaw@latest requires Node.js version >= 22.16

解决方案：

bash 复制代码 
# 升级 Node.js
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version  # 应该 >= 22.16
问题 2: npm 权限错误

错误信息：

复制代码 
npm ERR! code EACCES
npm ERR! syscall mkdir

解决方案：

bash 复制代码 
# 方案 A: 修复 npm 权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 方案 B: 使用 sudo (不推荐)
sudo npm install -g openclaw@latest --unsafe-perm
问题 3: sharp 库构建失败

错误信息：

复制代码 
sharp: Installation failed

解决方案：

bash 复制代码 
# 安装 sharp 依赖
sudo apt-get install -y libvips-dev

# 或忽略全局 libvips
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

8.2 网络访问问题

问题 4: 无法从 Windows 浏览器访问

症状 ：WSL 中 OpenClaw 运行正常，但浏览器无法访问 localhost:18789

诊断步骤：

bash 复制代码 
# 1. 在 WSL 中测试
curl http://127.0.0.1:18789/

# 2. 检查端口监听
ss -tlnp | grep 18789

# 3. 检查 Gateway 状态
openclaw gateway status

解决方案：

powershell 复制代码 
# 方案 A: 配置端口转发 (Windows 10)
$wslIP = wsl hostname -I
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIP
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

# 方案 B: 使用镜像网络模式 (Windows 11)
# 编辑 $env:USERPROFILE\.wslconfig
# 添加: networkingMode=mirrored
# 重启: wsl --shutdown

8.3 开机自启问题

问题 5: Windows 重启后 OpenClaw 未启动

诊断步骤：

powershell 复制代码 
# 1. 检查任务是否运行
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 2. 查看任务历史
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"

# 3. 查看日志
Get-Content $env:USERPROFILE\OpenClaw-Startup.log -Tail 50

# 4. 手动运行测试
Start-ScheduledTask -TaskName "OpenClaw WSL AutoStart"
Start-Sleep -Seconds 10
Get-Content $env:USERPROFILE\OpenClaw-Startup.log -Tail 20

解决方案：

powershell 复制代码 
# 方案 A: 增加启动延迟时间
# 编辑任务计划程序，将延迟从 30 秒改为 60 秒

# 方案 B: 检查 linger 状态
wsl -d Ubuntu-24.04 -- bash -c 'loginctl show-user $(whoami) | grep Linger'
# 如果输出不是 Linger=yes，执行:
wsl -d Ubuntu-24.04 -- bash -c 'loginctl enable-linger $(whoami)'

# 方案 C: 重新启用服务
wsl -d Ubuntu-24.04 -- bash -c 'systemctl --user enable openclaw-gateway.service'
问题 6: 任务计划程序任务失败

错误信息（在任务计划程序历史中）：

复制代码 
Task Start Failed

解决方案：

powershell 复制代码 
# 1. 检查脚本路径
Test-Path "F:\OpenClaw_Installed\启动OpenClaw.ps1"

# 2. 手动测试脚本
powershell.exe -ExecutionPolicy Bypass -File "F:\OpenClaw_Installed\启动OpenClaw.ps1"

# 3. 检查执行策略
Get-ExecutionPolicy -List
# 设置为: RemoteSigned 或 Unrestricted

# 4. 重新创建任务
Unregister-ScheduledTask -TaskName "OpenClaw WSL AutoStart" -Confirm:$false
# 然后重新运行创建脚本
问题 7: WSL 发行版名称不正确

错误信息：

复制代码 
WSL distro 'Ubuntu-24.04' not found

解决方案：

powershell 复制代码 
# 1. 列出所有 WSL 发行版
wsl --list --verbose

# 2. 修改启动脚本中的 WSL 发行版名称
# 编辑 F:\OpenClaw_Installed\启动OpenClaw.ps1
# 将 $WSLDistro = "Ubuntu-24.04" 改为实际的名称
问题 8: systemctl 命令失败

错误信息：

复制代码 
System has not been booted with systemd as init system

解决方案：

bash 复制代码 
# 1. 检查 WSL 版本 (必须是 WSL2)
wsl --version

# 2. 确保 systemd 已启用
# 编辑 /etc/wsl.conf
sudo nano /etc/wsl.conf
# 添加:
# [boot]
# systemd=true

# 3. 重启 WSL
# 在 PowerShell 中执行:
wsl --shutdown
wsl -d Ubuntu-24.04

# 4. 验证
systemctl --user status

8.4 性能问题

问题 9: OpenClaw 启动缓慢

诊断：

bash 复制代码 
# 查看启动时间
systemctl --user show openclaw-gateway.service -p ExecMainStartTimestamp

# 查看资源使用
top -p $(pgrep -f openclaw)

优化方案：

bash 复制代码 
# 1. 清理日志
> ~/.openclaw/logs/*.log

# 2. 减少插件数量
openclaw plugin list
# 卸载不需要的插件

# 3. 升级到最新版本
npm update -g openclaw@latest

9. 维护与管理

9.1 日常管理命令

9.1.1 WSL 服务管理
bash 复制代码 
# 查看服务状态
systemctl --user status openclaw-gateway.service

# 启动服务
systemctl --user start openclaw-gateway.service

# 停止服务
systemctl --user stop openclaw-gateway.service

# 重启服务
systemctl --user restart openclaw-gateway.service

# 查看日志
journalctl --user -u openclaw-gateway.service -f

# 查看最近的错误
journalctl --user -u openclaw-gateway.service -p err -n 20
9.1.2 Windows 任务管理
powershell 复制代码 
# 查看任务状态
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 手动启动任务
Start-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 禁用任务
Disable-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 启用任务
Enable-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 删除任务
Unregister-ScheduledTask -TaskName "OpenClaw WSL AutoStart" -Confirm:$false

# 查看任务历史
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"

9.2 更新 OpenClaw

bash 复制代码 
# 更新到最新版本
npm update -g openclaw@latest

# 或使用安装脚本更新
curl -fsSL https://openclaw.ai/install.sh | bash

# 重启服务
systemctl --user restart openclaw-gateway.service

# 验证版本
openclaw --version

9.3 备份与恢复

9.3.1 备份配置
bash 复制代码 
# 创建备份目录
mkdir -p ~/openclaw-backup-$(date +%Y%m%d)

# 备份配置文件
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)/
cp -r ~/.config/systemd/user/openclaw-gateway.service ~/openclaw-backup-$(date +%Y%m%d)/

# 备份 npm 全局包
npm list -g --depth=0 > ~/openclaw-backup-$(date +%Y%m%d)/npm-global-list.txt
9.3.2 恢复配置
bash 复制代码 
# 停止服务
systemctl --user stop openclaw-gateway.service

# 恢复配置
cp -r ~/openclaw-backup-YYYYMMDD/.openclaw ~/
cp ~/openclaw-backup-YYYYMMDD/openclaw-gateway.service ~/.config/systemd/user/

# 重启服务
systemctl --user daemon-reload
systemctl --user start openclaw-gateway.service

9.4 日志管理

9.4.1 查看日志
bash 复制代码 
# OpenClaw 日志
openclaw logs

# systemd 日志
journalctl --user -u openclaw-gateway.service -n 100

# 实时日志
journalctl --user -u openclaw-gateway.service -f

# Windows 启动日志
# 在 PowerShell 中:
notepad $env:USERPROFILE\OpenClaw-Startup.log
9.4.2 清理日志
bash 复制代码 
# 清理旧日志 (保留最近 7 天)
find ~/.openclaw/logs/ -name "*.log" -mtime +7 -delete

# 清空 systemd 日志
journalctl --user --rotate --vacuum-time=7d

9.5 监控与告警

创建简单的监控脚本：~/check-openclaw.sh

bash 复制代码 
#!/bin/bash
# OpenClaw Health Check Script

SERVICE_NAME="openclaw-gateway.service"
PORT=18789
ALERT_EMAIL="your-email@example.com"

# 检查服务状态
if ! systemctl --user is-active --quiet "$SERVICE_NAME"; then
    echo "[$(date)] Service $SERVICE_NAME is not running" >> ~/openclaw-health.log
    systemctl --user start "$SERVICE_NAME"
    # 发送告警邮件 (需要配置 mailx)
    # echo "OpenClaw service was restarted" | mailx -s "OpenClaw Alert" $ALERT_EMAIL
fi

# 检查端口监听
if ! ss -tlnp | grep -q ":$PORT "; then
    echo "[$(date)] Port $PORT is not listening" >> ~/openclaw-health.log
fi

echo "[$(date)] Health check passed" >> ~/openclaw-health.log

添加到 cron：

bash 复制代码 
# 编辑 crontab
crontab -e

# 添加: 每 5 分钟检查一次
*/5 * * * * ~/check-openclaw.sh

10. 卸载指南

10.1 完全卸载 OpenClaw

10.1.1 停止并禁用服务
bash 复制代码 
# 停止 OpenClaw 服务
systemctl --user stop openclaw-gateway.service
systemctl --user disable openclaw-gateway.service

# 停止所有 OpenClaw 进程
pkill -f openclaw
10.1.2 卸载 OpenClaw
bash 复制代码 
# 使用 npm 卸载
npm uninstall -g openclaw

# 或手动删除
rm -rf ~/.npm-global/lib/node_modules/openclaw
rm -f ~/.npm-global/bin/openclaw
10.1.3 删除配置和数据
bash 复制代码 
# 删除配置文件
rm -rf ~/.openclaw
rm -rf ~/.config/systemd/user/openclaw-gateway.service

# 删除数据
rm -rf ~/.local/share/openclaw
rm -rf ~/.local/state/openclaw

# 删除日志
rm -rf /tmp/openclaw
10.1.4 删除 Windows 任务计划程序
powershell 复制代码 
# 在 PowerShell (管理员) 中执行
Unregister-ScheduledTask -TaskName "OpenClaw WSL AutoStart" -Confirm:$false
10.1.5 删除启动脚本
powershell 复制代码 
# 删除脚本文件
Remove-Item F:\OpenClaw_Installed\启动OpenClaw.ps1
Remove-Item F:\OpenClaw_Installed\创建任务计划程序.ps1

# 删除日志
Remove-Item $env:USERPROFILE\OpenClaw-Startup.log

10.2 重新安装

如果需要重新安装：

bash 复制代码 
# 清理 (可选)
npm cache clean --force

# 重新安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 运行配置向导
openclaw onboard --install-daemon

# 重新配置开机自启
# 按照第 6 节的步骤重新配置

附录 A: 快速参考

A.1 常用端口

服务 默认端口 访问地址
OpenClaw Gateway 18789 http://127.0.0.1:18789/
OpenClaw Web UI 18789 http://127.0.0.1:18789/

A.2 重要路径

类型 WSL 路径 Windows 路径
配置文件 ~/.openclaw/ \\wsl$\Ubuntu-24.04\home\user\.openclaw\
日志文件 ~/.local/state/openclaw/logs/ \\wsl$\Ubuntu-24.04\home\user\.local\state\openclaw\logs\
服务文件 ~/.config/systemd/user/ \\wsl$\Ubuntu-24.04\home\user\.config\systemd\user\
启动日志 - %USERPROFILE%\OpenClaw-Startup.log

A.3 命令速查表

bash 复制代码 
# === WSL 命令 ===
# 查看服务状态
systemctl --user status openclaw-gateway.service

# 启动/停止/重启
systemctl --user start|stop|restart openclaw-gateway.service

# 查看 Gateway 状态
openclaw gateway status

# 查看日志
journalctl --user -u openclaw-gateway.service -f

# === PowerShell 命令 ===
# 查看 Windows 任务
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 手动启动任务
Start-ScheduledTask -TaskName "OpenClaw WSL AutoStart"

# 查看启动日志
Get-Content $env:USERPROFILE\OpenClaw-Startup.log -Tail 20

# 重启 WSL
wsl --shutdown
wsl -d Ubuntu-24.04

附录 B: 故障排查流程图

复制代码 
OpenClaw 无法访问
    │
    ├─→ 在 WSL 中测试: curl http://127.0.0.1:18789/
    │   │
    │   ├→ 成功 → 问题在 Windows 层
    │   │   ├─→ 检查 Windows 防火墙
    │   │   ├─→ 配置端口转发 (Windows 10)
    │   │   └─→ 启用镜像网络模式 (Windows 11)
    │   │
    │   └→ 失败 → 问题在 WSL 层
    │       ├─→ 检查服务状态
    │       ├─→ 重启服务
    │       └─→ 检查日志
    │
    ├─→ 检查服务状态
    │   ├─→ inactive (未运行)
    │   │   ├─→ systemctl --user start openclaw-gateway.service
    │   │   └─→ 检查错误日志
    │   │
    │   ├─→ failed (失败)
    │   │   ├─→ journalctl --user -u openclaw-gateway.service -p err
    │   │   └─→ 修复配置后重启
    │   │
    │   └─→ active (运行中)
    │       └─→ 检查端口监听: ss -tlnp | grep 18789
    │
    └─→ 开机未启动
        ├─→ 检查 Windows 任务
        ├─→ 检查 linger 状态
        ├─→ 检查服务是否启用
        └─→ 查看启动日志

附录 C: 安全最佳实践

C.1 访问控制

  • ✅ OpenClaw 默认监听 127.0.0.1，仅本机可访问
  • ✅ 不要修改为 0.0.0.0 暴露到公网
  • ✅ 使用 Windows 防火墙限制访问
  • ✅ 配置 WSL 防火墙 (ufw) 限制入站

C.2 密钥管理

bash 复制代码 
# 使用环境变量管理 API 密钥
cat > ~/.openclaw/.env << EOF
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
EOF

# 设置文件权限
chmod 600 ~/.openclaw/.env

C.3 更新与维护

  • ✅ 定期更新 OpenClaw: npm update -g openclaw@latest
  • ✅ 定期更新系统包: sudo apt update && sudo apt upgrade
  • ✅ 定期审查日志: journalctl --user -u openclaw-gateway.service -p err
  • ✅ 定期备份配置

C.4 日志审计

bash 复制代码 
# 查看最近的认证尝试
journalctl --user -u openclaw-gateway.service -n 1000 | grep -i auth

# 检查异常访问
journalctl --user -u openclaw-gateway.service --since "1 hour ago"

总结

本指南提供了完整的 OpenClaw 在 Windows WSL2 环境中的部署和开机自启动配置方案。

关键要点

  1. 安装：使用官方脚本或 npm 安装 OpenClaw
  2. 网络：WSL2 自动 localhost 转发，Windows 11 无需额外配置
  3. 开机自启 ：
    • WSL 层：systemd 用户服务 + linger
    • Windows 层：任务计划程序
  4. 维护：定期更新、备份和监控

获取帮助

文档维护: 本文档会根据 OpenClaw 版本更新持续维护。如发现问题或有改进建议，欢迎提交 Issue 或 Pull Request。

最后更新 : 2026-03-22
适用版本: OpenClaw 2026.3.13+, Windows 10/11, WSL2, Ubuntu 20.04/22.04/24.04

祝您使用愉快！ 🦞

相关推荐
Rolei_zl1 小时前
AIGC（生成式AI）试用 49 -- AI与软件开发过程4
人工智能·aigc
九天轩辕1 小时前
OpenClaw教程
人工智能
cyyt2 小时前
深度学习周报（3.16~3.22）
人工智能
Yeats_Liao2 小时前
华为开源自研AI框架昇思MindSpore应用案例：WaveNet实现音乐生成
人工智能·深度学习·算法·机器学习·边缘计算
Daydream.V2 小时前
深度学习详解
人工智能·深度学习
twc8292 小时前
RAG核心技术解读
人工智能·深度学习·机器学习
twc8292 小时前
打造专属 MCP Server 测试自动化的私有化解决方案
运维·软件测试·人工智能·自动化·mcp server
如若1232 小时前
WSL2 启动报错“拒绝访问“ E_ACCESSDENIED 完整解决方案
人工智能·pytorch·python·深度学习·计算机视觉
洛阳泰山2 小时前
我用 Java 21 虚拟线程重写了一个 RAG 平台：从架构设计到踩坑实录
java·人工智能·后端
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南08OpenClaw Control UI安全上下文访问配置09UV安装并设置国内源10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）