openclaw gateway ... 之下。
Bonjour discovery
本機 mDNS + 廣域 DNS-SD 設定。
Discovery overview
OpenClaw 如何宣告並尋找閘道。
Configuration
頂層閘道設定鍵。
執行閘道
Startup behavior
Startup behavior
- 除非
~/.openclaw/openclaw.json中已設定gateway.mode=local，否則會拒絕啟動。針對臨時/開發執行可使用--allow-unconfigured；它會略過防護，但不會寫入或修復設定。 openclaw onboard --mode local和openclaw setup會寫入gateway.mode=local。如果設定檔存在但缺少gateway.mode，會被視為損壞/遭覆寫的設定，閘道不會替你猜測local；請重新執行上線設定、手動設定該鍵，或傳入--allow-unconfigured。- 未使用驗證時，會阻擋超出 loopback 的綁定。
--bind值lan、tailnet和custom目前會透過僅 IPv4 路徑解析；僅 IPv6 的自帶主機設定需要在閘道前方放置 IPv4 sidecar 或 proxy。- 授權時，
SIGUSR1會觸發程序內重新啟動。commands.restart（預設：啟用）會控管外部送出的SIGUSR1；將它設為false可阻擋手動 OS 訊號重新啟動，同時仍允許透過gateway restart命令、閘道工具，以及設定套用/更新來重新啟動。 SIGINT/SIGTERM會停止程序，但不會還原自訂終端機狀態；如果你將命令列介面包在終端介面或 raw-mode 輸入中，請在結束前自行還原終端機。
選項
WebSocket 連接埠（預設來自設定/env；通常是
18789）。綁定模式：
loopback（預設）、lan、tailnet、auto、custom。connect.params.auth.token 的共享權杖。設定時預設為 OPENCLAW_GATEWAY_TOKEN。驗證模式：
none、token、password、trusted-proxy。--auth password 的密碼。從檔案讀取閘道密碼。
Tailscale 暴露方式：
off、serve、funnel。關閉時重設 Tailscale serve/funnel 設定。
不強制
gateway.mode=local 即啟動。僅供臨時/開發 bootstrap 使用；不會持久化或修復設定。若缺少開發設定 + 工作區，則建立它們（略過
BOOTSTRAP.md）。重設開發設定、憑證、工作階段和工作區。需要
--dev。啟動前先終止目標連接埠上任何既有 listener。
將詳細記錄輸出到 stdout/stderr。
只在主控台顯示命令列介面後端記錄（也會啟用 stdout/stderr）。
WebSocket 記錄樣式：
auto、full、compact。--ws-log compact 的別名。將原始模型串流事件記錄到 JSONL。
原始串流 JSONL 路徑。
--claude-cli-logs 是 --cli-backend-logs 的已棄用別名。
對於 --bind custom，請將 gateway.customBindHost 設為 IPv4 位址；如果該位址不可用，閘道會退回到 0.0.0.0。僅 IPv6 的自帶主機設定需要在閘道前方放置 IPv4 sidecar 或 proxy。
重新啟動閘道
--safe 會要求執行中的閘道預先檢查作用中的工作，並在該工作排空後排程一次合併的重新啟動。等待時間受 gateway.reload.deferralTimeoutMs 限制（預設：5 分鐘 / 300000）；當預算用盡時會強制重新啟動。將 deferralTimeoutMs: 0 設為無限期等待（並定期發出仍在等待的警告），而不是強制執行。--safe 不能與 --force 或 --wait 搭配使用。
--skip-deferral 會在安全重新啟動時略過作用中工作延遲門檻，因此即使回報了 blocker，閘道也會立即重新啟動。它需要 --safe；當延遲卡在失控工作上時使用。
--wait <duration> 會覆寫一般（非 safe）重新啟動的排空預算。接受裸毫秒或單位後綴 ms、s、m、h、d（例如 30s、5m、1h30m）；--wait 0 會無限期等待。與 --force 或 --safe 不相容。
--force 會略過作用中工作排空並立即重新啟動。一般 restart（沒有旗標）會保留既有 service-manager 重新啟動行為。
閘道 profiling
OPENCLAW_GATEWAY_STARTUP_TRACE=1會在啟動期間記錄階段計時，包括每個階段的eventLoopMax延遲與外掛 lookup-table 計時（installed-index、manifest registry、startup planning、owner-map work）。OPENCLAW_GATEWAY_RESTART_TRACE=1會記錄重新啟動範圍的restart trace:行：訊號處理、作用中工作排空、關閉階段、下一次啟動、就緒計時，以及記憶體指標。OPENCLAW_DIAGNOSTICS=timeline搭配OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>，會為外部 QA harness 寫入 best-effort JSONL 啟動診斷 timeline（等同於設定diagnostics.flags: ["timeline"]；路徑仍僅能透過 env 設定）。加入OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1可包含 event-loop samples。pnpm build然後pnpm test:startup:gateway -- --runs 5 --warmup 1會以已建置的命令列介面進入點 benchmark 閘道啟動：第一個程序輸出、/healthz、/readyz、啟動 trace 計時、event-loop 延遲，以及外掛 lookup-table 計時。pnpm build然後pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5會在 macOS 或 Linux 上 benchmark 程序內重新啟動（Windows 不支援；重新啟動需要SIGUSR1）。使用SIGUSR1、在子程序中啟用兩種 trace，並記錄下一個/healthz、下一個/readyz、停機時間、就緒計時、CPU、RSS，以及重新啟動 trace 指標。/healthz是 liveness；/readyz是可用 readiness。請將 trace 行和 benchmark 輸出視為 owner-attribution 訊號，而不是來自單一 span 或 sample 的完整效能結論。
查詢執行中的閘道
所有查詢命令都使用 WebSocket RPC。- Output modes
- 預設：人類可讀（TTY 中有色彩）。
--json：機器可讀 JSON（無樣式/spinner）。--no-color（或NO_COLOR=1）：停用 ANSI，同時保留人類版面配置。
當你設定
--url 時，命令列介面不會退回使用設定或環境憑證。請明確傳入 --token 或 --password。缺少明確憑證會導致錯誤。gateway health
/healthz 是 liveness probe：只要伺服器能回應 HTTP 就會傳回。/readyz 更嚴格，當啟動外掛 sidecar、通道或已設定掛鉤仍在穩定時會維持紅燈。本機或已驗證的詳細 /readyz 回應會包含 eventLoop 診斷區塊（延遲、使用率、CPU-core ratio、degraded 旗標）。
以此連接埠上的 local loopback 閘道為目標。針對此呼叫覆寫
OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_PORT。gateway usage-cost
從工作階段記錄擷取 usage-cost 摘要。
要納入的天數。
將摘要範圍限定為一個已設定的 agent id。
彙總所有已設定的 agent。不能與
--agent 搭配使用。gateway stability
從執行中的閘道擷取最近的診斷穩定性 recorder。
要納入的最近事件上限（最大
1000）。依診斷事件類型篩選，例如
payload.large 或 diagnostic.memory.pressure。只納入診斷序號之後的事件。
讀取已持久化的穩定性 bundle，而不是呼叫執行中的閘道。
--bundle latest（或裸 --bundle）會選擇狀態目錄下最新的 bundle；你也可以直接傳入 bundle JSON 路徑。寫入可共享的支援診斷 zip，而不是列印穩定性詳細資料。
--export 的輸出路徑。Privacy and bundle behavior
Privacy and bundle behavior
- 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、queue/session 狀態、approval id、通道/外掛名稱，以及已遮蔽的工作階段摘要。它們會排除聊天文字、webhook bodies、工具輸出、原始 request/response bodies、權杖、cookies、secret values、主機名稱，以及原始 session id。設定
diagnostics.enabled: false可完全停用 recorder。 - 致命閘道結束、關閉逾時與重新啟動啟動失敗，會在 recorder 有事件時將相同診斷快照寫入
~/.openclaw/logs/stability/openclaw-stability-*.json。使用openclaw gateway stability --bundle latest檢查最新 bundle；--limit、--type和--since-seq也會套用於 bundle 輸出。
gateway diagnostics export
寫入為 bug report 設計的本機診斷 zip。如需隱私模型與 bundle 內容，請見 診斷匯出。
輸出 zip 路徑。預設為狀態目錄下的支援匯出。
要包含的已清理敏感資訊記錄行數上限。
要檢查的記錄位元組數上限。
健康快照的閘道 WebSocket URL。
健康快照的閘道 token。
健康快照的閘道密碼。
狀態/健康快照逾時。
略過已持久化的穩定性套件組合查詢。
以 JSON 列印已寫入路徑、大小與資訊清單。
manifest.json（檔案清單）、summary.md（Markdown 摘要）、diagnostics.json（頂層設定/記錄/探索/穩定性/狀態/健康摘要）、config/sanitized.json、status/gateway-status.json、health/gateway-health.json、logs/openclaw-sanitized.jsonl，以及存在套件組合時的 stability/latest.json。
它設計為可分享。它保留對除錯有用的操作細節，包括安全的記錄欄位、子系統名稱、狀態碼、持續時間、已設定模式、連接埠、外掛/提供者 ID、非機密功能設定，以及已遮蔽的操作記錄訊息，並省略或遮蔽聊天文字、網路鉤子本文、工具輸出、認證資料、Cookie、帳號/訊息識別碼、提示/指令文字、主機名稱與秘密值。當記錄訊息看起來像使用者/聊天/工具酬載文字（例如「user said」、「chat text」、「tool output」、「webhook body」）時，匯出只保留訊息已省略這件事及其位元組數。
gateway status
顯示閘道服務（launchd/systemd/schtasks）以及選用的連線能力/驗證探測。
加入明確的探測目標。已設定的遠端 + localhost 仍會被探測。
探測的 token 驗證。
探測的密碼驗證。
探測逾時。
略過連線能力探測（僅服務檢視）。
也掃描系統層級服務。
將連線能力探測升級為讀取探測，若失敗則以非零狀態碼結束。不能與
--no-probe 合併使用。狀態語意
狀態語意
- 即使本機命令列介面設定遺失或無效，仍可用於診斷。
- 預設輸出會證明服務狀態、WebSocket 連線，以及握手時可見的驗證能力，而不是讀取/寫入/管理員操作。
- 探測對首次裝置驗證不會變更狀態：當既有快取裝置 token 存在時會重用它，但絕不會只為了檢查狀態而建立新的命令列介面裝置身分或唯讀配對記錄。
- 可能時，會解析已設定的驗證 SecretRefs 作為探測驗證。如果必要的 SecretRef 無法解析，當探測連線能力/驗證失敗時，
--json會回報rpc.authWarning；請明確傳入--token/--password，或修正秘密來源。一旦探測成功，未解析驗證警告會被抑制。 - 當執行中的閘道回報版本時，JSON 輸出會包含
gateway.version；如果握手探測無法提供版本中繼資料，--require-rpc可退回使用status.runtimeVersionRPC 酬載。 - 在腳本/自動化中，如果只有服務正在監聽還不夠，且也需要讀取範圍 RPC 健康，請使用
--require-rpc。 --deep會掃描額外的 launchd/systemd/schtasks 安裝；當找到多個類似閘道的服務時，人類可讀輸出會列印清理提示（通常每台機器執行一個閘道），並在相關時回報最近的監督程式重新啟動交接。--deep也會以外掛感知模式（pluginValidation: "full"）執行設定驗證，並顯示外掛資訊清單警告（例如缺少通道設定中繼資料）。預設gateway status會保留快速唯讀路徑，略過外掛驗證。- 人類可讀輸出會包含已解析的檔案記錄路徑，以及命令列介面與服務設定路徑/有效性，以協助診斷設定檔或狀態目錄漂移。
Linux systemd 驗證漂移檢查
Linux systemd 驗證漂移檢查
- 服務驗證漂移檢查會從 unit 讀取
Environment=與EnvironmentFile=（包括%h、加上引號的路徑、多個檔案，以及選用的-檔案）。 - 使用合併後的執行時環境（先服務命令環境，然後程序環境後援）解析
gateway.auth.tokenSecretRefs。 - 當 token 驗證實際上未啟用時（
gateway.auth.mode明確為password/none/trusted-proxy，或模式未設定且密碼可勝出且沒有 token 候選可勝出），token 漂移檢查會略過設定 token 解析。
gateway probe
「除錯所有項目」命令。它一律探測：
- 你已設定的遠端閘道（如果已設定），以及
- localhost（loopback），即使已設定遠端。
--url 會把該明確目標加在兩者之前。人類可讀輸出會將目標標示為 URL (explicit)、Remote (configured) / Remote (configured, inactive)，以及 Local loopback。
如果多個探測目標可連線，全部都會列印。SSH tunnel、TLS/proxy URL 與已設定的遠端 URL 可以指向同一個閘道，即使使用不同傳輸連接埠；
multiple_gateways 保留給不同或身分模糊的可連線閘道。支援為隔離設定檔執行多個閘道（例如救援 bot），但大多數安裝會執行單一閘道。將此連接埠用於 local loopback 探測目標與 SSH tunnel 遠端連接埠。沒有
--url 時，這只會選取 local loopback 目標，而不是已設定的閘道環境 URL、環境連接埠或遠端目標。解讀
解讀
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 受限。回報為降級可連線性，而不是完整失敗。Read probe: failed在Connect: ok之後表示 WebSocket 已連線，但後續讀取診斷逾時或失敗，同樣是降級，不是無法連線。- 和
gateway status一樣，探測會重用既有快取裝置驗證，但不會建立首次裝置身分或配對狀態。 - 只有在沒有任何已探測目標可連線時，結束碼才會是非零。
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 範圍而失敗）。每個目標（targets[].auth）：可用時在 hello-ok 中回報的 role 與 scopes，以及顯示的 capability 分類。透過 SSH 遠端（Mac 應用程式等效性）
macOS 應用程式的「Remote over SSH」模式使用本機連接埠轉送，讓僅限 loopback 的遠端閘道可在ws://127.0.0.1:<port> 連線。
命令列介面等效：
user@host 或 user@host:port（連接埠預設為 22）。身分檔案。
從已解析的探索端點（
local. 加上已設定的廣域網域，如果有）選取第一個探索到的閘道主機作為 SSH 目標。僅 TXT 的提示會被忽略。gateway.remote.sshTarget、gateway.remote.sshIdentity。
gateway call <method>
低階 RPC 輔助工具。
參數的 JSON 物件字串。
閘道 WebSocket URL。
閘道 token。
閘道密碼。
逾時預算。
主要用於會在最終酬載之前串流中介事件的 agent 風格 RPC。
機器可讀的 JSON 輸出。
--params 必須是有效 JSON，且每個方法會驗證自己的參數形狀（額外/命名錯誤的欄位會被拒絕）。管理閘道服務
使用包裝器安裝
當受管理的服務必須透過另一個可執行檔啟動時，請使用--wrapper，例如秘密管理器 shim 或 run-as 輔助工具。包裝器會接收一般閘道參數，並負責最終以這些參數 exec openclaw 或節點。
gateway install 會驗證該路徑是可執行檔，將包裝器寫入服務的 ProgramArguments，並在服務環境中保留 OPENCLAW_WRAPPER，供後續強制重新安裝、更新與 doctor 修復使用。
OPENCLAW_WRAPPER：
命令選項
命令選項
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>（預設：node）、--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 start前不會重新產生；當手動停止需要在重新開機後仍然有效時，請使用此選項。 - 生命週期命令接受
--json以便撰寫指令碼。
安裝時的驗證與 SecretRefs
安裝時的驗證與 SecretRefs
- 當權杖驗證需要權杖，且
gateway.auth.token由 SecretRef 管理時，gateway install會驗證 SecretRef 可解析，但不會將解析後的權杖保留到服務環境中繼資料。 - 如果權杖驗證需要權杖，而已設定的權杖 SecretRef 無法解析，安裝會失敗關閉，而不是保留備援明文。
- 對於
gateway run上的密碼驗證，優先使用OPENCLAW_GATEWAY_PASSWORD、--password-file，或由 SecretRef 支援的gateway.auth.password，而不是行內--password。 - 在推斷驗證模式中，僅存在於 shell 的
OPENCLAW_GATEWAY_PASSWORD不會放寬安裝權杖需求；安裝受管理服務時，請使用持久設定（gateway.auth.password或設定env）。 - 如果同時設定了
gateway.auth.token和gateway.auth.password，且未設定gateway.auth.mode，安裝會被阻擋，直到明確設定模式為止。
探索閘道（Bonjour）
gateway discover 會掃描閘道信標（_openclaw-gw._tcp）。
- 多播 DNS-SD：
local. - 單播 DNS-SD（廣域 Bonjour）：選擇一個網域（範例：
openclaw.internal.）並設定 split DNS + DNS 伺服器；請參閱 Bonjour。
role（閘道角色提示）、transport（傳輸提示，例如 gateway）、gatewayPort（WebSocket 連接埠，通常是 18789）、tailnetDns（MagicDNS 主機名稱，可用時）、gatewayTls / gatewayTlsSha256（TLS 已啟用 + 憑證指紋）。sshPort 和 cliPath 只會在完整探索模式中發布（discovery.mdns.mode: "full"；預設是 "minimal"，會省略它們；用戶端接著會將預設 SSH 目標設為連接埠 22）。
gateway discover
每個命令的逾時時間（瀏覽/解析）。
機器可讀輸出（也會停用樣式/旋轉器）。
- 會掃描
local.，以及啟用時已設定的廣域網域。 - JSON 輸出中的
wsUrl來自解析後的服務端點，而不是僅存在於 TXT 的提示，例如lanHost或tailnetDns。 discovery.mdns.mode控制local.mDNS 和廣域 DNS-SD 上的sshPort/cliPath發布（見上文）。