Gateway 是 OpenClaw 的 WebSocket 伺服器（通道、節點、工作階段、hook）。本頁中的子命令位於Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw gateway … 之下。
Bonjour discovery
本機 mDNS + 廣域 DNS-SD 設定。
Discovery overview
OpenClaw 如何宣告與尋找 Gateway。
Configuration
頂層 Gateway 設定鍵。
執行 Gateway
執行本機 Gateway 處理程序：Startup behavior
Startup behavior
- 根據預設，除非
~/.openclaw/openclaw.json中設定了gateway.mode=local，否則 Gateway 會拒絕啟動。針對臨時/開發執行，請使用--allow-unconfigured。 openclaw onboard --mode local和openclaw setup預期會寫入gateway.mode=local。如果檔案存在但缺少gateway.mode，請將其視為損壞或遭覆寫的設定，並修復它，而不是隱含假設為本機模式。- 如果檔案存在且缺少
gateway.mode，Gateway 會將其視為可疑的設定損壞，並拒絕替你「猜測為本機」。 - 未使用驗證卻繫結到 loopback 之外會被封鎖（安全護欄）。
SIGUSR1會在授權時觸發處理程序內重啟（預設啟用commands.restart；設定commands.restart: false可封鎖手動重啟，同時仍允許 Gateway 工具/設定套用/更新）。SIGINT/SIGTERM處理常式會停止 Gateway 處理程序，但不會還原任何自訂終端機狀態。如果你用 TUI 或 raw-mode 輸入包裝 CLI，請在結束前還原終端機。
選項
WebSocket 連接埠（預設值來自設定/env；通常是
18789）。監聽器繫結模式。
驗證模式覆寫。
Token 覆寫（也會為處理程序設定
OPENCLAW_GATEWAY_TOKEN）。密碼覆寫。
從檔案讀取 Gateway 密碼。
透過 Tailscale 公開 Gateway。
關閉時重設 Tailscale serve/funnel 設定。
允許在設定中沒有
gateway.mode=local 時啟動 Gateway。僅針對臨時/開發啟動流程繞過啟動防護；不會寫入或修復設定檔。如果缺少開發設定 + 工作區，則建立它們（略過 BOOTSTRAP.md）。
重設開發設定 + 憑證 + 工作階段 + 工作區（需要
--dev）。啟動前終止所選連接埠上的任何現有監聽器。
詳細記錄。
只在主控台中顯示 CLI 後端記錄（並啟用 stdout/stderr）。
WebSocket 記錄樣式。
--ws-log compact 的別名。將原始模型串流事件記錄到 jsonl。
原始串流 jsonl 路徑。
啟動分析
- 設定
OPENCLAW_GATEWAY_STARTUP_TRACE=1，以在 Gateway 啟動期間記錄各階段計時，包括每階段的eventLoopMax延遲，以及 installed-index、manifest registry、啟動規劃和 owner-map 工作的 Plugin 查找表計時。 - 設定
OPENCLAW_DIAGNOSTICS=timeline搭配OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>，以為外部 QA 測試工具寫入盡力而為的 JSONL 啟動診斷時間軸。你也可以在設定中使用diagnostics.flags: ["timeline"]啟用該旗標；路徑仍由 env 提供。加入OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1可包含事件迴圈樣本。 - 執行
pnpm test:startup:gateway -- --runs 5 --warmup 1來對 Gateway 啟動進行基準測試。該基準測試會記錄第一個處理程序輸出、/healthz、/readyz、啟動追蹤計時、事件迴圈延遲，以及 Plugin 查找表計時詳細資料。
查詢執行中的 Gateway
所有查詢命令都使用 WebSocket RPC。- Output modes
- 預設：人類可讀（在 TTY 中著色）。
--json：機器可讀 JSON（無樣式/spinner）。--no-color（或NO_COLOR=1）：停用 ANSI，同時保留人類版面。
設定
--url 時，CLI 不會退回使用設定或環境憑證。請明確傳入 --token 或 --password。缺少明確憑證會導致錯誤。gateway health
/healthz 端點是存活探針：當伺服器能回應 HTTP 時即會返回。HTTP /readyz 端點更嚴格，會在啟動 sidecar、通道或已設定的 hook 仍在穩定中時維持紅燈。本機或已驗證的詳細就緒回應會包含 eventLoop 診斷區塊，其中有事件迴圈延遲、事件迴圈使用率、CPU 核心比率，以及 degraded 旗標。
gateway usage-cost
從工作階段記錄擷取使用成本摘要。
要包含的天數。
gateway stability
從執行中的 Gateway 擷取近期診斷穩定性記錄器。
要包含的近期事件數量上限（最大
1000）。依診斷事件類型篩選，例如
payload.large 或 diagnostic.memory.pressure。只包含診斷序號之後的事件。
讀取持久化的穩定性 bundle，而不是呼叫執行中的 Gateway。使用
--bundle latest（或只用 --bundle）可取得狀態目錄下最新的 bundle，或直接傳入 bundle JSON 路徑。寫入可分享的支援診斷 zip，而不是列印穩定性詳細資料。
--export 的輸出路徑。Privacy and bundle behavior
Privacy and bundle behavior
- 記錄會保留作業中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/Plugin 名稱，以及已遮蔽的工作階段摘要。它們不會保留聊天文字、webhook 內文、工具輸出、原始請求或回應內文、token、cookie、秘密值、主機名稱或原始工作階段 ID。設定
diagnostics.enabled: false可完全停用記錄器。 - 在 Gateway 發生致命結束、關閉逾時和重啟啟動失敗時，如果記錄器有事件，OpenClaw 會將相同的診斷快照寫入
~/.openclaw/logs/stability/openclaw-stability-*.json。使用openclaw gateway stability --bundle latest檢查最新 bundle；--limit、--type和--since-seq也適用於 bundle 輸出。
gateway diagnostics export
寫入本機診斷 zip，設計用於附加到錯誤回報。隱私模型和 bundle 內容請參閱 診斷匯出。
輸出 zip 路徑。預設為狀態目錄下的支援匯出。
要包含的已清理記錄行數上限。
要檢查的記錄位元組數上限。
用於健康狀態快照的 Gateway WebSocket URL。
用於健康狀態快照的 Gateway token。
用於健康狀態快照的 Gateway 密碼。
狀態/健康狀態快照逾時。
略過持久化穩定性 bundle 查找。
以 JSON 列印寫入的路徑、大小和 manifest。
gateway status
gateway status 顯示 Gateway 服務（launchd/systemd/schtasks），並可選擇探測連線能力/驗證能力。
加入明確的探測目標。仍會探測已設定的遠端 + localhost。
探測使用的 token 驗證。
探測使用的密碼驗證。
探測逾時。
略過連線能力探測（僅服務檢視）。
也掃描系統層級服務。
將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零狀態結束。不能與
--no-probe 合併使用。狀態語意
狀態語意
gateway status即使在本機 CLI 設定缺失或無效時，仍可用於診斷。- 預設
gateway status會證明服務狀態、WebSocket 連線，以及握手時可見的驗證能力。它不會證明讀取/寫入/管理操作。 - 診斷探測對首次裝置驗證不會進行變更：若既有的快取裝置 token 存在，會重用該 token，但不會只為了檢查狀態而建立新的 CLI 裝置身分或唯讀裝置配對記錄。
gateway status會在可能時解析已設定的驗證 SecretRefs，以供探測驗證使用。- 如果此命令路徑中必要的驗證 SecretRef 未解析，當探測連線/驗證失敗時，
gateway status --json會回報rpc.authWarning；請明確傳入--token/--password，或先解析祕密來源。 - 如果探測成功，未解析的 auth-ref 警告會被抑制，以避免誤報。
- 在指令碼和自動化中，當只要服務正在監聽還不夠，且也需要讀取範圍的 RPC 呼叫保持健康時，請使用
--require-rpc。 --deep會加入盡力掃描，以尋找額外的 launchd/systemd/schtasks 安裝。偵測到多個類似 gateway 的服務時，人類可讀輸出會列印清理提示，並警告大多數設定應該在每台機器上只執行一個 gateway。- 人類可讀輸出包含解析後的檔案日誌路徑，以及 CLI 與服務設定路徑/有效性的快照，以協助診斷 profile 或 state-dir 漂移。
Linux systemd 驗證漂移檢查
Linux systemd 驗證漂移檢查
- 在 Linux systemd 安裝中，服務驗證漂移檢查會從 unit 讀取
Environment=和EnvironmentFile=值（包含%h、加引號的路徑、多個檔案，以及選用的-檔案）。 - 漂移檢查會使用合併後的執行階段 env 解析
gateway.auth.tokenSecretRefs（先用服務命令 env，再 fallback 到程序 env）。 - 如果 token 驗證未實際啟用（明確的
gateway.auth.mode為password/none/trusted-proxy，或 mode 未設定且 password 可以勝出、沒有 token 候選可以勝出），token 漂移檢查會略過設定 token 解析。
gateway probe
gateway probe 是「除錯所有項目」命令。它一律會探測：
- 你設定的遠端 gateway（如果已設定），以及
- localhost (loopback)，即使已設定遠端。
--url，該明確目標會加在兩者之前。人類可讀輸出會將目標標示為：
URL (explicit)Remote (configured)或Remote (configured, inactive)Local loopback
如果多個 gateway 可連線，它會列印所有 gateway。當你使用隔離的 profiles/ports（例如救援 bot）時，支援多個 gateway，但大多數安裝仍只執行單一 gateway。
解讀
解讀
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 受限。這會回報為降級可連線性，而不是完全失敗。Connect: ok之後的Read probe: failed表示 Gateway 接受了 WebSocket 連線，但後續讀取診斷逾時或失敗。這也屬於降級可連線性，而不是 Gateway 無法連線。- 與
gateway status一樣，probe 會重用既有的快取裝置驗證，但不會建立首次裝置身分或配對狀態。 - 只有在沒有任何已探測目標可連線時，退出碼才會是非零。
JSON 輸出
JSON 輸出
最上層：
ok：至少有一個目標可連線。degraded：至少有一個目標接受連線，但未完成完整的詳細 RPC 診斷。capability：在可連線目標中觀察到的最佳能力（read_only、write_capable、admin_capable、pairing_pending、connected_no_operator_scope或unknown）。primaryTargetId：依此順序作為作用中勝出者的最佳目標：明確 URL、SSH tunnel、已設定遠端，然後是 local loopback。warnings[]：盡力產生的警告記錄，包含code、message，以及選用的targetIds。network：從目前設定與主機網路推導出的 local loopback/tailnet URL 提示。discovery.timeoutMs和discovery.count：此探測回合使用的實際 discovery 預算/結果數量。
targets[].connect）：ok：連線加上降級分類後的可連線性。rpcOk：完整詳細 RPC 成功。scopeLimited：詳細 RPC 因缺少 operator scope 而失敗。
targets[].auth）：role：可用時，hello-ok中回報的驗證角色。scopes：可用時，hello-ok中回報的已授權 scopes。capability：該目標呈現出的驗證能力分類。
常見警告代碼
常見警告代碼
ssh_tunnel_failed：SSH tunnel 設定失敗；命令 fallback 到直接探測。multiple_gateways：有超過一個目標可連線；除非你刻意執行隔離的 profiles，例如救援 bot，否則這很不尋常。auth_secretref_unresolved：無法為失敗目標解析已設定的驗證 SecretRef。probe_scope_limited：WebSocket 連線成功，但讀取探測因缺少operator.read而受限。
透過 SSH 遠端連線（Mac app parity）
macOS app 的「Remote over SSH」模式使用本機 port-forward，因此遠端 gateway（可能只綁定到 loopback）會在ws://127.0.0.1:<port> 可連線。
CLI 等效命令：
user@host 或 user@host:port（port 預設為 22）。身分檔案。
從解析後的 discovery endpoint（
local. 加上已設定的 wide-area domain，如果有）選取第一個發現的 gateway host 作為 SSH 目標。只含 TXT 的提示會被忽略。gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
低階 RPC 輔助命令。
params 的 JSON object 字串。
Gateway WebSocket URL。
Gateway token。
Gateway password。
逾時預算。
主要用於 agent-style RPC，這類 RPC 會在最終 payload 前串流中間事件。
機器可讀 JSON 輸出。
--params 必須是有效的 JSON。管理 Gateway 服務
使用 wrapper 安裝
當受管理服務必須透過另一個執行檔啟動時，請使用--wrapper，例如
secrets manager shim 或 run-as helper。wrapper 會收到一般 Gateway args，並
負責最終 exec openclaw 或帶有這些 args 的 Node。
gateway install 會驗證該路徑是
可執行檔，將 wrapper 寫入服務 ProgramArguments，並在服務環境中持久化
OPENCLAW_WRAPPER，供之後強制重新安裝、更新與 doctor
修復使用。
OPENCLAW_WRAPPER：
命令選項
命令選項
gateway status：--url、--token、--password、--timeout、--no-probe、--require-rpc、--deep、--jsongateway install：--port、--runtime <node|bun>、--token、--wrapper <path>、--force、--jsongateway uninstall|start|stop|restart：--json
生命週期行為
生命週期行為
- 使用
gateway restart重新啟動受管理服務。不要串接gateway stop和gateway start來替代重新啟動；在 macOS 上，gateway stop會刻意在停止前停用 LaunchAgent。 - 生命週期命令接受
--json以供指令碼使用。
安裝時的驗證與 SecretRefs
安裝時的驗證與 SecretRefs
- 當 token 驗證需要 token，且
gateway.auth.token由 SecretRef 管理時，gateway install會驗證 SecretRef 可解析，但不會將解析後的 token 持久化到服務環境中繼資料。 - 如果 token 驗證需要 token，且已設定的 token SecretRef 未解析，安裝會封閉失敗，而不是持久化 fallback plaintext。
- 對於
gateway run的 password 驗證，建議使用OPENCLAW_GATEWAY_PASSWORD、--password-file，或以 SecretRef 支援的gateway.auth.password，而不是 inline--password。 - 在推斷驗證模式中，僅限 shell 的
OPENCLAW_GATEWAY_PASSWORD不會放寬安裝 token 需求；安裝受管理服務時，請使用持久設定（gateway.auth.password或 configenv）。 - 如果同時設定了
gateway.auth.token和gateway.auth.password，且gateway.auth.mode未設定，安裝會被阻擋，直到明確設定 mode。
探索 gateways（Bonjour）
gateway discover 會掃描 Gateway beacons（_openclaw-gw._tcp）。
- Multicast DNS-SD：
local. - Unicast DNS-SD（Wide-Area Bonjour）：選擇一個 domain（範例：
openclaw.internal.）並設定 split DNS 與 DNS server；請參閱 Bonjour。
role（gateway role 提示）transport（transport 提示，例如gateway）gatewayPort（WebSocket port，通常是18789）sshPort（選用；缺少時 clients 預設 SSH 目標為22）tailnetDns（MagicDNS hostname，可用時）gatewayTls/gatewayTlsSha256（TLS 已啟用 + cert fingerprint）cliPath（寫入 wide-area zone 的 remote-install 提示）
gateway discover
每個命令的逾時（browse/resolve）。
機器可讀輸出（也會停用樣式/spinner）。
- CLI 會掃描
local.，並在啟用時掃描已設定的廣域網域。 - JSON 輸出中的
wsUrl是從已解析的服務端點衍生而來，而不是來自僅 TXT 的提示，例如lanHost或tailnetDns。 - 在
local.mDNS 上，只有當discovery.mdns.mode為full時，才會廣播sshPort和cliPath。廣域 DNS-SD 仍會寫入cliPath；sshPort在那裡也維持選用。