OpenClaw Launcher#

Prerequisites#

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

Prerequisites#

• WSL2 with Ubuntu (or other distro)
• OpenClaw Gateway installed in WSL as systemd user service
• Windows PowerShell or PowerShell 7
• Python with PIL/Pillow (for icon conversion)

Architecture#

text

Desktop Shortcut (.lnk)
    ↓
<USER_SCRIPTS_DIR>\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:

SystemPath ExampleWindowsC:\Users\<WINDOWS_USER>\openclaw-scripts\WSL/mnt/c/Users/<WINDOWS_USER>/openclaw-scripts/WSL home/home/<WSL_USER>/

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\<WINDOWS_USER>\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:

powershell

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

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

cmd

wsl --list

Get WSL username (in WSL terminal):

bash

whoami

Default shortcut name: Ask user or use "OpenClaw"

Step 2: Create Scripts Directory#

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

powershell

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

Replace <WINDOWS_USER> with actual Windows username, or use $env:USERNAME.

Or from WSL:

bash

mkdir -p /mnt/c/Users/<WINDOWS_USER>/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:

• $WslDistro: WSL distro name (e.g., "Ubuntu")
• $WslUser: WSL username (from whoami)

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

python

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

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

python

lines = [
    '# OpenClaw Gateway Launcher Script (Hidden Mode)',
    '',
    '$wslConfig = cmd /c "wsl.exe --distribution Ubuntu --user <WSL_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 <WSL_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 <WSL_USER> -- systemctl --user is-active openclaw-gateway 2>&1"',
    'if ($status -ne "active") {',
    '    cmd /c "wsl.exe --distribution Ubuntu --user <WSL_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\\<WINDOWS_USER>\\openclaw-scripts\\keep-alive.bat" -WindowStyle Hidden',
    '',
    '# Open Dashboard',
    'start $DASHBOARD_URL',
]

content = '\n'.join(lines)
with open('/mnt/c/Users/<WINDOWS_USER>/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#

powershell

$batContent = '@echo off
chcp 65001 >nul
powershell -ExecutionPolicy Bypass -WindowStyle Hidden -File "%~dp0start-openclaw.ps1"'

Set-Content -Path "C:\Users\<WINDOWS_USER>\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:

bash

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

Step 6: Create Desktop Shortcut#

powershell

$WshShell = New-Object -ComObject WScript.Shell
$Shortcut = $WshShell.CreateShortcut("C:\Users\<WINDOWS_USER>\Desktop\<SHORTCUT_NAME>.lnk")
$Shortcut.TargetPath = "C:\Users\<WINDOWS_USER>\openclaw-scripts\start-openclaw.bat"
$Shortcut.WorkingDirectory = "C:\Users\<WINDOWS_USER>\openclaw-scripts"
$Shortcut.IconLocation = "C:\Users\<WINDOWS_USER>\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: bash

   systemctl --user is-active openclaw-gateway
   
   

5. Verify: Keep-alive process running (in WSL): bash

   ps aux | grep "sleep 86400"
   
   

   Should show a sleep 86400 process owned by your user.

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#

Cause: Keep-alive process dies when PowerShell exits Fix: Use a pre-created batch file for keep-alive, not inline Start-Process. See Step 3 script template.

Keep-alive process not running after script exits#

Cause: Start-Process -WindowStyle Hidden creates a process that dies when PowerShell exits Fix: The keep-alive must be a separate .bat file started via cmd /c:

powershell

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

And pre-create keep-alive.bat:

bat

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

Token extraction fails / $Matches is empty#

Cause: Two issues:

1. Regex matches "mode": "token" before actual token field
2. $Matches doesn't populate correctly after cmd /c calls Fix: Use [regex]::Match() with 40-char hex pattern:

powershell

$wslConfig = cmd /c "wsl.exe --distribution Ubuntu --user <WSL_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#

Cause: Bash/WSL heredoc escaping corrupts PowerShell syntax (especially backticks \s, $, etc.) Fix: Write PowerShell files using Python, not bash heredocs:

python

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#

Cause: File encoding issues or special characters not handled Fix: Always write PowerShell scripts with UTF-8 BOM encoding ( -Encoding UTF8 in PowerShell, or b'\xef\xbb\xbf' in Python)

"Script moved or changed" when clicking shortcut#

Cause: Shortcut points to WSL UNC path ( \\wsl$\...) Fix: Scripts must be in Windows-native path ( C:\Users\...\openclaw-scripts\)

Icon not displaying correctly#

Cause: Shortcut references .png instead of .ico, or wrong path Fix: Convert PNG to ICO, verify IconLocation path exists

Portproxy connection refused#

Cause: Gateway only listens on 127.0.0.1, or portproxy not set up Fix:

1. Run script as Administrator (portproxy requires admin)
2. Or manually verify:

cmd

netsh interface portproxy show all

WSL commands fail silently#

Cause: PowerShell & operator doesn't handle spaces well Fix: Always use cmd /c "wsl.exe ..." pattern

WSL distro not found#

Cause: Distro name spelling is wrong Fix: List all distros:

cmd

wsl --list --verbose

Debugging script issues from WSL#

When troubleshooting PowerShell scripts, run directly via:

bash

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

Security Notes#

• Token is read dynamically from WSL config at runtime
• Never hardcode tokens or credentials
• Keep scripts in user-private directory
• Portproxy only exposes local loopback