OpenClaw 閘道器鎖定機制：解決連接埠衝突與啟動錯誤

開發時最煩人的事情之一，就是遇到「埠號被佔用」的錯誤，特別是當你以為已經關掉了舊的進程，卻發現它還躲在背景變成幽靈進程。這不僅浪費時間，還會讓自動化部署變得一團糟。

為了讓你開發更順手，我們在 Gateway 中實作了一套簡單卻強大的鎖定機制，確保你的開發環境始終保持整潔。

Gateway 鎖定機制

為什麼

• 確保同一個主機上的每個基礎埠號只運行一個 Gateway 實例；額外的 Gateway 必須使用獨立的 profile 和唯一的埠號。
• 在當機或遇到 SIGKILL 時能自動恢復，不會留下過時的鎖定檔案（lock files）。
• 當控制埠號被佔用時，能立即噴出清晰的錯誤訊息並停止啟動。

運作機制

• Gateway 在啟動時會立即透過獨佔的 TCP 監聽器綁定 WebSocket 監聽位址（預設為 ws://127.0.0.1:18789）。
• 如果綁定失敗並出現 EADDRINUSE，啟動程序會拋出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。
• 作業系統會在任何進程結束（包括當機和 SIGKILL）時自動釋放監聽器，因此不需要額外的鎖定檔案或清理步驟。
• 關機時，Gateway 會關閉 WebSocket 伺服器和底層的 HTTP 伺服器，迅速釋放埠號。

錯誤處理

• 如果埠號被其他進程佔用，啟動時會拋出 GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")。
• 其他綁定失敗則會顯示為 GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")。

操作注意事項

• 如果埠號被「其他」進程佔用，錯誤訊息是一樣的；請釋放該埠號，或使用 openclaw gateway --port <port> 選擇另一個埠號。
• macOS App 在啟動 Gateway 之前仍會維持自己的輕量級 PID 保護機制；而執行時期的鎖定則是透過 WebSocket 綁定來強制執行的。

相關文件

• Multiple Gateways — 使用唯一埠號運行多個實例
• Troubleshooting — 診斷 EADDRINUSE 和埠號衝突

---

下一步：

• 了解如何運行多個 Gateway
• 查看疑難排解指南

有任何設定上的疑問嗎？歡迎使用 AI Setup Assistant 獲取即時協助。