Skip to content
OpenClaw Docs

Gateway Runbook

Gateway runbook

Section titled “Gateway runbook”

使用此頁面進行 Gateway 服務的第一天啟動和第二天操作。

Deep troubleshooting

透過確切的命令階梯和日誌特徵進行以症狀為先導的診斷。

Configuration

以任務為導向的設定指南 + 完整設定參考。

Secrets management

SecretRef 合約、執行時期快照行為，以及遷移/重新載入作業。

Secrets plan contract

精確的 secrets apply target/path 規則和僅參照 auth-profile 行為。

5 分鐘本地啟動

Section titled “5 分鐘本地啟動”

  1. Start the Gateway

    Terminal window
    openclaw gateway --port 18789
    # debug/trace mirrored to stdio
    openclaw gateway --port 18789 --verbose
    # force-kill listener on selected port, then start
    openclaw gateway --force

  2. Verify service health

    Terminal window
    openclaw gateway status
    openclaw status
    openclaw logs --follow

    健康基準：Runtime: running 和 RPC probe: ok。

  3. Validate channel readiness

    Terminal window
    openclaw channels status --probe

Runtime model

Section titled “Runtime model”
  • 一個用於路由、控制平面和通道連線的常駐程序。
  • 單一多工連接埠用於：
    • WebSocket 控制/RPC
    • HTTP API，OpenAI 相容 (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • 控制 UI 和 hooks
  • 預設綁定模式：loopback。
  • 預設情況下需要身份驗證 (gateway.auth.token / gateway.auth.password，或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD)。

OpenAI 相容端點

Section titled “OpenAI 相容端點”

OpenClaw 目前最高杠杆的相容性介面為：

  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses

為何這組端點很重要：

  • 大多數 Open WebUI、LobeChat 和 LibreChat 整合首先會探測 /v1/models。
  • 許多 RAG 和記憶管線期望使用 /v1/embeddings。
  • Agent 原生客戶端越來越偏好使用 /v1/responses。

規劃備註：

  • /v1/models 是代理優先的：它返回 openclaw、openclaw/default 和 openclaw/<agentId>。
  • openclaw/default 是一個穩定的別名，始終映射到設定的預設代理。
  • 當您想要後端提供者/模型覆寫時，請使用 x-openclaw-model；否則，所選代理的常規模型和嵌入設定將保持控制。

所有這些都運作在主要 Gateway 連接埠上，並使用與其餘 Gateway HTTP API 相同的可信操作員驗證邊界。

連接埠與綁定優先順序

Section titled “連接埠與綁定優先順序”
設定解析順序
Gateway 連接埠--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
綁定模式CLI/override → gateway.bind → loopback

熱重載模式

Section titled “熱重載模式”
gateway.reload.mode行為
off不重新載入設定
hot僅套用熱安全變更
restart當需要重新載入變更時重啟
hybrid (預設)安全時熱套用，必要時重啟

操作員指令集

Section titled “操作員指令集”
Terminal window
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

遠端存取

Section titled “遠端存取”

首選：Tailscale/VPN。 備選：SSH tunnel。

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

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

參閱：Remote Gateway、Authentication、Tailscale。

監控與服務生命週期

Section titled “監控與服務生命週期”

在生產環境等對可靠性要求高的場景中，請使用監控模式運行。

Terminal window
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgent 標籤為 ai.openclaw.gateway (預設) 或 `ai.openclaw.

(命名設定檔)。openclaw doctor` 會稽核並修復服務配置漂移。

在單一主機上執行多個 Gateway

Section titled “在單一主機上執行多個 Gateway”

大多數設定應執行 一 個 Gateway。 僅在需要嚴格隔離/冗餘時（例如救援設定檔）才使用多個。

每個執行個體的檢查清單：

  • 唯一的 gateway.port
  • 唯一的 OPENCLAW_CONFIG_PATH
  • 唯一的 OPENCLAW_STATE_DIR
  • 唯一的 agents.defaults.workspace

範例：

Terminal window
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

請參閱：多重閘道。

開發設定檔快速路徑

Section titled “開發設定檔快速路徑”
Terminal window
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

預設值包括隔離的狀態/組態和基礎閘道連接埠 19001。

協定快速參考 (操作員視圖)

Section titled “協定快速參考 (操作員視圖)”
  • 第一個客戶端框架必須是 connect。
  • Gateway 傳回 hello-ok 快照（presence、health、stateVersion、uptimeMs、限制/原則）。
  • 請求：req(method, params) → res(ok/payload|error)。
  • 常見事件：connect.challenge、agent、chat、presence、tick、health、heartbeat、shutdown。

Agent 執行分為兩個階段：

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

請參閱完整的協定文件：Gateway Protocol。

操作檢查

Section titled “操作檢查”

存活度

Section titled “存活度”
  • 開啟 WS 並發送 connect。
  • 預期會收到帶有快照的 hello-ok 回應。

就緒度

Section titled “就緒度”
Terminal window
openclaw gateway status
openclaw channels status --probe
openclaw health

間隙恢復

Section titled “間隙恢復”

事件不會重播。遇到序列間隙時，請先重新整理狀態 (health, system-presence) 再繼續。

常見失敗特徵

Section titled “常見失敗特徵”
特徵可能問題
refusing to bind gateway ... without auth非回環綁定但未提供令牌/密碼
another gateway instance is already listening / EADDRINUSE連接埠衝突
Gateway start blocked: set gateway.mode=local設定設為遠端模式
連線時發生 unauthorized用戶端與 Gateway 之間的驗證不符

如需完整的診斷步驟，請使用 Gateway Troubleshooting。

安全保證

Section titled “安全保證”
  • 當 Gateway 無法使用時，Gateway 協定用戶端會快速失敗 (沒有隱含的直接通道回退)。
  • 無效或非連線的第一個影格會被拒絕並關閉。
  • 優雅關閉會在通訊端關閉前發出 shutdown 事件。

相關：