name: gateway-token-doctor description: Diagnose and fix gateway token mismatches causing 401 errors. Align tokens across config, service, and CLI surfaces.

Gateway Token Doctor

Diagnose and fix 401 errors from token mismatches.

Problem

Gateway token inconsistencies cause:

• 401 Unauthorized errors
• CLI/UI authentication failures
• Service startup failures
• Silent auth degradation

Workflow

1. Token Audit

# Check all token surfaces
$cfg = Get-Content "$HOME/.openclaw/openclaw.json" -Raw | ConvertFrom-Json
$auth = $cfg.gateway.auth.token
$remote = $cfg.gateway.remote.token
$service = $env:OPENCLAW_GATEWAY_TOKEN

"auth.token   = $auth"
"remote.token = $remote"
"service.token = $service"

if ($auth -and $remote -and $auth -ne $remote) {
    Write-Warning "Token mismatch: auth != remote"
}

2. Alignment Fix

# Generate or use existing token
$token = $auth

# Update config
$cfg.gateway.auth.token = $token
$cfg.gateway.remote.token = $token
$cfg | ConvertTo-Json -Depth 10 | Out-File "$HOME/.openclaw/openclaw.json" -Encoding UTF8

# Update service startup script
$servicePath = "$HOME/.openclaw/gateway.cmd"
$content = Get-Content $servicePath -Raw
$content = $content -replace 'OPENCLAW_GATEWAY_TOKEN=.*', "OPENCLAW_GATEWAY_TOKEN=$token"
$content | Out-File $servicePath -Encoding UTF8

# Restart
openclaw gateway restart

3. Verification

# Test gateway access
openclaw gateway status

# Test CLI auth
openclaw whoami

Executable Completion Criteria

Privacy/Safety

• Never log actual token values
• Redact tokens in output (show first 4 chars only)
• Store tokens only in config files

Self-Use Trigger

Use when:

• 401 errors appear
• Gateway restart after config change
• CLI shows auth mismatch
• Service fails to start

Align tokens. Restore access.