OpenClaw端口占用排查:Gateway Connection Refused的解决指南

# 检查 Gateway 状态
openclaw gateway status
# 可能的输出：
# ❌ Gateway 未运行
# 或
# ⚠️  Gateway 运行中但端口未监听

# PowerShell - 查看端口 18789 占用情况
netstat -ano | findstr :18789
# 或 PowerShell 5.0+ 方式
Get-NetTCPConnection -LocalPort 18789
# 查看占用进程
Get-Process -Id (Get-NetTCPConnection -LocalPort 18789).OwningProcess

# 查找 OpenClaw/Cladbot 相关进程
Get-Process | Where-Object {$_.ProcessName -match "openclaw|cladbot|node"}
# 查找端口监听
netstat -ano | findstr LISTENING | findstr 18789

# 1. 查找占用进程
netstat -ano | findstr :18789
# 输出: TCP    127.0.0.1:18789    0.0.0.0:0    LISTENING    12345
#                                                      ↑ PID
# 2. 结束进程
taskkill /PID 12345 /F
# 或 PowerShell 方式
Stop-Process -Id 12345 -Force

# 1. 清理环境变量
[Environment]::SetEnvironmentVariable("CLADBOT_HOME", $null, "User")
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", $null, "User")
# 2. 清理旧配置（谨慎操作！）
# 备份后删除 Cladbot 配置
Rename-Item -Path "$env:USERPROFILE\.cladbot" -NewName "$env:USERPROFILE\.cladbot.backup"
# 3. 重新初始化 OpenClaw
openclaw onboard

# 以管理员身份运行 PowerShell，然后
openclaw gateway restart
# 或修改端口为高位端口（不需要管理员权限）
# 在 openclaw.json 中:
{
  "gateway": {
    "port": 58789  # ← 改为高位端口
  }
}

# 1. 检查防火墙规则
Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*node*" -or $_.DisplayName -like "*openclaw*"}
# 2. 添加入站规则（管理员权限）
New-NetFirewallRule -DisplayName "OpenClaw Gateway" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

# 1. 停止所有相关进程
taskkill /F /IM node.exe 2>$null
# 2. 清理端口
$port = 18789
$process = Get-NetTCPConnection -LocalPort $port -ErrorAction SilentlyContinue
if ($process) {
    Stop-Process -Id $process.OwningProcess -Force
    Write-Host "已结束占用端口 $port 的进程"
}
# 3. 重启 Gateway
openclaw gateway restart
# 4. 验证
openclaw gateway status

# 1. 停止服务
openclaw gateway stop
# 2. 备份配置
Copy-Item -Path "$env:USERPROFILE\.openclaw" -Destination "$env:USERPROFILE\.openclaw.backup.$(Get-Date -Format 'yyyyMMdd')" -Recurse
# 3. 清理所有 Node 进程
Get-Process node -ErrorAction SilentlyContinue | Stop-Process -Force
# 4. 重新安装
npm uninstall -g openclaw
npm install -g openclaw
# 5. 重新配置
openclaw onboard

// ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 58789,
    "host": "127.0.0.1"
  }
}

openclaw gateway restart
# 访问: http://127.0.0.1:58789/__openclaw__/canvas/

# 应该看到 LISTENING 状态
netstat -ano | findstr :18789
# TCP    127.0.0.1:18789    0.0.0.0:0    LISTENING    [PID]

# 测试 HTTP 响应
Invoke-RestMethod -Uri "http://127.0.0.1:18789/__openclaw__/canvas/" -Method GET
# 或使用 curl
curl http://127.0.0.1:18789/__openclaw__/canvas/

# 创建启动脚本 check-and-start.ps1
$port = 18789
# 检查端口
$existing = Get-NetTCPConnection -LocalPort $port -ErrorAction SilentlyContinue
if ($existing) {
    Write-Host "⚠️  端口 $port 被占用，尝试释放..."
    Stop-Process -Id $existing.OwningProcess -Force
    Start-Sleep -Seconds 2
}
# 启动 Gateway
openclaw gateway start

# 使用 nssm 创建 Windows 服务
nssm install OpenClawGateway "C:\Program Files\nodejs\node.exe"
nssm set OpenClawGateway AppDirectory "$env:USERPROFILE"
nssm set OpenClawGateway AppParameters "openclaw gateway start"
nssm set OpenClawGateway DisplayName "OpenClaw Gateway"
nssm start OpenClawGateway

# monitor.ps1
while ($true) {
    try {
        $response = Invoke-RestMethod -Uri "http://127.0.0.1:18789/health" -TimeoutSec 5
        Write-Host "$(Get-Date) ✅ Gateway 运行正常"
    } catch {
        Write-Host "$(Get-Date) ❌ Gateway 无响应，尝试重启..."
        openclaw gateway restart
    }
    Start-Sleep -Seconds 60
}