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

2026-03-24 11:55:19 绝不裸奔001

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. 概述

本指南提供了在 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 中运行
# 检查 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 关键技术点

双层启动机制：
- Windows 层：任务计划程序负责触发
- Linux 层：systemd 负责服务管理
用户级服务 (user-level service)：
- 使用 systemctl --user 而非 sudo systemctl
- 更安全，无需 root 权限
- OpenClaw 安装时自动创建
网络访问：
- WSL2 自动 localhost 转发 (Windows 11 默认)
- 无需额外端口转发配置

4. 第一部分：安装 OpenClaw

4.1 安装 WSL2

4.1.1 启用 WSL

打开 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 (管理员) 中执行：

# 设置 WSL2 为默认版本
wsl --set-default-version 2

4.1.3 安装 Ubuntu

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

打开 Microsoft Store
搜索 “Ubuntu 24.04 LTS” 或 “Ubuntu 22.04 LTS”
点击"获取"或"安装"
等待安装完成

方法 B：使用命令行安装

# 查看可用的 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 终端中执行：

# 更新软件包列表
sudo apt update
# 升级已安装的包
sudo apt upgrade -y
# 安装基础工具
sudo apt install -y curl git build-essential python3 make g++ cmake

4.2.2 验证安装

# 检查 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 (推荐)

# 添加 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 版本：

# 安装 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：使用官方安装脚本 (最简单)

# 在 WSL Ubuntu 中执行
curl -fsSL https://openclaw.ai/install.sh | bash

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

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

4.4.2 方法 B：使用 npm 安装

# 确保使用最新的 npm 版本
npm install -g npm@latest
# 安装 OpenClaw
npm install -g openclaw@latest
# 运行 onboarding 配置向导
openclaw onboard --install-daemon

4.4.3 验证安装

# 检查 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

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

openclaw onboard

按照提示完成：

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

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

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

5.1 检查当前网络配置

# 在 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 (管理员) 中执行：

# 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

删除端口转发规则：

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 中执行
notepad $env:USERPROFILE\.wslconfig

添加以下内容：

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

保存后重启 WSL：

wsl --shutdown
wsl -d Ubuntu-24.04

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

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

6.1 理解自动启动机制

6.1.1 为什么需要双层机制？

WSL2 的特性：
- WSL2 不是传统虚拟机，不会自动启动所有服务
- systemd 用户服务需要触发启动
解决方案：
- WSL 层：使用 systemd 用户服务管理 OpenClaw
- Windows 层：使用任务计划程序在启动时触发

6.1.2 OpenClaw 的服务架构

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

# 查看服务文件
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 中执行：

# 查看服务状态
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，执行：

# 启用开机自启
systemctl --user enable openclaw-gateway.service
# 启动服务
systemctl --user start openclaw-gateway.service
# 验证
systemctl --user status openclaw-gateway.service

6.2.3 配置 linger (保持用户服务运行)

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

# 启用 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

# 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 (普通用户) 中执行：

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 检查日志

# 查看日志文件
notepad $env:USERPROFILE\OpenClaw-Startup.log

6.4 配置 Windows 任务计划程序

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

6.4.1 创建任务配置脚本

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

# 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 运行配置脚本

右键点击 PowerShell
选择 “以管理员身份运行”
执行脚本：

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

按提示操作
选择 Y 立即测试

6.4.3 验证任务创建

# 查看任务状态
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 服务检查

# 在 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 中执行
# 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 网络访问测试

# 在浏览器中访问
# http://127.0.0.1:18789/
# 或使用 curl 测试
curl http://127.0.0.1:18789/

7.2 重启测试 (终极验证)

重启 Windows：

Restart-Computer

等待 40-60 秒 (30 秒延迟 + WSL 启动时间)
检查服务：

# 在 WSL 中
systemctl --user status openclaw-gateway.service

访问 Dashboard：

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

检查日志：

notepad $env:USERPROFILE\OpenClaw-Startup.log

7.3 性能检查

# 检查服务资源使用
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

解决方案：

# 升级 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

解决方案：

# 方案 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

解决方案：

# 安装 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

诊断步骤：

# 1. 在 WSL 中测试
curl http://127.0.0.1:18789/
# 2. 检查端口监听
ss -tlnp | grep 18789
# 3. 检查 Gateway 状态
openclaw gateway status

解决方案：

# 方案 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 未启动

诊断步骤：

# 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

解决方案：

# 方案 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

解决方案：

# 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

解决方案：

# 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

解决方案：

# 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 启动缓慢

诊断：

# 查看启动时间
systemctl --user show openclaw-gateway.service -p ExecMainStartTimestamp
# 查看资源使用
top -p $(pgrep -f openclaw)

优化方案：

# 1. 清理日志
> ~/.openclaw/logs/*.log
# 2. 减少插件数量
openclaw plugin list
# 卸载不需要的插件
# 3. 升级到最新版本
npm update -g openclaw@latest

9. 维护与管理

9.1 日常管理命令

9.1.1 WSL 服务管理

# 查看服务状态
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 任务管理

# 查看任务状态
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

# 更新到最新版本
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 备份配置

# 创建备份目录
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 恢复配置

# 停止服务
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 查看日志

# 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 清理日志

# 清理旧日志 (保留最近 7 天)
find ~/.openclaw/logs/ -name "*.log" -mtime +7 -delete
# 清空 systemd 日志
journalctl --user --rotate --vacuum-time=7d

9.5 监控与告警

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

#!/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：

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

10. 卸载指南

10.1 完全卸载 OpenClaw

10.1.1 停止并禁用服务

# 停止 OpenClaw 服务
systemctl --user stop openclaw-gateway.service
systemctl --user disable openclaw-gateway.service
# 停止所有 OpenClaw 进程
pkill -f openclaw

10.1.2 卸载 OpenClaw

# 使用 npm 卸载
npm uninstall -g openclaw
# 或手动删除
rm -rf ~/.npm-global/lib/node_modules/openclaw
rm -f ~/.npm-global/bin/openclaw

10.1.3 删除配置和数据

# 删除配置文件
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 (管理员) 中执行
Unregister-ScheduledTask -TaskName "OpenClaw WSL AutoStart" -Confirm:$false

10.1.5 删除启动脚本

# 删除脚本文件
Remove-Item F:\OpenClaw_Installed\启动OpenClaw.ps1
Remove-Item F:\OpenClaw_Installed\创建任务计划程序.ps1
# 删除日志
Remove-Item $env:USERPROFILE\OpenClaw-Startup.log

10.2 重新安装

如果需要重新安装：

# 清理 (可选)
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 命令速查表

# === 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 密钥管理

# 使用环境变量管理 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 日志审计

# 查看最近的认证尝试
journalctl --user -u openclaw-gateway.service -n 1000 | grep -i auth
# 检查异常访问
journalctl --user -u openclaw-gateway.service --since "1 hour ago"

总结

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

关键要点

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

获取帮助

官方文档: https://docs.openclaw.ai
GitHub Issues: https://github.com/openclaw/openclaw/issues
社区论坛: https://discord.gg/openclaw

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

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

到此这篇关于OpenClaw从安装到开机自启完整部署指南的文章就介绍到这了,更多相关OpenClaw安装到部署内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！