OpenClaw Gateway Fixer

Diagnose and repair OpenClaw gateway startup failures on Windows, focusing on the
Chinese username encoding bug and port availability issues.

When to Use

Chinese users:
- OpenClaw web UI (default http://127.0.0.1:18789) returns connection refused or timeout
- OpenClaw web UI asks for gateway token but token is correct
- gateway.cmd exists but double-clicking does nothing (silent failure)
- After system update or reinstall, OpenClaw stops working
- Port 18789 is not in LISTENING state

English users: See references/trigger-phrases-en.md for English trigger phrases.
Typical English triggers: "OpenClaw won't load", "gateway timeout", "OpenClaw stopped working after update", "port 18789 not responding".

Diagnostic Flow

Step 1: Check Gateway Process

Run PowerShell:

netstat -ano | findstr ":18789"
Get-Process -Name node -ErrorAction SilentlyContinue | Where-Object {$_.Id -eq (netstat -ano | Select-String ":18789.*LISTENING" | ForEach-Object {$_.ToString().Split(' ')[-1].Trim()}) } | Select-Object Id, WorkingSet

If port 18789 is NOT in LISTENING state → gateway is not running. Proceed to Step 2.

Step 2: Check gateway.cmd Encoding

Read C:\Users\<username>\.openclaw\gateway.cmd and check for:
- Garbled Chinese characters (e.g., 鍚存竻鑳絓 instead of 吴清能)
- Missing backslash before AppData in TMPDIR path
- Wrong node.js path

Chinese Windows usernames are prone to UTF-8/GBK encoding mismatch in gateway.cmd.

Step 3: Check openclaw.json Workspace Path

Read C:\Users\<username>\.openclaw\openclaw.json. The agents.defaults.workspace
field may also contain garbled Chinese characters. The file itself may be OK when
read via PowerShell Get-Content -Encoding UTF8, but gateway.cmd is the
primary failure point.

Step 4: Check Port Availability

netstat -ano | findstr ":18789"

If another process occupies port 18789, either kill it or change the port in
openclaw.json (gateway.port) and gateway.cmd.

Fix Procedures

Fix A: Repair gateway.cmd (Most Common Fix)

1. Backup existing file:
   powershell Copy-Item "C:\Users\<username>\.openclaw\gateway.cmd" "C:\Users\<username>\.openclaw\gateway.cmd.bak" -Force

2. Rewrite with correct encoding (GBK/CodePage 936) using the template in
   scripts/fix-gateway-cmd.ps1 — run that script directly.

3. Verify the fix:
   powershell Get-Content "C:\Users\<username>\.openclaw\gateway.cmd" -Encoding Default
   Chinese characters must display correctly.

Fix B: Start Gateway Manually (Bypass gateway.cmd)

If gateway.cmd is broken, start gateway directly:

Start-Process -FilePath "node" -ArgumentList '"C:\Users\<username>\AppData\Roaming\npm\node_modules\openclaw\dist\index.js" gateway --port 18789' -WindowStyle Hidden

Wait 5-10 seconds, then verify:

netstat -ano | findstr ":18789"
Invoke-WebRequest -Uri "http://127.0.0.1:18789/" -TimeoutSec 5

Fix C: Create Silent Startup Script

Use scripts/create-silent-startup.ps1 to generate start-gateway-silent.vbs
which runs gateway without a visible CMD window. This VBS file is then used by
Windows Task Scheduler for auto-start.

Fix D: Setup Auto-Start via Task Scheduler

Use scripts/setup-autostart.ps1 to create a Windows scheduled task that:
- Triggers at user logon
- Delays 15 seconds (wait for system ready)
- Runs silently via wscript.exe (no CMD window)
- Restarts on failure (up to 3 retries)

To remove auto-start:

schtasks /delete /tn "OpenClaw Gateway" /f

Web UI Access

After gateway is running, access the web UI at:

http://127.0.0.1:18789/?token=<gateway-token>

The token is in C:\Users\<username>\.openclaw\openclaw.json under
gateway.auth.token.

If the page shows "gateway token missing", use the URL with ?token=... appended,
or paste the token into the "网关令牌" field manually.

Scripts Reference

Notes

• The root cause is OpenClaw's gateway.cmd generator not handling multi-byte
  Chinese characters correctly — the UTF-8 bytes get interpreted as GBK,
  producing garbled text like 鍚存竻鑳絓.
• Always backup gateway.cmd before overwriting.
• The fix must be reapplied after OpenClaw updates that regenerate gateway.cmd.
• Node.js path may vary: check D:\Program Files\nodejs\node.exe or where.exe node.