OpenClaw端口占用排查:Gateway Connection Refused的解決指南
問題現(xiàn)象
用戶在 Windows 11 上全新安裝 OpenClaw 后,完成 onboarding 流程,但在啟動 Gateway 時遇到 連接被拒絕 錯誤:
ERR_CONNECTION_REFUSED
http://127.0.0.1:18789/__openclaw__/canvas/
環(huán)境信息:
- OS: Windows 11
- OpenClaw: latest
- Node.js: latest
- 特殊情況:之前安裝過 Cladbot
診斷過程
1. 確認 Gateway 狀態(tài)
# 檢查 Gateway 狀態(tài) openclaw gateway status # 可能的輸出: # ? Gateway 未運行 # 或 # ?? Gateway 運行中但端口未監(jiān)聽
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"}
# 查找端口監(jiān)聽
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 可能使用相同的配置目錄或環(huán)境變量。
解決方案:
# 1. 清理環(huán)境變量
[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 的網(wǎng)絡訪問。
解決方案:
# 1. 檢查防火墻規(guī)則
Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*node*" -or $_.DisplayName -like "*openclaw*"}
# 2. 添加入站規(guī)則(管理員權限)
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. 檢查殘留進程
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 端口持續(xù)被占用:
// ~/.openclaw/openclaw.json
{
"gateway": {
"port": 58789,
"host": "127.0.0.1"
}
}然后:
openclaw gateway restart # 訪問: http://127.0.0.1:58789/__openclaw__/canvas/
驗證步驟
1. 端口監(jiān)聽驗證
# 應該看到 LISTENING 狀態(tài) 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. 使用固定端口前檢查
# 創(chuà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
}
# 啟動 Gateway
openclaw gateway start2. 配置 Systemd/Windows Service
# 使用 nssm 創(chuàng)建 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. 監(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 運行正常"
} catch {
Write-Host "$(Get-Date) ? Gateway 無響應,嘗試重啟..."
openclaw gateway restart
}
Start-Sleep -Seconds 60
}Windows 環(huán)境特殊注意事項
| 問題 | 解決方案 |
| 路徑過長 | 使用 `\\?\` 前綴或縮短路徑 |
| 權限不足 | 以管理員身份運行 PowerShell |
| 殺毒軟件攔截 | 將 OpenClaw 目錄加入白名單 |
| WSL 沖突 | 檢查 WSL 是否占用了相同端口 |
| 快速啟動 | 禁用 Windows 快速啟動功能 |
總結
| 問題類型 | 快速解決 |
| 端口被占用 | `taskkill /PID [PID] /F` |
| 殘留進程 | `taskkill /F /IM node.exe` |
| 配置沖突 | 備份后刪除 `.openclaw` 重新配置 |
| 權限問題 | 以管理員身份運行 |
| 防火墻 | 添加入站規(guī)則允許 18789 端口 |
到此這篇關于OpenClaw端口占用排查:Gateway Connection Refused的解決指南的文章就介紹到這了,更多相關OpenClaw端口占用排查內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章,希望大家以后多多支持腳本之家!
相關文章

OpenClaw Gateway設備Token不匹配問題排查與解決全指南
用戶在使用 OpenClaw 2026.2.15 版本時,突然遇到設備Token不匹配的錯誤,下面小編就和大家詳細介紹一下如何排查問題并解決,文中的示例代碼講解詳細,感興趣的小伙伴可以2026-03-13
OpenClaw 樹莓派部署終極避坑指南之快速解決OpenClaw Gateway儀表盤登錄問題
本文詳細介紹了在樹莓派上部署OpenClawGateway時遇到的四個核心問題及其解決方案:局域網(wǎng)無法訪問、跨域錯誤、HTTPS安全上下文限制和設備配對驗證,通過逐一解決這些問題,您2026-03-13
OpenClaw龍蝦安裝部署全流程:手把手教你搭建自己的AI助手
OpenClaw 是一個自托管的 AI 網(wǎng)關,它可以把你常用的聊天軟件(微信、Telegram、Discord、iMessage…)和一個 AI 助手連接起來,下面小編就和大家詳細講講如何正確安裝部署O2026-03-16
本文詳細介紹了如何在騰訊云服務器上安裝和配置OpenClaw,使其無需消耗個人Token即可使用Qwen大模型進行文本和視覺任務,安裝過程中涉及Node.js環(huán)境配置、NVM安裝、OpenClaw2026-03-15
OpenClaw推薦在Windows上通過WSL2運行,使用Ubuntu發(fā)行版,CLI和Gateway運行在Linux環(huán)境中,保持運行時一致性并提高工具鏈兼容性,WSL2提供完整Linux體驗,只需一條命令即可安裝2026-03-12
Windows、macOS、Linux三系統(tǒng)本地部署OpenClaw+避坑指南+Docker一鍵部署,30分鐘搞定
本文給大家分享全網(wǎng)最全的OpenClaw安裝部署教程,覆蓋Windows、macOS、Linux三系統(tǒng)本地部署,并最終提供Docker一鍵部署方案,感興趣的朋友一起看看吧2026-03-10
OpenClaw怎么安裝到電腦? OpenClaw免費小白安裝教程
OpenClaw怎么安裝到電腦?本文就為大家?guī)砹耸褂肅herry Studio一鍵安裝 OpenClaw,操作簡單,非常適合零基礎小白,需要的朋友一起看看吧2026-03-10








