Gateway 是 OpenClaw 的 WebSocket 伺服器（通道、節點、工作階段、hook）。本頁中的子命令位於Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw gateway … 底下。
Bonjour 探索
本機 mDNS + 廣域 DNS-SD 設定。
探索概觀
OpenClaw 如何公告並尋找 gateway。
設定
頂層 gateway 設定鍵。
執行 Gateway
執行本機 Gateway 程序：啟動行為
啟動行為
- 預設情況下，除非
~/.openclaw/openclaw.json中已設定gateway.mode=local，否則 Gateway 會拒絕啟動。對臨時/開發執行使用--allow-unconfigured。 openclaw onboard --mode local和openclaw setup預期會寫入gateway.mode=local。如果檔案存在但缺少gateway.mode，請將其視為損壞或被覆寫的設定並修復，而不是隱含假設為 local 模式。- 如果檔案存在且缺少
gateway.mode，Gateway 會將其視為可疑的設定損壞，並拒絕替你「猜測 local」。 - 未使用驗證而繫結到 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 繞過啟動防護；不會寫入或修復設定檔。如果缺少，建立開發設定 + 工作區（略過 BOOTSTRAP.md）。
重設開發設定 + 憑證 + 工作階段 + 工作區（需要
--dev）。啟動前終止所選連接埠上的任何既有監聽器。
詳細記錄。
僅在主控台顯示 CLI 後端記錄（並啟用 stdout/stderr）。
Websocket 記錄樣式。
--ws-log compact 的別名。將原始模型串流事件記錄到 jsonl。
原始串流 jsonl 路徑。
重新啟動 Gateway
openclaw gateway restart --safe 會要求執行中的 Gateway 在重新啟動前預檢作用中的 OpenClaw 工作。如果佇列中的操作、回覆傳遞、嵌入式執行或任務執行處於作用中，Gateway 會回報阻擋項目、合併重複的安全重新啟動要求，並在作用中工作排空後重新啟動。純 restart 會保留既有服務管理器行為以維持相容性。只有在你明確想要立即覆寫路徑時才使用 --force。
openclaw gateway restart --safe --skip-deferral 會執行與 --safe 相同的 OpenClaw 感知協調式重新啟動，但會繞過作用中工作延遲閘門，因此即使回報阻擋項目，Gateway 也會立即發出重新啟動。當延遲被卡住的任務執行釘住，而單用 --safe 會無限期等待時，將其作為操作員逃生出口使用。--skip-deferral 需要 --safe。
啟動分析
- 設定
OPENCLAW_GATEWAY_STARTUP_TRACE=1可在 Gateway 啟動期間記錄各階段計時，包括每個階段的eventLoopMax延遲，以及已安裝索引、manifest registry、啟動規劃和 owner-map 工作的 Plugin 查找表計時。 - 設定
OPENCLAW_DIAGNOSTICS=timeline搭配OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>，可為外部 QA harness 寫入 best-effort JSONL 啟動診斷時間軸。你也可以在設定中使用diagnostics.flags: ["timeline"]啟用該旗標；路徑仍由 env 提供。加入OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1可包含 event-loop 樣本。 - 執行
pnpm test:startup:gateway -- --runs 5 --warmup 1以基準測試 Gateway 啟動。該基準會記錄第一個程序輸出、/healthz、/readyz、啟動追蹤計時、event-loop 延遲，以及 Plugin 查找表計時詳細資料。
查詢執行中的 Gateway
所有查詢命令都使用 WebSocket RPC。- 輸出模式
- 共用選項
- 預設：人類可讀（在 TTY 中著色）。
--json：機器可讀 JSON（無樣式/spinner）。--no-color（或NO_COLOR=1）：停用 ANSI，同時保留人類版面配置。
當你設定
--url 時，CLI 不會退回使用設定檔或環境憑證。請明確傳入 --token 或 --password。缺少明確憑證會造成錯誤。gateway health
/healthz 端點是存活探測：伺服器能回應 HTTP 後就會返回。HTTP /readyz 端點較嚴格，在啟動中的 Plugin 附屬程序、通道或已設定的 Hook 仍在就緒期間會保持紅色。本機或已驗證的詳細就緒回應包含 eventLoop 診斷區塊，內有事件迴圈延遲、事件迴圈使用率、CPU 核心比率，以及 degraded 旗標。
gateway usage-cost
從工作階段記錄擷取使用成本摘要。
要包含的天數。
gateway stability
從執行中的 Gateway 擷取最近的診斷穩定性記錄器。
要包含的近期事件數量上限（最大
1000）。依診斷事件類型篩選，例如
payload.large 或 diagnostic.memory.pressure。只包含某個診斷序號之後的事件。
讀取已持久化的穩定性套件組合，而不是呼叫執行中的 Gateway。使用
--bundle latest（或只用 --bundle）讀取狀態目錄下最新的套件組合，或直接傳入套件組合 JSON 路徑。寫入可分享的支援診斷 zip，而不是列印穩定性詳細資料。
--export 的輸出路徑。隱私權與套件組合行為
隱私權與套件組合行為
gateway diagnostics export
寫入本機診斷 zip，設計用於附加到錯誤回報。關於隱私權模型和套件組合內容，請參閱診斷匯出。
輸出 zip 路徑。預設為狀態目錄下的支援匯出。
要包含的已清理記錄行數上限。
要檢查的記錄位元組數上限。
用於健康快照的 Gateway WebSocket URL。
用於健康快照的 Gateway 權杖。
用於健康快照的 Gateway 密碼。
狀態/健康快照逾時。
跳過已持久化穩定性套件組合查找。
以 JSON 列印寫入路徑、大小和資訊清單。
gateway status
gateway status 會顯示 Gateway 服務（launchd/systemd/schtasks），並可選擇性探測連線能力/驗證能力。
加入明確的探測目標。仍會探測已設定的遠端 + localhost。
探測用的權杖驗證。
探測用的密碼驗證。
探測逾時。
略過連線能力探測（僅服務檢視）。
也掃描系統層級服務。
將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零狀態碼結束。不可與
--no-probe 搭配使用。狀態語意
狀態語意
- 即使本機 CLI 設定遺失或無效，
gateway status仍可用於診斷。 - 預設的
gateway status會證明服務狀態、WebSocket 連線，以及握手時可見的驗證能力。它不會證明讀取／寫入／管理員操作。 - 對於首次裝置驗證，診斷探測不會進行變更：如果既有快取裝置權杖存在，它們會重用該權杖，但不會只為了檢查狀態而建立新的 CLI 裝置身分或唯讀裝置配對記錄。
- 可行時，
gateway status會解析已設定的驗證 SecretRefs 以供探測驗證使用。 - 如果必要的驗證 SecretRef 在此命令路徑中未解析，當探測連線能力／驗證失敗時，
gateway status --json會回報rpc.authWarning；請明確傳入--token/--password，或先解析秘密來源。 - 如果探測成功，未解析的驗證參照警告會被抑制，以避免誤報。
- 當正在監聽的服務還不夠，並且你也需要讀取範圍的 RPC 呼叫保持健康時，請在指令碼和自動化中使用
--require-rpc。 --deep會加入對額外 launchd/systemd/schtasks 安裝的最佳努力掃描。偵測到多個類似 Gateway 的服務時，人類可讀輸出會列印清理提示，並警告多數設定應在每台機器上只執行一個 Gateway。- 當服務程序為了外部監督器重新啟動而乾淨結束時，
--deep也會回報近期的 Gateway 監督器重新啟動交接。 --deep會以 Plugin 感知模式（pluginValidation: "full"）執行設定驗證，並呈現已設定 Plugin manifest 警告（例如缺少頻道設定中繼資料），讓安裝和更新冒煙檢查能捕捉到這些問題。預設的gateway status會維持略過 Plugin 驗證的快速唯讀路徑。- 人類可讀輸出包含已解析的檔案記錄路徑，以及 CLI 與服務設定路徑／有效性快照，用來協助診斷 profile 或 state-dir 漂移。
Linux systemd 驗證漂移檢查
Linux systemd 驗證漂移檢查
- 在 Linux systemd 安裝中，服務驗證漂移檢查會從 unit 讀取
Environment=和EnvironmentFile=值（包含%h、加引號的路徑、多個檔案，以及選用的-檔案）。 - 漂移檢查會使用合併後的執行階段 env（先使用服務命令 env，再回退到程序 env）解析
gateway.auth.tokenSecretRefs。 - 如果權杖驗證實際上未啟用（明確的
gateway.auth.mode為password/none/trusted-proxy，或模式未設定且密碼可能勝出、沒有權杖候選可勝出），權杖漂移檢查會略過設定權杖解析。
gateway probe
gateway probe 是「偵錯所有項目」命令。它一律會探測：
- 你已設定的遠端 Gateway（如果已設定），以及
- localhost（loopback），即使已設定遠端。
--url，該明確目標會被加入到兩者之前。人類可讀輸出會將目標標示為：
URL (explicit)Remote (configured)或Remote (configured, inactive)Local loopback
如果多個 Gateway 可連線，它會全部列印出來。當你使用隔離的 profile／連接埠時（例如救援 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：此探測輪次實際使用的探索預算／結果數。
targets[].connect）：ok：連線後加上降級分類的可連線性。rpcOk：完整詳細 RPC 成功。scopeLimited：詳細 RPC 因缺少 operator scope 而失敗。
targets[].auth）：role：可用時，在hello-ok中回報的驗證角色。scopes：可用時，在hello-ok中回報的已授予 scopes。capability：該目標呈現的驗證能力分類。
常見警告代碼
常見警告代碼
ssh_tunnel_failed：SSH tunnel 設定失敗；命令已回退到直接探測。multiple_gateways：有多個目標可連線；除非你刻意執行隔離的 profile，例如救援 bot，否則這並不常見。auth_secretref_unresolved：無法為失敗目標解析已設定的驗證 SecretRef。probe_scope_limited：WebSocket 連線成功，但讀取探測因缺少operator.read而受限。
透過 SSH 遠端（Mac app 對等功能）
macOS app 的「透過 SSH 遠端」模式使用本機連接埠轉送，讓遠端 Gateway（可能只綁定到 loopback）能在ws://127.0.0.1:<port> 連線。
CLI 對等命令：
user@host 或 user@host:port（連接埠預設為 22）。身分檔案。
從已解析的探索端點（
local. 加上已設定的廣域網域，如果有）選取第一個發現的 Gateway 主機作為 SSH 目標。會忽略僅 TXT 的提示。gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
低階 RPC 輔助工具。
params 的 JSON 物件字串。
Gateway WebSocket URL。
Gateway 權杖。
Gateway 密碼。
逾時預算。
主要用於代理風格的 RPC，這類 RPC 會在最終 payload 前串流中間事件。
機器可讀 JSON 輸出。
--params 必須是有效的 JSON。管理 Gateway 服務
使用 wrapper 安裝
當受管理服務必須透過另一個可執行檔啟動時，請使用--wrapper，例如
秘密管理器 shim 或 run-as 輔助工具。wrapper 會接收一般 Gateway 參數，並
負責最終以這些參數 exec openclaw 或 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 restart：--safe、--skip-deferral、--force、--wait <duration>、--jsongateway uninstall|start：--jsongateway stop：--disable、--json
生命週期行為
生命週期行為
- 使用
gateway restart重新啟動受管理的服務。請勿將gateway stop和gateway start串接起來，當作重新啟動的替代做法。 - 在 macOS 上，
gateway stop預設使用launchctl bootout，這會從目前的開機工作階段移除 LaunchAgent，但不會持續保留停用狀態 — KeepAlive 自動復原在未來當機時仍會保持啟用，且gateway start可乾淨地重新啟用，無須手動執行launchctl enable。傳入--disable可持續抑制 KeepAlive 和 RunAtLoad，讓 gateway 在下一次明確執行gateway start前不會重新產生；當手動停止應該在重新開機或系統重新啟動後仍維持有效時，請使用此選項。 gateway restart --safe會要求正在執行的 Gateway 預先檢查進行中的 OpenClaw 工作，並延後重新啟動，直到回覆送達、嵌入式執行和任務執行都排空為止。--safe不能與--force或--wait合併使用。gateway restart --wait 30s會覆寫該次重新啟動的已設定重新啟動排空預算。未加單位的數字是毫秒；也接受s、m和h等單位。--wait 0會無限期等待。gateway restart --safe --skip-deferral會執行具備 OpenClaw 感知能力的安全重新啟動，但略過延後閘門，因此即使回報阻擋項目，Gateway 也會立即發出重新啟動。這是供操作者在任務執行延後卡住時使用的逃生選項；需要--safe。gateway restart --force會略過作用中工作排空並立即重新啟動。當操作者已經檢查列出的任務阻擋項目，並希望 gateway 立刻恢復時使用。- 生命週期命令接受
--json以供腳本使用。
安裝時的驗證與 SecretRefs
安裝時的驗證與 SecretRefs
- 當 token 驗證需要 token，且
gateway.auth.token由 SecretRef 管理時，gateway install會驗證該 SecretRef 可解析，但不會將已解析的 token 持續寫入服務環境中繼資料。 - 如果 token 驗證需要 token，而已設定的 token SecretRef 無法解析，安裝會以關閉方式失敗，而不是持續寫入備援明文。
- 對於
gateway run上的密碼驗證，請優先使用OPENCLAW_GATEWAY_PASSWORD、--password-file，或由 SecretRef 支援的gateway.auth.password，而不是內嵌的--password。 - 在推斷驗證模式中，僅存在於 shell 的
OPENCLAW_GATEWAY_PASSWORD不會放寬安裝 token 需求；安裝受管理服務時，請使用持久設定（gateway.auth.password或設定env）。 - 如果同時設定了
gateway.auth.token和gateway.auth.password，且未設定gateway.auth.mode，安裝會被封鎖，直到明確設定 mode。
探索 gateway（Bonjour）
gateway discover 會掃描 Gateway beacon（_openclaw-gw._tcp）。
- 多播 DNS-SD：
local. - 單播 DNS-SD（廣域 Bonjour）：選擇一個網域（範例：
openclaw.internal.），並設定 split DNS + DNS 伺服器；請參閱 Bonjour。
role（gateway 角色提示）transport（傳輸提示，例如gateway）gatewayPort（WebSocket 連接埠，通常是18789）sshPort（僅限完整探索模式；不存在時，客戶端預設 SSH 目標為22）tailnetDns（MagicDNS 主機名稱，可用時）gatewayTls/gatewayTlsSha256（已啟用 TLS + 憑證指紋）cliPath（僅限完整探索模式）
gateway discover
單一命令逾時（瀏覽/解析）。
機器可讀輸出（也會停用樣式/spinner）。
- CLI 會掃描
local.，並在已啟用廣域網域時一併掃描已設定的廣域網域。 - JSON 輸出中的
wsUrl是從已解析的服務端點衍生，而不是來自僅存在於 TXT 的提示，例如lanHost或tailnetDns。 - 在
local.mDNS 和廣域 DNS-SD 上，只有當discovery.mdns.mode為full時，才會發布sshPort和cliPath。