OpenClaw Launcher

OpenClaw Launcher

Prerequisites

One-click startup for OpenClaw Gateway via Windows desktop shortcut.

Prerequisites

Architecture

Desktop Shortcut (.lnk)
    ↓
\start-openclaw.bat
    ↓
start-openclaw.ps1 (hidden, auto-close)
    ↓
WSL: systemctl start openclaw-gateway + keep-alive sleep
    ↓
Dashboard opens in browser

Path Reference

Important: WSL and Windows paths are different:

| System | Path Example | |--------|--------------| | Windows | C:\Users\\openclaw-scripts\ | | WSL | /mnt/c/Users//openclaw-scripts/ | | WSL home | /home// |

When working in WSL, use /mnt/c/... prefix to access Windows files. When working in PowerShell on Windows, use C:\... paths.

Note on scripts/ directory: The scripts/ folder contains reference templates. When deploying, these are copied to C:\Users\\openclaw-scripts\ with actual usernames substituted. Always use the Python method to generate scripts on the user's machine (see Step 3).

Step-by-Step Workflow

Step 1: Gather System Info

Auto-detect Windows username:

$WindowsUser = $env:USERNAME
Write-Host "Windows user: $WindowsUser"

Get WSL distro name (in Windows CMD or PowerShell):

wsl --list

Get WSL username (in WSL terminal):

whoami

Default shortcut name: Ask user or use "OpenClaw"

Step 2: Create Scripts Directory

In Windows PowerShell (as user, no admin needed):

New-Item -ItemType Directory -Path "C:\Users\\openclaw-scripts" -Force

Or from WSL:

mkdir -p /mnt/c/Users//openclaw-scripts

Step 3: Write Core Script (start-openclaw.ps1)

⚠️ Important: Always write .ps1 files using Python (not bash heredocs) to avoid escaping issues.

Key variables to customize:

Step 3a: Write keep-alive.bat first (required for reliable backgrounding)

content = '@echo off\nstart "" /b cmd /c wsl.exe --distribution Ubuntu --user  -- bash -c "sleep 86400"\n'
with open('/mnt/c/Users//openclaw-scripts/keep-alive.bat', 'w', encoding='ascii') as f:
    f.write(content)

Step 3b: Write start-openclaw.ps1 using Python

lines = [
    '# OpenClaw Gateway Launcher Script (Hidden Mode)',
    '',
    '$wslConfig = cmd /c "wsl.exe --distribution Ubuntu --user  -- cat ~/.openclaw/openclaw.json 2>&1"',
    '$tokenMatch = [regex]::Match($wslConfig, "[a-f0-9]{40}")',
    'if ($tokenMatch.Success) {',
    '    $TOKEN = $tokenMatch.Value',
    '} else {',
    '    Write-Host "[ERROR] Failed to read token from WSL config"',
    '    exit 1',
    '}',
    '$DASHBOARD_URL = "http://localhost:18789/#token=$TOKEN"',
    '',
    '# Get WSL IP',
    '$wslIpRaw = cmd /c "wsl.exe --distribution Ubuntu --user  -- hostname -I 2>&1"',
    '$wslIp = ($wslIpRaw -split " ")[0]',
    '',
    '# Setup port proxy (requires admin)',
    'cmd /c "netsh interface portproxy delete v4tov4 listenport=18789 listenaddress=127.0.0.1 2>nul"',
    'cmd /c "netsh interface portproxy add v4tov4 listenport=18789 listenaddress=127.0.0.1 connectport=18789 connectaddress=$wslIp protocol=tcp 2>nul"',
    '',
    '# Check and start service if needed',
    '$status = cmd /c "wsl.exe --distribution Ubuntu --user  -- systemctl --user is-active openclaw-gateway 2>&1"',
    'if ($status -ne "active") {',
    '    cmd /c "wsl.exe --distribution Ubuntu --user  -- systemctl --user start openclaw-gateway 2>nul"',
    '    Start-Sleep -Seconds 3',
    '}',
    '',
    '# Start keep-alive via pre-created batch file (more reliable than inline Start-Process)',
    'Start-Process -FilePath "cmd.exe" -ArgumentList "/c","C:\\Users\\\\openclaw-scripts\\keep-alive.bat" -WindowStyle Hidden',
    '',
    '# Open Dashboard',
    'start $DASHBOARD_URL',
]
content = '\n'.join(lines)
with open('/mnt/c/Users//openclaw-scripts/start-openclaw.ps1', 'wb') as f:
    f.write(b'\xef\xbb\xbf')  # UTF-8 BOM for PowerShell
    f.write(content.encode('utf-8'))

Step 4: Write Bat Launcher

$batContent = '@echo off
chcp 65001 >nul
powershell -ExecutionPolicy Bypass -WindowStyle Hidden -File "%~dp0start-openclaw.ps1"'
Set-Content -Path "C:\Users\\openclaw-scripts\start-openclaw.bat" -Value $batContent -Encoding ASCII

Note: The .bat must use -ExecutionPolicy Bypass to allow the script to run without prompts.

Step 5: Prepare Icon (Optional)

1. Get PNG image (256x256 or larger) 2. Copy to Windows scripts folder or accessible location 3. Convert to ICO using Python in WSL:

# If PNG is at Windows path (accessible from WSL):
python3 -c "
from PIL import Image
img = Image.open('/mnt/c/Users//Desktop/icon.png')
img = img.resize((256, 256), Image.Resampling.LANCZOS)
img.save('/mnt/c/Users//openclaw-scripts/icon.ico', format='ICO')
"

Step 6: Create Desktop Shortcut

$WshShell = New-Object -ComObject WScript.Shell
$Shortcut = $WshShell.CreateShortcut("C:\Users\\Desktop\.lnk")
$Shortcut.TargetPath = "C:\Users\\openclaw-scripts\start-openclaw.bat"
$Shortcut.WorkingDirectory = "C:\Users\\openclaw-scripts"
$Shortcut.IconLocation = "C:\Users\\openclaw-scripts\icon.ico"
$Shortcut.Save()

Step 7: Test

1. Double-click shortcut 2. Verify: No visible PowerShell window 3. Verify: Browser opens dashboard URL 4. Verify: Gateway is active:

   systemctl --user is-active openclaw-gateway
   

   ps aux | grep "sleep 86400"
   

Step 8: Verify No "Gateway Stopping" Issues

If gateway stops immediately after script runs, check: 1. Is keep-alive process running? (ps aux | grep sleep) 2. If not, the batch file path in Start-Process may be wrong 3. Try running the script with admin privileges for portproxy

Troubleshooting

"Gateway disconnected" / "Gateway stopping" immediately

Keep-alive process not running after script exits

# In start-openclaw.ps1:
Start-Process -FilePath "cmd.exe" -ArgumentList "/c","C:\Users\\openclaw-scripts\keep-alive.bat" -WindowStyle Hidden

@echo off
start "" /b cmd /c wsl.exe --distribution Ubuntu --user  -- bash -c "sleep 86400"

Token extraction fails / $Matches is empty

$wslConfig = cmd /c "wsl.exe --distribution Ubuntu --user  -- cat ~/.openclaw/openclaw.json 2>&1"
$tokenMatch = [regex]::Match($wslConfig, "[a-f0-9]{40}")
if ($tokenMatch.Success) {
    $TOKEN = $tokenMatch.Value
}

PowerShell script parsing errors after editing

content = '''# PowerShell content here
$var = "value"
'''
with open('/mnt/c/Users/.../script.ps1', 'wb') as f:
    f.write(b'\xef\xbb\xbf')  # UTF-8 BOM
    f.write(content.encode('utf-8'))

PowerShell shows "unexpected token" errors

"Script moved or changed" when clicking shortcut

Icon not displaying correctly

Portproxy connection refused

netsh interface portproxy show all

WSL commands fail silently

WSL distro not found

wsl --list --verbose

Debugging script issues from WSL

/mnt/c/Windows/System32/cmd.exe /c "cd /d C:\\Users\\\\openclaw-scripts && powershell -ExecutionPolicy Bypass -File start-openclaw.ps1"

Security Notes

One-click startup for OpenClaw Gateway via Windows desktop shortcut.

"Gateway disconnected" / "Gateway stopping" immediately

Keep-alive process not running after script exits

# In start-openclaw.ps1:
Start-Process -FilePath "cmd.exe" -ArgumentList "/c","C:\Users\\openclaw-scripts\keep-alive.bat" -WindowStyle Hidden

@echo off
start "" /b cmd /c wsl.exe --distribution Ubuntu --user  -- bash -c "sleep 86400"

Token extraction fails / $Matches is empty

$wslConfig = cmd /c "wsl.exe --distribution Ubuntu --user  -- cat ~/.openclaw/openclaw.json 2>&1"
$tokenMatch = [regex]::Match($wslConfig, "[a-f0-9]{40}")
if ($tokenMatch.Success) {
    $TOKEN = $tokenMatch.Value
}

PowerShell script parsing errors after editing

content = '''# PowerShell content here
$var = "value"
'''
with open('/mnt/c/Users/.../script.ps1', 'wb') as f:
    f.write(b'\xef\xbb\xbf')  # UTF-8 BOM
    f.write(content.encode('utf-8'))

PowerShell shows "unexpected token" errors

"Script moved or changed" when clicking shortcut

Icon not displaying correctly

Portproxy connection refused

netsh interface portproxy show all

WSL commands fail silently

WSL distro not found

wsl --list --verbose

Debugging script issues from WSL

/mnt/c/Windows/System32/cmd.exe /c "cd /d C:\\Users\\\\openclaw-scripts && powershell -ExecutionPolicy Bypass -File start-openclaw.ps1"