閘道操作手冊

此頁面適用於閘道服務的第 1 天啟動與第 2 天維運。

5 分鐘本機啟動

openclaw gateway --port 18789# 將偵錯／追蹤同步輸出至標準輸入輸出openclaw gateway --port 18789 --verbose# 強制終止所選連接埠上的監聽程式，然後啟動openclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

執行階段模型

• 一個持續執行的程序，負責路由、控制平面與頻道連線。
• 單一多工連接埠用於：
  • WebSocket 控制／RPC
  • HTTP API（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • 外掛 HTTP 路由，例如選用的 /api/v1/admin/rpc
  • 控制介面與鉤子
• 預設繫結模式：loopback。在偵測到的容器環境中，有效預設值為 auto（解析為 0.0.0.0 以進行連接埠轉送），但 Tailscale serve/funnel 啟用時例外，此時一律強制使用 loopback。
• 預設需要驗證。共用密鑰設定使用 gateway.auth.token／gateway.auth.password（或 OPENCLAW_GATEWAY_TOKEN／OPENCLAW_GATEWAY_PASSWORD），而非回送位址的反向 Proxy 設定可使用 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。
• 代理程式原生用戶端日益偏好 /v1/responses。

/v1/models 以代理程式為優先：它會為每個已設定的代理程式傳回 openclaw、openclaw/default 與 openclaw/<agentId>。openclaw/default 是穩定別名，一律對應至已設定的預設代理程式。若要覆寫後端提供者／模型，請傳送 x-openclaw-model；否則仍由所選代理程式的一般模型與嵌入設定控制。

這些端點全都在主要閘道連接埠上執行，並與閘道 HTTP API 的其餘部分共用相同的受信任操作員驗證邊界。

管理 HTTP RPC（POST /api/v1/admin/rpc）是獨立且預設關閉的外掛路由，供無法使用 WebSocket RPC 的主機工具使用。請參閱管理 HTTP RPC。

連接埠與繫結優先順序

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

閘道啟動時，若使用非回送繫結，會以相同的有效連接埠與繫結植入本機控制介面來源。例如，--bind lan --port 3000 會在執行階段驗證前植入 http://localhost:3000 與 http://127.0.0.1:3000。請將任何遠端瀏覽器來源（例如 HTTPS Proxy URL）明確加入 gateway.controlUi.allowedOrigins。

熱重新載入模式

操作員命令集

openclaw gateway statusopenclaw gateway status --deep   # 新增系統層級的服務掃描openclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep 用於額外的服務探索（LaunchDaemons/systemd 系統單元/schtasks），而非更深入的 RPC 健康狀態探測。

多個閘道（同一主機）

大多數安裝應在每台機器上執行一個閘道。單一閘道可以承載多個代理程式與頻道。只有在刻意需要隔離或救援機器人時，才需要多個閘道。

實用檢查：

openclaw gateway status --deepopenclaw gateway probe

預期情況：

• 當仍有過時的 launchd/systemd/schtasks 安裝存在時，gateway status --deep 可能會回報 Other gateway-like services detected (best effort) 並顯示清理提示。
• 當不同閘道回應，或 OpenClaw 無法證明可連線的目標是同一個閘道時，gateway probe 可能會警告 multiple reachable gateway identities。即使傳輸連接埠不同，通往同一閘道的 SSH 通道、Proxy URL 或已設定的遠端 URL，仍是具有多種傳輸方式的單一閘道。
• 如果這是刻意的安排，請為每個閘道分別隔離連接埠、設定／狀態與工作區根目錄。

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

• 唯一的 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 通道。

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

然後讓用戶端在本機連線至 ws://127.0.0.1:18789。

另請參閱：遠端閘道、驗證、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 $(whoami)

[Unit]Description=OpenClaw 閘道After=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=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

無效設定錯誤會以代碼 78 結束。Linux systemd 單元使用 RestartPreventExitStatus=78，在修正設定前停止重新啟動。launchd 與 Windows Task Scheduler 沒有依結束代碼停止的等效規則，因此閘道也會保存短時間內不正常啟動的歷史記錄，並在重複啟動失敗後抑制頻道／提供者帳號自動啟動。在該安全模式中，控制平面仍會啟動以供檢查與修復；設定熱重新載入與 secrets.reload 會拒絕自動重新啟動頻道，而操作員明確提出的 channels.start 要求可以覆寫此抑制。

開發設定檔快速路徑

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

預設值包括隔離的狀態／設定，以及閘道基礎連接埠 19001。

通訊協定快速參考（操作員檢視）

• 第一個用戶端影格必須是 connect。
• 閘道會傳回一個 hello-ok 影格，其中包含 snapshot（presence、health、stateVersion、uptimeMs），以及 policy 限制（maxPayload、maxBufferedBytes、tickIntervalMs）。
• hello-ok.features.methods / events 是保守的探索清單，而不是 每個可呼叫輔助路由的自動產生完整清單。
• 請求：req(method, params) → res(ok/payload|error)。
• 常見事件包括 connect.challenge、agent、chat、 session.message、session.operation、session.tool、選擇性啟用的 session.approval、sessions.changed、presence、tick、health、 heartbeat、配對／核准生命週期事件，以及 shutdown。

代理程式執行分為兩個階段：

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

請參閱完整的通訊協定文件：閘道通訊協定。

操作檢查

存活狀態

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

就緒狀態

openclaw gateway statusopenclaw channels status --probeopenclaw health

缺口復原

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

常見失敗特徵

如需完整的診斷流程，請參閱閘道疑難排解。

安全性保證

• 當閘道無法使用時，閘道通訊協定用戶端會立即失敗（不會隱含地回退至直接通道）。
• 無效或非連線類型的初始訊框會遭拒絕並關閉。
• 正常關閉時，會在通訊端關閉前發出 shutdown 事件。

相關內容

• 設定
• 閘道疑難排解
• 背景程序
• 健康狀態
• 診斷工具
• 身分驗證
• 遠端存取
• 機密資料管理