Gateway

Gateway 是 OpenClaw 的 WebSocket 伺服器（頻道、節點、工作階段、hook）。本頁中的子命令位於 openclaw gateway … 之下。

# 執行 Gateway

執行本機 Gateway 處理程序：

openclaw gateway

前景別名：

openclaw gateway run

# 選項

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> WebSocket 連接埠（預設值來自設定/env；通常是 18789）。

"--bind

"--auth

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> token 覆寫（也會為處理程序設定 OPENCLAW_GATEWAY_TOKEN）。

"--password

"--tailscale

--tailscale-reset-on-exitboolean

關閉時重設 Tailscale serve/funnel 設定。

--allow-unconfiguredboolean

允許 Gateway 在設定中沒有 gateway.mode=local 時啟動。僅針對臨時/開發啟動繞過啟動防護；不會寫入或修復設定檔。

--devboolean

若缺少則建立開發設定 + 工作區（略過 BOOTSTRAP.md）。

--resetboolean

重設開發設定 + 憑證 + 工作階段 + 工作區（需要 --dev）。

--forceboolean

啟動前終止所選連接埠上的任何既有監聽器。

--verboseboolean

詳細記錄。

--cli-backend-logsboolean

僅在主控台顯示 CLI 後端記錄（並啟用 stdout/stderr）。

"--ws-log

--compactboolean

--ws-log compact 的別名。

--raw-streamboolean

將原始模型串流事件記錄到 jsonl。

# 重新啟動 Gateway

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --force

openclaw gateway restart --safe 會要求執行中的 Gateway 在重新啟動前預先檢查作用中的 OpenClaw 工作。如果佇列作業、回覆傳遞、嵌入式執行或任務執行仍在作用中，Gateway 會回報阻擋項目、合併重複的安全重新啟動要求，並在作用中工作排空後重新啟動。一般 restart 會保留既有的服務管理器行為以維持相容性。只有在你明確想要立即覆寫路徑時才使用 --force。

# 啟動分析

• 設定 OPENCLAW_GATEWAY_STARTUP_TRACE=1，可在 Gateway 啟動期間記錄階段計時，包括每個階段的 eventLoopMax 延遲，以及已安裝索引、manifest registry、啟動規劃和 owner-map 工作的 Plugin 查找表計時。
• 設定 OPENCLAW_DIAGNOSTICS=timeline 搭配 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>，可為外部 QA harness 寫入盡力而為的 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。

# gateway health

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

HTTP /healthz 端點是存活探針：伺服器能回應 HTTP 時就會傳回。HTTP /readyz 端點更嚴格，會在啟動中的 Plugin sidecar、頻道或已設定 hook 仍在穩定期間保持紅色。本機或已驗證的詳細就緒狀態回應會包含 eventLoop 診斷區塊，其中包括事件迴圈延遲、事件迴圈使用率、CPU 核心比率，以及 degraded 旗標。

# gateway usage-cost

從工作階段記錄擷取使用成本摘要。

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

"--days

# gateway stability

從執行中的 Gateway 擷取近期診斷穩定性記錄器。

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tbGltaXQgPGxpbWl0 " type="number" default="25"> 要包含的近期事件數量上限（最大 1000）。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdHlwZSA8dHlwZQ " type="string"> 依診斷事件類型篩選，例如 payload.large 或 diagnostic.memory.pressure。

"--since-seq

--bundle [path]string

讀取已保存的穩定性 bundle，而不是呼叫執行中的 Gateway。使用 --bundle latest（或只用 --bundle）讀取狀態目錄下最新的 bundle，或直接傳入 bundle JSON 路徑。

--exportboolean

寫入可分享的支援診斷 zip，而不是列印穩定性細節。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tb3V0cHV0IDxwYXRo " type="string"> --export 的輸出路徑。

# gateway diagnostics export

寫入本機診斷 zip，其設計用途是附加到錯誤報告。關於隱私模型和 bundle 內容，請參閱 Diagnostics Export。

openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json

"--log-lines

"--log-bytes

"--url

"--token

"--password

"--timeout

--no-stability-bundleboolean

略過已保存穩定性 bundle 查找。

--jsonboolean

以 JSON 列印已寫入的路徑、大小和 manifest。

此匯出包含 manifest、Markdown 摘要、設定形狀、已清理的設定細節、已清理的記錄摘要、已清理的 Gateway 狀態/健康狀態快照，以及存在時的最新穩定性 bundle。

它設計為可分享。它會保留有助於偵錯的作業細節，例如安全的 OpenClaw 記錄欄位、子系統名稱、狀態碼、持續時間、已設定模式、連接埠、Plugin ID、提供者 ID、非秘密功能設定，以及已遮蔽的作業記錄訊息。它會省略或遮蔽聊天文字、webhook 內文、工具輸出、憑證、cookie、帳號/訊息識別碼、提示/指令文字、主機名稱和秘密值。當 LogTape 風格訊息看起來像使用者/聊天/工具 payload 文字時，匯出只會保留訊息已被省略的事實及其位元組計數。

# gateway status

gateway status 會顯示 Gateway 服務（launchd/systemd/schtasks），以及選用的連線能力/驗證能力探針。

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

"--url

"--token

"--password

"--timeout

--no-probeboolean

略過連線能力探測（僅服務檢視）。

--deepboolean

也掃描系統層級服務。

--require-rpcboolean

將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零狀態結束。不能與 --no-probe 搭配使用。

# gateway probe

gateway probe 是「偵錯所有內容」命令。它一律會探測：

• 你已設定的遠端 Gateway（如果已設定），以及
• localhost（loopback），即使已設定遠端。

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

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

openclaw gateway probe
openclaw gateway probe --json

# 透過 SSH 遠端（Mac 應用程式一致性）

macOS 應用程式的「透過 SSH 遠端」模式會使用本機連接埠轉送，讓遠端 Gateway（可能僅繫結至 loopback）可在 ws://127.0.0.1:<port> 連線。

CLI 等效命令：

openclaw gateway probe --ssh user@gateway-host

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc3NoIDx0YXJnZXQ " type="string"> user@host 或 user@host:port（連接埠預設為 22）。

--ssh-autoboolean

從已解析的探索端點（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

"--url

"--token

"--password

"--timeout

--expect-finalboolean

主要用於會在最終承載前串流中間事件的 agent 風格 RPC。

--jsonboolean

機器可讀 JSON 輸出。

# 管理 Gateway 服務

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

# 使用包裝器安裝

當受管理服務必須透過另一個可執行檔啟動時，請使用 --wrapper，例如 祕密管理器 shim 或 run-as 輔助工具。包裝器會接收一般 Gateway 引數，並且 負責最終以這些引數 exec openclaw 或 Node。

cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart

你也可以透過環境設定包裝器。gateway install 會驗證路徑是 可執行檔，將包裝器寫入服務 ProgramArguments，並在服務環境中持久化 OPENCLAW_WRAPPER，供後續強制重新安裝、更新與 doctor 修復使用。

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor

若要移除持久化包裝器，請在重新安裝時清除 OPENCLAW_WRAPPER：

OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart

# 探索 Gateway (Bonjour)

gateway discover 會掃描 Gateway 信標（_openclaw-gw._tcp）。

• 多播 DNS-SD：local.
• 單播 DNS-SD（廣域 Bonjour）：選擇一個網域（範例：openclaw.internal.），並設定 split DNS + DNS 伺服器；請參閱 Bonjour。

只有啟用 Bonjour 探索（預設）的 Gateway 會公告信標。

廣域探索記錄包含 (TXT)：

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

# gateway discover

openclaw gateway discover

"--timeout

--jsonboolean

機器可讀輸出（也會停用樣式/旋轉指示器）。

範例：

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

# 相關

• CLI 參考
• Gateway runbook