Gateway 操作手冊

這份文件涵蓋 Gateway 服務的初次啟動與日常維運。

  • 深度疑難排解 — 從症狀出發的診斷流程，附帶具體指令和日誌特徵。
  • 設定 — 任務導向的設定指南 + 完整設定參考。
  • Secrets 管理 — SecretRef 合約、執行期快照行為，以及 migrate/reload 操作。
  • Secrets plan 合約 — secrets apply 的確切 target/path 規則和 ref-only auth-profile 行為。

5 分鐘本地啟動

第一步：啟動 Gateway

openclaw gateway --port 18789
# debug/trace 同步輸出到終端
openclaw gateway --port 18789 --verbose
# 強制終止指定埠上的監聽器後再啟動
openclaw gateway --force

第二步：驗證服務健康

openclaw gateway status
openclaw status
openclaw logs --follow

健康基線：Runtime: running 且 RPC probe: ok。

第三步：確認頻道就緒

openclaw channels status --probe

注意： Gateway 設定重載會監聽活躍的設定檔路徑（從 profile/state 預設值解析，或 OPENCLAW_CONFIG_PATH 指定時使用該值）。 預設模式為 gateway.reload.mode="hybrid"。

執行模型

  • 一個常駐程序，負責路由、控制平面和頻道連線。
  • 單一多工埠用於：
    • WebSocket 控制/RPC
    • HTTP API（OpenAI 相容、Responses、tools invoke）
    • Control UI 和 hooks
  • 預設繫結模式：loopback。
  • 預設需要驗證（gateway.auth.token / gateway.auth.password，或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。

埠與繫結優先順序

設定解析順序
Gateway 埠--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
繫結模式CLI/覆寫 → gateway.bind → loopback

熱重載模式

gateway.reload.mode行為
off不做設定重載
hot只套用安全的熱更新變更
restart需要重載的變更觸發重啟
hybrid（預設）安全變更用熱更新，需重啟的變更自動重啟

Operator 指令集

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

遠端存取

推薦：Tailscale/VPN。 備援：SSH 通道。

ssh -N -L 18789:127.0.0.1:18789 user@host

然後在本地把客戶端連到 ws://127.0.0.1:18789。

警告： 如果有設定 gateway 驗證，即使透過 SSH 通道，客戶端仍需發送驗證資訊（token/password）。

參閱：遠端 Gateway、身份驗證、Tailscale。

服務管理與生命週期

使用受監管的方式執行以獲得正式環境的可靠性。

macOS（launchd）

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgent 標籤為 ai.openclaw.gateway（預設）或 ai.openclaw.<profile>（命名 profile）。openclaw doctor 會稽核並修復服務設定偏移。

Linux（systemd user）

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

登出後要持續運行，啟用 linger：

sudo loginctl enable-linger <user>

Linux（系統服務）

多使用者/常駐主機使用 system unit。

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

同一主機上的多個 Gateway

多數情況應該只跑一個 Gateway。 只有在需要嚴格隔離/備援時才使用多個（例如救援 profile）。

每個實例的檢查清單：

  • 獨立的 gateway.port
  • 獨立的 OPENCLAW_CONFIG_PATH
  • 獨立的 OPENCLAW_STATE_DIR
  • 獨立的 agents.defaults.workspace

範例：

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

參閱：多 Gateway。

開發 profile 快速路徑

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

預設包含隔離的 state/config 和基底 gateway 埠 19001。

協定快速參考（operator 視角）

  • 客戶端第一個訊框必須是 connect。
  • Gateway 回傳 hello-ok 快照（presence、health、stateVersion、uptimeMs、limits/policy）。
  • 請求：req(method, params) → res(ok/payload|error)。
  • 常見事件：connect.challenge、agent、chat、presence、tick、health、heartbeat、shutdown。

Agent 回合分兩階段：

  1. 立即的接受確認（status:"accepted"）
  2. 最終完成回應（status:"ok"|"error"），中間穿插串流的 agent 事件。

完整協定文件：Gateway 協定。

維運檢查

存活檢查

  • 開啟 WS 並傳送 connect。
  • 預期收到 hello-ok 回應及快照。

就緒檢查

openclaw gateway status
openclaw channels status --probe
openclaw health

間隙恢復

事件不會重播。序列號出現間隙時，先刷新狀態（health、system-presence）再繼續。

常見故障特徵

特徵可能原因
refusing to bind gateway ... without auth非 loopback 繫結但沒有 token/password
another gateway instance is already listening / EADDRINUSE埠衝突
Gateway start blocked: set gateway.mode=local設定為 remote 模式
unauthorized during connect客戶端和 gateway 間的驗證不匹配

完整診斷流程請參閱 Gateway 疑難排解。

安全保證

  • Gateway 協定客戶端在 Gateway 不可用時會立即失敗（不會隱含直連頻道的備援）。
  • 無效或非 connect 的第一個訊框會被拒絕並關閉連線。
  • 優雅關閉時會先發出 shutdown 事件再關閉 socket。

相關文件：

arrow_back
上一頁
Peekaboo
下一頁
Configuration
arrow_forward