Gateway 運行指南：從本地啟動到生產維運

很多時候，我們只是想讓一個服務乖乖跑起來，但偏偏會遇到埠號被佔用、設定檔沒讀到，或是服務無預警掛掉卻找不到日誌的情況。處理這些瑣碎的維運基礎建設，往往比開發核心功能還要耗神。

這份指南會帶你搞定 Gateway 的第一天啟動與之後的日常維運，讓你把精力放在真正重要的事情上。

需要準備的東西

在開始之前，請確保你已經準備好：

• 已安裝 openclaw CLI 工具
• 基本的終端機操作能力

Quick Start：5 分鐘本地啟動

你可以透過以下步驟快速啟動並驗證 Gateway 服務。

1. 啟動 Gateway

你可以選擇標準啟動，或是開啟詳細日誌來觀察運作狀況：

# 標準啟動
openclaw gateway --port 18789

# 開啟詳細日誌，將 debug/trace 輸出到標準輸出
openclaw gateway --port 18789 --verbose

# 強制關閉佔用該埠號的程序並啟動
openclaw gateway --force

2. 驗證服務健康狀況

啟動後，檢查服務是否正常運行：

openclaw gateway status
openclaw status
openclaw logs --follow

當你看到 Runtime: running 且 RPC probe: ok 時，代表服務處於健康的基準狀態。

3. 確認 Channel 就緒

最後，確認所有 Channel 的連線狀態：

openclaw channels status --probe

注意： Gateway 的設定重載會監控設定檔路徑（由 profile 或 OPENCLAW_CONFIG_PATH 決定）。預設模式為 gateway.reload.mode="hybrid"。

運行模型

Gateway 採用單一長駐程序處理路由、控制平面與 Channel 連線。它使用單一多路複用埠號（Multiplexed port）來處理以下任務：

• WebSocket 控制與 RPC
• HTTP APIs（相容 OpenAI、回應處理、工具調用）
• 控制 UI 與 hooks

預設的綁定模式（Bind mode）為 loopback。此外，系統預設要求 Auth 認證，你需要配置 gateway.auth.token / gateway.auth.password 或使用環境變數 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。

埠號與綁定優先順序

設定項	優先順序 (由高到低)
Gateway port	--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Bind mode	CLI/override → gateway.bind → loopback

熱重載模式

gateway.reload.mode	行為描述
off	不進行設定重載
hot	僅套用不影響運行的安全變更
restart	偵測到需要重啟的變更時自動重啟
hybrid (預設)	安全時熱套用，必要時自動重啟

遠端存取

如果你需要從遠端連線，首選方案是使用 Tailscale 或 VPN。如果無法使用，可以採用 SSH tunnel 作為替代方案：

ssh -N -L 18789:127.0.0.1:18789 user@host

接著在本地端將客戶端連線至 ws://127.0.0.1:18789。

警告： 如果啟用了 Gateway Auth，即便透過 SSH tunnel，客戶端連線時仍必須提供 token 或 password。

服務監控與生命週期

在生產環境中，建議使用守護程序（Supervision）來確保可靠性。

macOS (launchd)

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

你可以使用 openclaw doctor 來稽核並修復服務設定的偏差。

Linux (systemd user)

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

若要在登出後保持執行，請啟用 lingering：

sudo loginctl enable-linger <user>

疑難排解

以下是常見的錯誤特徵與對應原因：

錯誤特徵	可能原因
refusing to bind gateway ... without auth	在非 loopback 綁定下未設定 token/password
another gateway instance is already listening / EADDRINUSE	埠號衝突，已被其他程序佔用
Gateway start blocked: set gateway.mode=local	設定檔被設為遠端模式 (remote mode)
unauthorized during connect	客戶端與 Gateway 之間的 Auth 資訊不匹配

安全保證

• 當 Gateway 無法連線時，客戶端會立即報錯，不會隱式降級到直接連線模式。
• 若連線後的第一個 Frame 不是 connect，Gateway 會拒絕連線並關閉 Socket。
• 正常的關閉流程會在 Socket 斷開前發送 shutdown 事件。

---

如果你在設定過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

下一步

• Troubleshooting
• Configuration
• Authentication
• Doctor