OpenClaw Gateway CLI 指南：快速啟動與配置 WebSocket 服務

Gateway CLI 概覽

Gateway 是 OpenClaw 的 WebSocket 伺服器，負責處理 channels、nodes、sessions 以及 hooks 等核心功能。透過 OpenClaw Gateway CLI，你可以輕鬆管理這些即時通訊組件，確保系統運作順暢。

本頁面列出的子指令皆位於 openclaw gateway … 之下。

相關文件：

啟動 Gateway 服務

若要啟動 Gateway 伺服器，請使用以下指令。這會根據你的設定檔初始化 WebSocket 連線，並開始監聽來自 nodes 的請求。

在終端機輸入以下指令來啟動服務：

openclaw gateway start

檢查 Gateway 狀態

你可以隨時透過 CLI 檢查目前 Gateway 的運作狀態。這對於除錯或是確認 Gateway 是否正確連線至 Node.js 環境非常有幫助。

執行狀態檢查指令：

openclaw gateway status

檢視 Gateway 日誌

當你需要追蹤 webhook 事件或排查連線問題時，查看即時日誌是最佳手段。這能讓你清楚看到所有經過 API 的流量與錯誤訊息。

使用以下指令來追蹤日誌輸出：

openclaw gateway logs --follow

重新載入 Gateway 設定

當你修改了 JSON 格式的設定檔後，不需要重啟整個服務，可以直接透過指令通知 Gateway 重新載入配置。

執行重新載入指令：

openclaw gateway reload

AI Setup Assistant

執行 Gateway

你可以透過執行本地的 Gateway 程序來啟動服務，這是使用 OpenClaw Gateway 進行開發與測試的基礎。

openclaw gateway

若你需要使用前景模式執行，可以使用以下別名：

openclaw gateway run

請注意以下事項：

預設情況下，如果 ~/.openclaw/openclaw.json 中沒有設定 gateway.mode=local，Gateway 將會拒絕啟動。若你只是想進行臨時測試或開發，可以使用 --allow-unconfigured 參數。
執行 openclaw onboard --mode local 與 openclaw setup 時，系統會自動將 gateway.mode=local 寫入設定檔。如果檔案存在但缺少 gateway.mode 欄位，系統會將其視為設定損壞並嘗試修復，而不是預設為本地模式。
若設定檔存在但缺少 gateway.mode，Gateway 會認為設定檔異常並拒絕自動推斷為本地模式。
基於安全考量，禁止在未經授權的情況下將服務綁定至 loopback 以外的位址。
當啟用 commands.restart（預設開啟）時，發送 SIGUSR1 訊號會觸發程序內重啟。你可以透過設定 commands.restart: false 來禁止手動重啟，但這不會影響 Gateway 工具、設定套用或更新功能。
SIGINT 與 SIGTERM 處理程序會停止 Gateway 程序，但不會還原自訂的終端機狀態。如果你使用 TUI 或 raw-mode 輸入包裝了 CLI，請記得在退出前還原終端機設定。

Gateway 選項設定

你可以透過多種參數來調整 Gateway 的執行行為，以符合你的開發環境需求。

--port <port>：設定 WebSocket 連接埠（預設值來自設定檔或環境變數，通常為 18789）。
--bind <loopback|lan|tailnet|auto|custom>：設定監聽綁定模式。
--auth <token|password>：覆寫驗證模式。
--token <token>：覆寫 token（同時會設定該程序的 OPENCLAW_GATEWAY_TOKEN）。
--password <password>：覆寫密碼。警告：直接在指令中輸入密碼可能會在本地程序列表中洩漏。
--password-file <path>：從指定檔案讀取 Gateway 密碼。
--tailscale <off|serve|funnel>：透過 Tailscale 暴露 Gateway 服務。
--tailscale-reset-on-exit：在關閉時重置 Tailscale serve/funnel 設定。
--allow-unconfigured：允許在設定檔中未設定 gateway.mode=local 的情況下啟動。這僅用於臨時或開發引導，不會寫入或修復設定檔。
--dev：若設定檔缺失，則建立開發用設定與工作區（會跳過 BOOTSTRAP.md）。
--reset：重置開發設定、憑證、連線階段與工作區（需搭配 --dev 使用）。
--force：在啟動前強制終止指定連接埠上已存在的監聽程序。
--verbose：顯示詳細日誌。
--cli-backend-logs：僅在控制台顯示 CLI 後端日誌（並啟用 stdout/stderr）。
--ws-log <auto|full|compact>：設定 WebSocket 日誌樣式（預設為 auto）。
--compact：等同於 --ws-log compact。
--raw-stream：將原始模型串流事件記錄為 JSONL 格式。
--raw-stream-path <path>：指定原始串流 JSONL 的儲存路徑。

啟動效能分析

你可以透過環境變數或專用的測試指令來追蹤與評估 Gateway 的啟動效能。

設定 OPENCLAW_GATEWAY_STARTUP_TRACE=1 以記錄 Gateway 啟動期間各階段的時間消耗。
執行 pnpm test:startup:gateway -- --runs 5 --warmup 1 來對 Gateway 啟動進行基準測試。此測試會記錄首次程序輸出、/healthz、/readyz 以及啟動追蹤的時間數據。

查詢運作中的 Gateway

所有的查詢指令都使用 WebSocket RPC 來進行溝通。

輸出模式：

預設：人類可讀格式（在 TTY 中會有顏色標示）。
--json：機器可讀的 JSON 格式（沒有樣式或載入動畫）。
--no-color（或 NO_COLOR=1）：停用 ANSI 顏色，同時保持人類可讀的排版。

共用選項（在支援的指令中）：

--url <url>：Gateway 的 WebSocket URL。
--token <token>：Gateway 的 token。
--password <password>：Gateway 的密碼。
--timeout <ms>：逾時時間或預算（根據指令而異）。
--expect-final：等待「最終」回應（用於 agent 呼叫）。

注意：當你設定 --url 時，CLI 不會回退到設定檔或環境變數中的憑證。請務必明確傳入 --token 或 --password。若缺少明確的憑證將會導致錯誤。

`gateway health`

你可以透過此指令檢查 Gateway 的健康狀態，確保服務正常運作。

openclaw gateway health --url ws://127.0.0.1:18789

HTTP 的 /healthz 端點是用於存活探測（liveness probe）：一旦伺服器能回應 HTTP 請求，它就會回傳。HTTP 的 /readyz 端點則更為嚴格，如果啟動時的 sidecars、channels 或已設定的 hooks 尚未就緒，它會保持紅色狀態。

`gateway usage-cost`

此指令用於從 session 日誌中獲取使用成本摘要。

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

選項：

--days <days>：要包含的天數（預設為 30）。

`gateway status`

gateway status 會顯示 Gateway 服務（launchd/systemd/schtasks）的狀態，並可選地探測連線能力或驗證功能。

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

選項：

--url <url>：新增一個明確的探測目標。已設定的遠端與 localhost 仍會被探測。
--token <token>：用於探測的 token 驗證。
--password <password>：用於探測的密碼驗證。
--timeout <ms>：探測逾時時間（預設 10000）。
--no-probe：跳過連線探測（僅檢視服務狀態）。
--deep：同時掃描系統層級的服務。
--require-rpc：將預設的連線探測升級為讀取探測，若讀取探測失敗則會以非零狀態碼退出。此選項不能與 --no-probe 同時使用。

注意事項：

即使本機 CLI 設定遺失或無效，gateway status 仍可用於診斷。
預設的 gateway status 可驗證服務狀態、WebSocket 連線以及握手時可見的驗證能力。它無法驗證讀取/寫入/管理操作。
gateway status 會在可能的情況下解析已設定的 auth SecretRefs 以進行探測驗證。
如果在此指令路徑中無法解析必要的 auth SecretRef，當探測連線或驗證失敗時，gateway status --json 會回報 rpc.authWarning；請明確傳入 --token/--password 或先解析 secret 來源。
如果探測成功，未解析的 auth-ref 警告將會被隱藏，以避免誤報。
當監聽服務不足，且你需要確保讀取範圍的 RPC 呼叫也正常運作時，請在指令碼與自動化流程中使用 --require-rpc。
--deep 會針對額外的 launchd/systemd/schtasks 安裝進行盡力掃描。當偵測到多個類似 Gateway 的服務時，人類可讀的輸出會列出清理建議，並警告大多數設定應保持每台機器僅執行一個 Gateway。
人類可讀的輸出包含已解析的檔案日誌路徑，以及 CLI 與服務設定路徑/有效性快照，協助診斷設定檔或狀態目錄偏移。
在 Linux systemd 安裝中，服務驗證偏移檢查會讀取單元中的 Environment= 與 EnvironmentFile= 值（包含 %h、引號路徑、多個檔案以及選用的 - 檔案）。
偏移檢查會使用合併後的執行時期環境變數來解析 gateway.auth.token SecretRefs（優先使用服務指令環境，其次為處理程序環境回退）。
如果 token 驗證未有效啟用（明確設定 gateway.auth.mode 為 password/none/trusted-proxy，或模式未設定且密碼驗證優先，且無 token 候選），token 偏移檢查將跳過設定 token 解析。

`gateway probe`

gateway probe 是「除錯一切」的指令。它總是會探測：

你已設定的遠端 Gateway（若有設定），以及
本機 (localhost) 即使已設定遠端。

如果你傳入 --url，該明確目標會被加入到前兩者之前。人類可讀的輸出會將目標標記為：

URL (explicit)
Remote (configured) 或 Remote (configured, inactive)
Local loopback

如果多個 Gateway 可達，它會全部列出。當你使用隔離的設定檔/連接埠（例如救援機器人）時，支援多個 Gateway，但大多數安裝仍只執行一個 Gateway。

openclaw gateway probe
openclaw gateway probe --json

解讀方式：

Reachable: yes 表示至少有一個目標接受了 WebSocket 連線。
Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only 報告了探測器對驗證能力的驗證結果。這與連線能力是分開的。
Read probe: ok 表示讀取範圍的詳細 RPC 呼叫（health/status/system-presence/config.get）也成功了。
Read probe: limited - missing scope: operator.read 表示連線成功，但讀取範圍的 RPC 受限。這會被回報為降級 (degraded) 的連線能力，而非完全失敗。
只有在沒有任何探測目標可達時，退出代碼才會是非零值。

JSON 注意事項 (--json)：

頂層：
- ok：至少有一個目標可達。
- degraded：至少有一個目標出現範圍受限的詳細 RPC。
- capability：在所有可達目標中觀察到的最佳能力（read_only、write_capable、admin_capable、pairing_pending、connected_no_operator_scope 或 unknown）。
- primaryTargetId：被視為活躍勝出者的最佳目標，順序為：明確 URL、SSH 通道、已設定遠端、本機 loopback。
- warnings[]：盡力記錄的警告，包含 code、message 以及選用的 targetIds。
- network：從目前設定與主機網路導出的本機 loopback/tailnet URL 提示。
- discovery.timeoutMs 與 discovery.count：此次探測過程實際使用的發現預算/結果數量。
每個目標 (targets[].connect)：
- ok：連線後的連線能力 + 降級分類。
- rpcOk：詳細 RPC 完全成功。
- scopeLimited：詳細 RPC 因缺少 operator scope 而失敗。
每個目標 (targets[].auth)：
- role：在 hello-ok 中回報的驗證角色（若可用）。
- scopes：在 hello-ok 中回報的授權範圍（若可用）。
- capability：該目標呈現的驗證能力分類。

常見警告代碼：

ssh_tunnel_failed：SSH 通道設定失敗；指令回退到直接探測。
multiple_gateways：多個目標可達；除非你刻意執行隔離設定檔（如救援機器人），否則這並不常見。
auth_secretref_unresolved：無法為失敗的目標解析已設定的 auth SecretRef。
probe_scope_limited：WebSocket 連線成功，但讀取探測受限於缺少 operator.read。

透過 SSH 的遠端連線 (Mac App 同步)

macOS 應用程式的「透過 SSH 的遠端連線」模式使用本機連接埠轉發，因此遠端 Gateway（可能僅綁定在 loopback）可以在 ws://127.0.0.1:<port> 處被存取。

CLI 等效指令：

openclaw gateway probe --ssh user@gateway-host

選項：

--ssh <target>：user@host 或 user@host:port（連接埠預設為 22）。
--ssh-identity <path>：身份驗證檔案。
--ssh-auto：從已解析的發現端點（local. 加上已設定的廣域網域，若有的話）中挑選第一個發現的 Gateway 主機作為 SSH 目標。僅 TXT 的提示會被忽略。

設定（選用，作為預設值）：

gateway.remote.sshTarget
gateway.remote.sshIdentity

`gateway call <method>`

低階 RPC 輔助工具。

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

選項：

--params <json>：參數的 JSON 物件字串（預設 {}）。
--url <url>
--token <token>
--password <password>
--timeout <ms>
--expect-final
--json

注意事項：

--params 必須是有效的 JSON。
--expect-final 主要用於在最終酬載之前串流中間事件的 agent 風格 RPC。

管理 Gateway 服務

當你需要處理後端連線或維護系統穩定性時，OpenClaw 的 Gateway 服務管理功能可以幫你快速搞定。透過簡單的指令，你就能輕鬆控制服務的生命週期。

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

Gateway 指令選項

這些指令選項能讓你更精確地控制 Gateway 的行為，特別是在需要進行自動化腳本編寫時。

gateway status 支援的參數：--url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
gateway install 支援的參數：--port, --runtime <node|bun>, --token, --force, --json
gateway uninstall|start|stop|restart 支援的參數：--json

Gateway 服務注意事項

在設定與安裝過程中，請留意以下關於權限與環境變數的細節，以確保 Gateway 運作順暢。

gateway install 指令支援 --port, --runtime, --token, --force, --json 這些參數。
當驗證機制需要 token 且 gateway.auth.token 是由 SecretRef 管理時，gateway install 會驗證該 SecretRef 是否可解析，但不會將解析後的 token 寫入服務環境元數據中。
若驗證機制需要 token 但設定的 SecretRef 無法解析，安裝程序會直接失敗並停止，而不會保留不安全的明文作為備用。
若要在 gateway run 中使用密碼驗證，建議優先使用 OPENCLAW_GATEWAY_PASSWORD、--password-file，或是由 SecretRef 支援的 gateway.auth.password，盡量避免直接在指令中使用 --password。
在推斷驗證模式下，僅在 shell 設定的 OPENCLAW_GATEWAY_PASSWORD 並不會放寬安裝時對 token 的要求；若要安裝受管理的服務，請使用持久化配置（例如 gateway.auth.password 或環境變數配置）。
如果同時設定了 gateway.auth.token 與 gateway.auth.password，且未明確指定 gateway.auth.mode，安裝程序將會被阻擋，直到你明確設定模式為止。
所有的生命週期指令皆接受 --json 參數，方便你進行腳本化操作。

AI Setup Assistant

透過 Bonjour 發現 Gateway

使用 OpenClaw 進行 Gateway 發現時，你可以透過 gateway discover 指令來掃描網路中的 Gateway 訊號（_openclaw-gw._tcp）。

Multicast DNS-SD：針對 local. 網域進行掃描。
Unicast DNS-SD (Wide-Area Bonjour)：選擇一個網域（例如 openclaw.internal.），並設定分割 DNS 與 DNS 伺服器；詳細資訊請參考 /gateway/bonjour。

只有開啟 Bonjour 發現功能（預設為開啟）的 Gateway 才會廣播此訊號。

廣域發現記錄包含以下 TXT 欄位：

role（Gateway 角色提示）
transport（傳輸提示，例如 gateway）
gatewayPort（WebSocket 連接埠，通常為 18789）
sshPort（選填；若未提供，客戶端預設 SSH 目標為 22）
tailnetDns（可用的 MagicDNS 主機名稱）
gatewayTls / gatewayTlsSha256（已啟用 TLS 與憑證指紋）
cliPath（寫入廣域區域的遠端安裝提示）

使用 gateway discover 指令

你可以直接在終端機執行此指令來搜尋網路中的 Gateway 節點。

openclaw gateway discover

可用選項：

--timeout <ms>：設定每個指令的逾時時間（瀏覽/解析）；預設值為 2000。
--json：輸出機器可讀格式（同時會停用樣式與載入動畫）。

範例：

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'

注意事項：

CLI 會掃描 local. 以及已設定的廣域網域。
JSON 輸出中的 wsUrl 是從解析後的服務端點導出，並非僅來自 lanHost 或 tailnetDns 等 TXT 提示。
在 local. mDNS 環境下，只有當 discovery.mdns.mode 設定為 full 時，才會廣播 sshPort 與 cliPath。廣域 DNS-SD 仍會寫入 cliPath，而 sshPort 在該環境下同樣維持選填。

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。