Gateway CLI

Gateway 是 OpenClaw 的 WebSocket 伺服器（頻道、節點、工作階段、hooks）。

本頁的子指令都位於 openclaw gateway ... 之下。

相關文件：

• /gateway/bonjour
• /gateway/discovery
• /gateway/configuration

執行 Gateway

執行本地 Gateway 處理程序：

openclaw gateway

前景模式別名：

openclaw gateway run

注意事項：

• 預設情況下，除非 ~/.openclaw/openclaw.json 中設定了 gateway.mode=local，否則 Gateway 拒絕啟動。臨時/開發執行可使用 --allow-unconfigured。
• 綁定至非迴路位址但未啟用驗證時會被阻擋（安全防護）。
• SIGUSR1 會在授權時觸發進程內重啟（commands.restart 預設啟用；設定 commands.restart: false 可阻擋手動重啟，但 gateway 工具/設定套用/更新仍然允許）。
• SIGINT/SIGTERM 處理器會停止 Gateway 處理程序，但不會恢復任何自訂終端機狀態。如果你用 TUI 或 raw-mode 輸入包裝 CLI，請在離開前恢復終端機。

選項

• --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 的情況下啟動 Gateway。
• --dev：如缺少則建立開發設定 + 工作區（跳過 BOOTSTRAP.md）。
• --reset：重設開發設定 + 憑證 + 工作階段 + 工作區（需搭配 --dev）。
• --force：啟動前殺掉佔用所選連接埠的既有監聽器。
• --verbose：詳細日誌。
• --claude-cli-logs：只在主控台顯示 claude-cli 日誌（並啟用其 stdout/stderr）。
• --ws-log <auto|full|compact>：WebSocket 日誌風格（預設 auto）。
• --compact：--ws-log compact 的別名。
• --raw-stream：將原始模型串流事件記錄至 jsonl。
• --raw-stream-path <path>：原始串流 jsonl 路徑。

查詢執行中的 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

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

gateway status

gateway status 顯示 Gateway 服務（launchd/systemd/schtasks）加上選用的 RPC 探測。

openclaw gateway status
openclaw gateway status --json

選項：

• --url <url>：覆蓋探測 URL。
• --token <token>：探測的 token 驗證。
• --password <password>：探測的密碼驗證。
• --timeout <ms>：探測逾時（預設 10000）。
• --no-probe：跳過 RPC 探測（僅服務檢視）。
• --deep：同時掃描系統層級的服務。

注意事項：

• gateway status 會在可能時解析已設定的驗證 SecretRef 用於探測。
• 如果必要的驗證 SecretRef 在目前指令路徑中無法解析，探測驗證可能失敗；請明確傳入 --token/--password 或先解析密碼來源。
• 在 Linux systemd 安裝中，服務驗證飄移檢查會讀取 unit 中的 Environment= 和 EnvironmentFile= 值（包含 %h、引號路徑、多個檔案和選用的 - 檔案）。

gateway probe

gateway probe 是「偵錯一切」的指令。它一律探測：

• 你設定的遠端 Gateway（若已設定），以及
• localhost（迴路），即使已設定遠端也會探測。

如果有多個 Gateway 可連線，它會全部列出。使用隔離的 profile/連接埠（例如救援機器人）時支援多個 Gateway，但多數安裝仍只執行單一 Gateway。

openclaw gateway probe
openclaw gateway probe --json

透過 SSH 遠端連線（Mac app 對等）

macOS app 的「Remote over SSH」模式使用本地連接埠轉發，讓遠端 Gateway（可能只綁定至迴路）可在 ws://127.0.0.1:<port> 連線。

CLI 對等指令：

openclaw gateway probe --ssh user@gateway-host

選項：

• --ssh <target>：user@host 或 user@host:port（port 預設為 22）。
• --ssh-identity <path>：身分檔案。
• --ssh-auto：自動選取第一個探索到的 Gateway 主機作為 SSH 目標（僅限 LAN/WAB）。

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

• gateway.remote.sshTarget
• gateway.remote.sshIdentity

gateway call <method>

底層 RPC 輔助工具。

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

管理 Gateway 服務

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

注意事項：

• gateway install 支援 --port、--runtime、--token、--force、--json。
• 當 token 驗證需要 token 且 gateway.auth.token 是 SecretRef 管理的，gateway install 會驗證 SecretRef 是否可解析，但不會將已解析的 token 寫入服務環境的中繼資料。
• 如果 token 驗證需要 token 但已設定的 token SecretRef 無法解析，install 會直接拒絕而非寫入後備明文。
• 使用密碼驗證執行 gateway run 時，建議使用 OPENCLAW_GATEWAY_PASSWORD、--password-file 或 SecretRef 支持的 gateway.auth.password，優於內嵌的 --password。
• 在推斷的驗證模式下，僅存在於 shell 中的 OPENCLAW_GATEWAY_PASSWORD/CLAWDBOT_GATEWAY_PASSWORD 不會放寬 install 的 token 要求；安裝受管理的服務時請使用持久化設定（gateway.auth.password 或 config env）。
• 如果 gateway.auth.token 和 gateway.auth.password 都已設定但 gateway.auth.mode 未設定，install 會被阻擋，直到明確設定 mode。
• 生命週期指令支援 --json 以便在腳本中使用。

探索 Gateway（Bonjour）

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

• 多播 DNS-SD：local.
• 單播 DNS-SD（廣域 Bonjour）：選擇一個網域（例如 openclaw.internal.）並設定 split 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

openclaw gateway discover

選項：

• --timeout <ms>：每指令逾時（瀏覽/解析）；預設 2000。
• --json：機器可讀輸出（同時停用樣式/旋轉圖示）。

範例：

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