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

目录

• OpenClaw 完整部署指南：Windows WSL2 环境安装与开机自启动配置
• 1. 概述
• 1.1 为什么选择 WSL2 部署？
• 2. 系统要求
• 2.1 硬件要求
• 2.2 软件要求
• 2.3 检查系统环境
• 3. 架构说明
• 3.1 整体架构图
• 3.2 启动流程详解
• 3.3 关键技术点
• 4. 第一部分：安装 OpenClaw
• 4.1 安装 WSL2
• 4.2 配置 WSL2 Ubuntu
• 4.3 安装 Node.js
• 4.4 安装 OpenClaw
• 5. 第二部分：配置网络访问
• 5.1 检查当前网络配置
• 5.2 从 Windows 访问
• 5.3 WSL2 网络模式说明
• 5.4 手动配置端口转发 (Windows 10)
• 5.5 配置镜像网络模式 (高级，Windows 11 22H2+)
• 6. 第三部分：配置开机自启动
• 6.1 理解自动启动机制
• 6.2 配置 WSL 层服务
• 6.3 创建 Windows 启动脚本
• 6.4 配置 Windows 任务计划程序
• 7. 验证与测试
• 7.1 完整验证清单
• 7.2 重启测试 (终极验证)
• 7.3 性能检查
• 8. 常见问题排查
• 8.1 OpenClaw 安装问题
• 8.2 网络访问问题
• 8.3 开机自启问题
• 8.4 性能问题
• 9. 维护与管理
• 9.1 日常管理命令
• 9.2 更新 OpenClaw
• 9.3 备份与恢复
• 9.4 日志管理
• 9.5 监控与告警
• 10. 卸载指南
• 10.1 完全卸载 OpenClaw
• 10.2 重新安装
• 附录 A: 快速参考
• A.1 常用端口
• A.2 重要路径
• A.3 命令速查表
• 附录 B: 故障排查流程图
• 附录 C: 安全最佳实践
• C.1 访问控制
• C.2 密钥管理
• C.3 更新与维护
• C.4 日志审计
• 总结
• 关键要点
• 获取帮助

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

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

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

优势：

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

适用场景：

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

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

• 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 内置)

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

# 在 PowerShell 中运行
# 检查 Windows 版本
winver
# 检查 WSL 版本
wsl --version
# 检查 WSL 状态
wsl --status

┌─────────────────────────────────────────────────────────────┐
│                         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│
              └─────────────────┘

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

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

打开 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

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

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

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

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

方法 B：使用命令行安装

# 查看可用的 Linux 发行版
wsl --list --online
# 安装 Ubuntu 24.04
wsl --install -d Ubuntu-24.04
# 安装完成后会提示重启

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

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: ******

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

在 WSL Ubuntu 终端中执行：

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

# 检查 Ubuntu 版本
lsb_release -a
# 检查 WSL 版本
wsl --version

预期输出示例：

Distributor ID: Ubuntu
Description:    Ubuntu 24.04 LTS
Release:        24.04
Codename:       noble

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

# 添加 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

如果需要管理多个 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

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

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

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

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

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

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

openclaw onboard

按照提示完成：

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

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

# 在 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

打开 Windows 浏览器，访问：

http://127.0.0.1:18789/

或

http://localhost:18789/

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

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

Windows 10 或旧版本：

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

如果自动转发不工作，在 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"

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

# 在 PowerShell 中执行
notepad $env:USERPROFILE.wslconfig

添加以下内容：

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

保存后重启 WSL：

wsl --shutdown
wsl -d Ubuntu-24.04

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

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

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

# 查看服务文件
ls ~/.config/systemd/user/openclaw-gateway.service
# 查看服务状态
systemctl --user status openclaw-gateway.service

关键点：

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

在 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)

如果服务显示 disabled，执行：

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

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

# 启用 linger
loginctl enable-linger $(whoami)

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

输出应该是：

Linger=yes

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

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

在 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:USERPROFILEOpenClaw-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
}

在 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/

# 查看日志文件
notepad $env:USERPROFILEOpenClaw-Startup.log

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

创建文件：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:USERPROFILEOpenClaw-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:USERPROFILEOpenClaw-Startup.log) {
        Write-Host ""
        Write-Host "Recent log entries:" -ForegroundColor Cyan
        Get-Content $env:USERPROFILEOpenClaw-Startup.log -Tail 15
    }
    Write-Host ""
    Write-Host "Test completed!" -ForegroundColor Green
}
Write-Host ""
$null = Read-Host "Press Enter to exit"

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

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

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

# 查看任务状态
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"
# 查看详细信息
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"

预期输出：

Name                          State
----                          -----
OpenClaw WSL AutoStart        Ready

# 在 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

# 在 PowerShell 中执行
# 1. 查看任务状态
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"
# 2. 查看任务历史
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"
# 3. 查看日志文件
Get-Content $env:USERPROFILEOpenClaw-Startup.log -Tail 20

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

• 重启 Windows：

Restart-Computer

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

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

• 访问 Dashboard：

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

• 检查日志：

notepad $env:USERPROFILEOpenClaw-Startup.log

# 检查服务资源使用
systemctl --user show openclaw-gateway.service -p CPUUsage,MemoryCurrent
# 查看进程
ps aux | grep openclaw
# 检查端口监听
ss -tlnp | grep 18789

错误信息：

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

错误信息：

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

错误信息：

sharp: Installation failed

解决方案：

# 安装 sharp 依赖
sudo apt-get install -y libvips-dev
# 或忽略全局 libvips
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

症状：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

诊断步骤：

# 1. 检查任务是否运行
Get-ScheduledTask -TaskName "OpenClaw WSL AutoStart"
# 2. 查看任务历史
Get-ScheduledTaskInfo -TaskName "OpenClaw WSL AutoStart"
# 3. 查看日志
Get-Content $env:USERPROFILEOpenClaw-Startup.log -Tail 50
# 4. 手动运行测试
Start-ScheduledTask -TaskName "OpenClaw WSL AutoStart"
Start-Sleep -Seconds 10
Get-Content $env:USERPROFILEOpenClaw-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'

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

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
# 然后重新运行创建脚本

错误信息：

WSL distro 'Ubuntu-24.04' not found

解决方案：

# 1. 列出所有 WSL 发行版
wsl --list --verbose
# 2. 修改启动脚本中的 WSL 发行版名称
# 编辑 F:OpenClaw_Installed启动OpenClaw.ps1
# 将 $WSLDistro = "Ubuntu-24.04" 改为实际的名称

错误信息：

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

诊断：

# 查看启动时间
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

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

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

# 更新到最新版本
npm update -g openclaw@latest
# 或使用安装脚本更新
curl -fsSL https://openclaw.ai/install.sh | bash
# 重启服务
systemctl --user restart openclaw-gateway.service
# 验证版本
openclaw --version

# 创建备份目录
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

# 停止服务
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

# OpenClaw 日志
openclaw logs
# systemd 日志
journalctl --user -u openclaw-gateway.service -n 100
# 实时日志
journalctl --user -u openclaw-gateway.service -f
# Windows 启动日志
# 在 PowerShell 中:
notepad $env:USERPROFILEOpenClaw-Startup.log

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

创建简单的监控脚本：~/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

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

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

# 删除配置文件
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

# 在 PowerShell (管理员) 中执行
Unregister-ScheduledTask -TaskName "OpenClaw WSL AutoStart" -Confirm:$false

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

如果需要重新安装：

# 清理 (可选)
npm cache clean --force
# 重新安装
curl -fsSL https://openclaw.ai/install.sh | bash
# 运行配置向导
openclaw onboard --install-daemon
# 重新配置开机自启
# 按照第 6 节的步骤重新配置

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

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

# === 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:USERPROFILEOpenClaw-Startup.log -Tail 20
# 重启 WSL
wsl --shutdown
wsl -d Ubuntu-24.04

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 状态
        ├─→ 检查服务是否启用
        └─→ 查看启动日志

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

# 使用环境变量管理 API 密钥
cat > ~/.openclaw/.env << EOF
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
EOF
# 设置文件权限
chmod 600 ~/.openclaw/.env

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

# 查看最近的认证尝试
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. 维护：定期更新、备份和监控

• 官方文档: 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安装到部署内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！