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，請在結束前還原終端機。

• 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/Plugin 名稱，以及已修訂的工作階段摘要。它們不會保留聊天文字、Webhook 內容、工具輸出、原始請求或回應內容、權杖、Cookie、祕密值、主機名稱，或原始工作階段 ID。設定 diagnostics.enabled: false 可完全停用記錄器。
• 在 Gateway 發生致命結束、關機逾時，以及重新啟動期間啟動失敗時，如果記錄器有事件，OpenClaw 會將相同的診斷快照寫入 ~/.openclaw/logs/stability/openclaw-stability-*.json。使用 openclaw gateway stability --bundle latest 檢查最新的套件組合；--limit、--type 和 --since-seq 也適用於套件組合輸出。

• 即使本機 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 安裝中，服務驗證漂移檢查會從 unit 讀取 Environment= 和 EnvironmentFile= 值（包含 %h、加引號的路徑、多個檔案，以及選用的 - 檔案）。
• 漂移檢查會使用合併後的執行階段 env（先使用服務命令 env，再回退到程序 env）解析 gateway.auth.token SecretRefs。
• 如果權杖驗證實際上未啟用（明確的 gateway.auth.mode 為 password/none/trusted-proxy，或模式未設定且密碼可能勝出、沒有權杖候選可勝出），權杖漂移檢查會略過設定權杖解析。

• 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 會重用既有快取裝置驗證，但不會建立首次裝置身分或配對狀態。
• 只有在沒有任何被探測目標可連線時，結束碼才會是非零。

頂層：

• 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 而受限。

• gateway status：--url、--token、--password、--timeout、--no-probe、--require-rpc、--deep、--json
• gateway install：--port、--runtime <node|bun>、--token、--wrapper <path>、--force、--json
• gateway restart：--safe、--skip-deferral、--force、--wait <duration>、--json
• gateway uninstall|start：--json
• gateway 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 以供腳本使用。

• 當 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。