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

作者：CSDN博客
问题现象

用户在 Windows 11 上全新安装 OpenClaw 后，完成 onboarding 流程，但在启动 Gateway 时遇到 连接被拒绝 错误：
ERR_CONNECTION_REFUSED
http://127.0.0.1:18789/__openclaw__/canvas/
环境信息：

OS: Windows 11OpenClaw: latestNode.js: latest特殊情况：之前安装过 Cladbot

诊断过程

1. 确认 Gateway 状态

# 检查 Gateway 状态
openclaw gateway status

# 可能的输出：
# ❌ Gateway 未运行
# 或
# ⚠️  Gateway 运行中但端口未监听
2. 检查端口占用

# PowerShell - 查看端口 18789 占用情况
netstat -ano | findstr :18789

# 或 PowerShell 5.0+ 方式
Get-NetTCPConnection -LocalPort 18789

# 查看占用进程
Get-Process -Id (Get-NetTCPConnection -LocalPort 18789).OwningProcess
3. 检查残留进程

由于用户之前安装过 Cladbot，可能存在冲突：
# 查找 OpenClaw/Cladbot 相关进程
Get-Process | Where-Object {$_.ProcessName -match "openclaw|cladbot|node"}

# 查找端口监听
netstat -ano | findstr LISTENING | findstr 18789
常见原因

原因 1：端口被占用

症状: Gateway 启动后立即退出
日志: Error: listen EADDRINUSE: address already in use :::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
原因 2：残留配置冲突

Cladbot 和 OpenClaw 可能使用相同的配置目录或环境变量。
解决方案：
# 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
原因 3：权限问题

Windows 可能需要管理员权限绑定端口。
解决方案：
# 以管理员身份运行 PowerShell，然后
openclaw gateway restart

# 或修改端口为高位端口（不需要管理员权限）
# 在 openclaw.json 中:
{
  "gateway": {
    "port": 58789  # ← 改为高位端口
  }
}
原因 4：防火墙/安全软件

Windows Defender 或其他安全软件可能阻止了 Node.js 的网络访问。
解决方案：
# 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. 检查 Gateway 状态
   └─ openclaw gateway status

2. 检查端口占用
   └─ netstat -ano | findstr :18789

3. 检查残留进程
   └─ Get-Process | ?{$_.Name -match "node|openclaw"}

4. 检查日志
   └─ Get-Content ~/.openclaw/logs/gateway.log -Tail 50

5. 尝试手动启动
   └─ openclaw gateway start --verbose

6. 检查防火墙
   └─ Get-NetFirewallRule | ?{$_.DisplayName -like "*openclaw*"}
解决方案汇总

方案 A：快速修复（推荐先尝试）

# 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
方案 B：完全重置

# 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
方案 C：更换端口

如果 18789 端口持续被占用：
// ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 58789,
    "host": "127.0.0.1"
  }
}
然后：
openclaw gateway restart
# 访问: http://127.0.0.1:58789/__openclaw__/canvas/
验证步骤

1. 端口监听验证

# 应该看到 LISTENING 状态
netstat -ano | findstr :18789
# TCP    127.0.0.1:18789    0.0.0.0:0    LISTENING    [PID]
2. 服务响应验证

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

# 或使用 curl
curl http://127.0.0.1:18789/__openclaw__/canvas/
3. 浏览器访问

打开浏览器访问：

http://127.0.0.1:18789/__openclaw__/canvas/应该看到 OpenClaw Web UI

预防措施

1. 使用固定端口前检查

# 创建启动脚本 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
2. 配置 Systemd/Windows Service

# 使用 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
3. 监控脚本

# 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
}
Windows 环境特殊注意事项

问题	解决方案
路径过长	使用 `\\?\` 前缀或缩短路径
权限不足	以管理员身份运行 PowerShell
杀毒软件拦截	将 OpenClaw 目录加入白名单
WSL 冲突	检查 WSL 是否占用了相同端口
快速启动	禁用 Windows 快速启动功能

总结

问题类型	快速解决
端口被占用	`taskkill /PID [PID] /F`
残留进程	`taskkill /F /IM node.exe`
配置冲突	备份后删除 `.openclaw` 重新配置
权限问题	以管理员身份运行
防火墙	添加入站规则允许 18789 端口

---

原文地址：https://blog.csdn.net/u011664969/article/details/158182518