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

發(fā)布時(shí)間：2026-03-17 15:21:17 作者：硬核-秦

我要評(píng)論

用戶(hù)在 Windows 11 上全新安裝 OpenClaw 后，完成 onboarding 流程，但在啟動(dòng) Gateway 時(shí)遇到連接被拒絕錯(cuò)誤，下面小編就和大家詳細(xì)介紹一下如何排查并解決吧

問(wèn)題現(xiàn)象

用戶(hù)在 Windows 11 上全新安裝 OpenClaw 后，完成 onboarding 流程，但在啟動(dòng) Gateway 時(shí)遇到 連接被拒絕 錯(cuò)誤：

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

環(huán)境信息：

OS: Windows 11
OpenClaw: latest
Node.js: latest
特殊情況：之前安裝過(guò) Cladbot

診斷過(guò)程

1. 確認(rèn) Gateway 狀態(tài)

# 檢查 Gateway 狀態(tài)
openclaw gateway status
# 可能的輸出：
# ? Gateway 未運(yùn)行
# 或
# ??  Gateway 運(yùn)行中但端口未監(jiān)聽(tīng)

2. 檢查端口占用

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

3. 檢查殘留進(jìn)程

由于用戶(hù)之前安裝過(guò) Cladbot，可能存在沖突：

# 查找 OpenClaw/Cladbot 相關(guān)進(jìn)程
Get-Process | Where-Object {$_.ProcessName -match "openclaw|cladbot|node"}
# 查找端口監(jiān)聽(tīng)
netstat -ano | findstr LISTENING | findstr 18789

常見(jiàn)原因

原因 1：端口被占用

癥狀: Gateway 啟動(dòng)后立即退出

日志: Error: listen EADDRINUSE: address already in use :::18789

解決方案：

# 1. 查找占用進(jìn)程
netstat -ano | findstr :18789
# 輸出: TCP    127.0.0.1:18789    0.0.0.0:0    LISTENING    12345
#                                                      ↑ PID
# 2. 結(jié)束進(jìn)程
taskkill /PID 12345 /F
# 或 PowerShell 方式
Stop-Process -Id 12345 -Force

原因 2：殘留配置沖突

Cladbot 和 OpenClaw 可能使用相同的配置目錄或環(huán)境變量。

解決方案：

# 1. 清理環(huán)境變量
[Environment]::SetEnvironmentVariable("CLADBOT_HOME", $null, "User")
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", $null, "User")
# 2. 清理舊配置（謹(jǐn)慎操作?。?
# 備份后刪除 Cladbot 配置
Rename-Item -Path "$env:USERPROFILE\.cladbot" -NewName "$env:USERPROFILE\.cladbot.backup"
# 3. 重新初始化 OpenClaw
openclaw onboard

原因 3：權(quán)限問(wèn)題

Windows 可能需要管理員權(quán)限綁定端口。

解決方案：

# 以管理員身份運(yùn)行 PowerShell，然后
openclaw gateway restart
# 或修改端口為高位端口（不需要管理員權(quán)限）
# 在 openclaw.json 中:
{
  "gateway": {
    "port": 58789  # ← 改為高位端口
  }
}

原因 4：防火墻/安全軟件

Windows Defender 或其他安全軟件可能阻止了 Node.js 的網(wǎng)絡(luò)訪問(wèn)。

解決方案：

# 1. 檢查防火墻規(guī)則
Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*node*" -or $_.DisplayName -like "*openclaw*"}
# 2. 添加入站規(guī)則（管理員權(quán)限）
New-NetFirewallRule -DisplayName "OpenClaw Gateway" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

完整排查流程

1. 檢查 Gateway 狀態(tài)

openclaw gateway status

2. 檢查端口占用

netstat -ano | findstr :18789

3. 檢查殘留進(jìn)程

Get-Process | ?{$_.Name -match "node|openclaw"}

4. 檢查日志

Get-Content ~/.openclaw/logs/gateway.log -Tail 50

5. 嘗試手動(dòng)啟動(dòng)

openclaw gateway start --verbose

6. 檢查防火墻

Get-NetFirewallRule | ?{$_.DisplayName -like "*openclaw*"}

解決方案匯總

方案 A：快速修復(fù)（推薦先嘗試）

# 1. 停止所有相關(guān)進(jìn)程
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 "已結(jié)束占用端口 $port 的進(jìn)程"
}
# 3. 重啟 Gateway
openclaw gateway restart
# 4. 驗(yàn)證
openclaw gateway status

方案 B：完全重置

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

方案 C：更換端口

如果 18789 端口持續(xù)被占用：

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

然后：

openclaw gateway restart
# 訪問(wèn): http://127.0.0.1:58789/__openclaw__/canvas/

驗(yàn)證步驟

1. 端口監(jiān)聽(tīng)驗(yàn)證

# 應(yīng)該看到 LISTENING 狀態(tài)
netstat -ano | findstr :18789
# TCP    127.0.0.1:18789    0.0.0.0:0    LISTENING    [PID]

2. 服務(wù)響應(yīng)驗(yàn)證

# 測(cè)試 HTTP 響應(yīng)
Invoke-RestMethod -Uri "http://127.0.0.1:18789/__openclaw__/canvas/" -Method GET
# 或使用 curl
curl http://127.0.0.1:18789/__openclaw__/canvas/

3. 瀏覽器訪問(wèn)

打開(kāi)瀏覽器訪問(wèn)：

http://127.0.0.1:18789/__openclaw__/canvas/
應(yīng)該看到 OpenClaw Web UI

預(yù)防措施

1. 使用固定端口前檢查

# 創(chuàng)建啟動(dòng)腳本 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
}
# 啟動(dòng) Gateway
openclaw gateway start

2. 配置 Systemd/Windows Service

# 使用 nssm 創(chuàng)建 Windows 服務(wù)
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. 監(jiān)控腳本

# monitor.ps1
while ($true) {
    try {
        $response = Invoke-RestMethod -Uri "http://127.0.0.1:18789/health" -TimeoutSec 5
        Write-Host "$(Get-Date) ? Gateway 運(yùn)行正常"
    } catch {
        Write-Host "$(Get-Date) ? Gateway 無(wú)響應(yīng)，嘗試重啟..."
        openclaw gateway restart
    }
    Start-Sleep -Seconds 60
}

Windows 環(huán)境特殊注意事項(xiàng)

問(wèn)題	解決方案
路徑過(guò)長(zhǎng)	使用 `\\?\` 前綴或縮短路徑
權(quán)限不足	以管理員身份運(yùn)行 PowerShell
殺毒軟件攔截	將 OpenClaw 目錄加入白名單
WSL 沖突	檢查 WSL 是否占用了相同端口
快速啟動(dòng)	禁用 Windows 快速啟動(dòng)功能

總結(jié)

問(wèn)題類(lèi)型	快速解決
端口被占用	`taskkill /PID [PID] /F`
殘留進(jìn)程	`taskkill /F /IM node.exe`
配置沖突	備份后刪除 `.openclaw` 重新配置
權(quán)限問(wèn)題	以管理員身份運(yùn)行
防火墻	添加入站規(guī)則允許 18789 端口

到此這篇關(guān)于OpenClaw端口占用排查:Gateway Connection Refused的解決指南的文章就介紹到這了,更多相關(guān)OpenClaw端口占用排查內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！