Gateway 執行手冊

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

# 5 分鐘本機啟動

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# 執行階段模型

• 一個永遠在線的程序，用於路由、控制平面與通道連線。
• 單一多工連接埠用於：
  • 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），而非 loopback 的反向 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。
• 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 相同的受信任操作員驗證邊界。

# 連接埠與綁定優先順序

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

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

# 熱重新載入模式

# 操作員命令集

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

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

# 多個 Gateway（同一主機）

多數安裝應該每台機器執行一個 Gateway。單一 Gateway 可以託管多個 agent 與通道。

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

實用檢查：

openclaw gateway status --deep
openclaw gateway probe

預期結果：

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

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

• 唯一的 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/multiple-gateways。

# 遠端存取

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

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

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

參見：Remote Gateway、Authentication、Tailscale。

# 監督與服務生命週期

使用受監督執行以取得接近生產環境的可靠性。

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

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

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# Dev profile 快速路徑

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

預設包含隔離的狀態/設定，以及基礎 Gateway 連接埠 19001。

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

• 第一個用戶端 frame 必須是 connect。
• Gateway 會回傳 hello-ok 快照（presence、health、stateVersion、uptimeMs、limits/policy）。
• 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. 立即 accepted ack（status:"accepted"）
2. 最終完成回應（status:"ok"|"error"），中間會串流 agent 事件。

完整通訊協定文件請見：Gateway Protocol。

# 維運檢查

# 存活性

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

# 就緒性

openclaw gateway status
openclaw channels status --probe
openclaw health

# 缺口復原

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

# 常見失敗特徵

完整診斷階梯請使用 Gateway Troubleshooting。

# 安全保證

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

相關：

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

# 相關

• 設定
• Gateway 疑難排解
• 遠端存取
• 密鑰管理