Gateway 作業手冊

使用此頁面進行 Gateway 服務的第 1 天啟動與第 2 天維運。

5 分鐘本機啟動

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

執行階段模型

• 一個常駐程序，用於路由、控制平面與頻道連線。
• 單一多工連接埠用於：
  • WebSocket 控制/RPC
  • HTTP API，相容 OpenAI（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • 控制 UI 與 hook
• 預設繫結模式：loopback。
• 預設需要驗證。共享密鑰設定使用 gateway.auth.token / gateway.auth.password（或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD），非 loopback 的反向代理設定可以使用 gateway.auth.mode: "trusted-proxy"。

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 以 agent 優先：它會回傳 openclaw、openclaw/default 與 openclaw/<agentId>。
• openclaw/default 是穩定別名，永遠對應到已設定的預設 agent。
• 當你想要後端 provider/model 覆寫時，請使用 x-openclaw-model；否則所選 agent 的一般模型與 embedding 設定會保持控制權。

所有這些都在主要 Gateway 連接埠上執行，並使用與其餘 Gateway HTTP API 相同的受信任 operator 驗證邊界。

連接埠與繫結優先順序

已安裝的 gateway 服務會在 supervisor 中繼資料記錄已解析的 --port。變更 gateway.port 後，請執行 openclaw doctor --fix 或 openclaw gateway install --force，讓 launchd/systemd/schtasks 在新連接埠啟動程序。

Gateway 啟動會在為非 loopback 繫結播種本機 控制 UI origin 時，使用相同的有效連接埠與繫結。例如，--bind lan --port 3000 會在執行階段驗證執行前，播種 http://localhost:3000 與 http://127.0.0.1:3000。 請將任何遠端瀏覽器 origin，例如 HTTPS proxy URL，明確加入 gateway.controlUi.allowedOrigins。

熱重新載入模式

Operator 命令集

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep 用於額外的服務探索（LaunchDaemons/systemd 系統 unit/schtasks），不是更深入的 RPC 健康探測。

多個 gateway（同一主機）

多數安裝應該在每台機器執行一個 gateway。單一 gateway 可以承載多個 agent 與頻道。

只有在你刻意需要隔離或救援 bot 時，才需要多個 gateway。

有用的檢查：

openclaw gateway status --deepopenclaw gateway probe

預期結果：

• gateway status --deep 可以回報 Other gateway-like services detected (best effort) 並在過期的 launchd/systemd/schtasks 安裝仍存在時列印清理提示。
• 當超過一個目標回應時，gateway probe 可以警告 multiple reachable gateways。
• 如果這是刻意的，請為每個 gateway 隔離連接埠、設定/狀態與 workspace root。

每個實例的檢查清單：

• 唯一的 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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

詳細設定：/gateway/multiple-gateways。

遠端存取

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

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

接著在本機將用戶端連線到 ws://127.0.0.1:18789。

請參閱：遠端 Gateway、驗證、Tailscale。

監督與服務生命週期

對類生產可靠性使用受監督的執行方式。

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

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

Dev 設定檔快速路徑

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

預設包含隔離的狀態/設定與基礎 gateway 連接埠 19001。

通訊協定快速參考（operator 視角）

• 第一個用戶端 frame 必須是 connect。
• Gateway 會回傳 hello-ok 快照（presence、health、stateVersion、uptimeMs、限制/政策）。
• hello-ok.features.methods / events 是保守的探索清單，不是 每個可呼叫 helper route 的生成式傾印。
• 請求：req(method, params) → res(ok/payload|error)。
• 常見事件包含 connect.challenge、agent、chat、 session.message、session.tool、sessions.changed、presence、tick、 health、heartbeat、配對/核准生命週期事件，以及 shutdown。

Agent 執行分為兩個階段：

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

請參閱完整通訊協定文件：Gateway 通訊協定。

操作檢查

存活性

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

就緒性

openclaw gateway statusopenclaw channels status --probeopenclaw health

缺口復原

事件不會重播。發生序列缺口時，先重新整理狀態（health、system-presence）再繼續。

常見失敗特徵

如需完整的診斷階梯，請使用 Gateway 疑難排解。

安全保證

• Gateway 協定用戶端會在 Gateway 無法使用時快速失敗（不會隱含回退到直接通道）。
• 無效或非連線的第一個 frame 會被拒絕並關閉。
• 正常關閉會在 socket 關閉前發出 shutdown 事件。

相關內容：

• 疑難排解
• 背景程序
• 設定
• 健康狀態
• 診斷
• 驗證

相關內容

• 設定
• Gateway 疑難排解
• 遠端存取
• 機密資訊管理