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

目录

• 问题现象
• 诊断过程
• 1. 确认 Gateway 状态
• 2. 检查端口占用
• 3. 检查残留进程
• 常见原因
• 原因 1：端口被占用
• 原因 2：残留配置冲突
• 原因 3：权限问题
• 原因 4：防火墙/安全软件
• 完整排查流程
• 解决方案汇总
• 方案 A：快速修复（推荐先尝试）
• 方案 B：完全重置
• 方案 C：更换端口
• 验证步骤
• 1. 端口监听验证
• 2. 服务响应验证
• 3. 浏览器访问
• 预防措施
• 1. 使用固定端口前检查
• 2. 配置 Systemd/Windows Service
• 3. 监控脚本
• Windows 环境特殊注意事项
• 总结

用户在 Windows 11 上全新安装 OpenClaw 后，完成 onboarding 流程，但在启动 Gateway 时遇到 连接被拒绝 错误：

ERR_CONNECTION_REFUSED
http://127.0.0.1:18789/__openclaw__/canvas/

环境信息：

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

# 检查 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

由于用户之前安装过 Cladbot，可能存在冲突：

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

症状: 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

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

Windows 可能需要管理员权限绑定端口。

解决方案：

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

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*"}

# 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

如果 18789 端口持续被占用：

// ~/.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/

打开浏览器访问：

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

# 创建启动脚本 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 Filesnodejsnode.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
}

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

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

到此这篇关于OpenClaw端口占用排查:Gateway Connection Refused的解决指南的文章就介绍到这了,更多相关OpenClaw端口占用排查内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！