閘道服務操作手冊

最後更新：2025-12-09

它是什麼

擁有單一 Baileys/Telegram 連線和控制/事件平面的永遠線上程序。
取代舊版 gateway 指令。CLI 入口點：moltbot gateway。
執行直到停止；發生致命錯誤時以非零退出，以便監督程式重新啟動。

如何執行（本地）

bash

moltbot gateway --port 18789
# 完整除錯/追蹤日誌輸出到 stdio：
moltbot gateway --port 18789 --verbose
# 如果埠忙碌，終止監聽器然後啟動：
moltbot gateway --force
# 開發迴圈（TS 變更時自動重新載入）：
pnpm gateway:watch

配置熱重載監視 ~/.clawdbot/moltbot.json（或 CLAWDBOT_CONFIG_PATH）。
- 預設模式：gateway.reload.mode="hybrid"（熱套用安全變更，關鍵變更時重啟）。
- 熱重載在需要時透過 SIGUSR1 使用程序內重啟。
- 使用 gateway.reload.mode="off" 停用。
將 WebSocket 控制平面綁定到 127.0.0.1:<port>（預設 18789）。
相同埠也提供 HTTP（控制介面、hooks、A2UI）。單埠多工。
- OpenAI Chat Completions (HTTP)：/v1/chat/completions。
- OpenResponses (HTTP)：/v1/responses。
- Tools Invoke (HTTP)：/tools/invoke。
預設在 canvasHost.port（預設 18793）上啟動 Canvas 檔案伺服器，從 ~/clawd/canvas 提供 http://<gateway-host>:18793/__moltbot__/canvas/。使用 canvasHost.enabled=false 或 CLAWDBOT_SKIP_CANVAS_HOST=1 停用。
記錄到 stdout；使用 launchd/systemd 保持它存活並輪替日誌。
傳遞 --verbose 以在疑難排解時將除錯日誌（握手、req/res、事件）從日誌檔案鏡像到 stdio。
--force 使用 lsof 尋找所選埠上的監聽器，發送 SIGTERM，記錄被終止的內容，然後啟動閘道（如果缺少 lsof 則快速失敗）。
如果你在監督程式下執行（launchd/systemd/mac 應用程式子程序模式），停止/重啟通常發送 SIGTERM；較舊的建置可能將其顯示為 pnpm ELIFECYCLE 退出碼 143（SIGTERM），這是正常關機，不是崩潰。
SIGUSR1 在授權時觸發程序內重啟（閘道工具/配置套用/更新，或啟用 commands.restart 進行手動重啟）。
預設需要閘道驗證：設定 gateway.auth.token（或 CLAWDBOT_GATEWAY_TOKEN）或 gateway.auth.password。除非使用 Tailscale Serve 身分，否則客戶端必須發送 connect.params.auth.token/password。
精靈現在預設產生權杖，即使在 loopback 上也是如此。
埠優先順序：--port > CLAWDBOT_GATEWAY_PORT > gateway.port > 預設 18789。

遠端存取

偏好 Tailscale/VPN；否則使用 SSH 通道：
bash
```
ssh -N -L 18789:127.0.0.1:18789 user@host
```
然後客戶端透過通道連接到 ws://127.0.0.1:18789。
如果配置了權杖，即使透過通道，客戶端也必須在 connect.params.auth.token 中包含它。

多個閘道（相同主機）

通常不必要：一個閘道可以服務多個訊息頻道和代理。僅在需要冗餘或嚴格隔離（例如：救援機器人）時使用多個閘道。

如果你隔離狀態 + 配置並使用唯一埠，則支援此功能。完整指南：多個閘道。

服務名稱具有設定檔感知能力：

macOS：bot.molt.<profile>（舊版 com.clawdbot.* 可能仍然存在）
Linux：moltbot-gateway-<profile>.service
Windows：Moltbot Gateway (<profile>)

安裝元資料嵌入在服務配置中：

CLAWDBOT_SERVICE_MARKER=moltbot
CLAWDBOT_SERVICE_KIND=gateway
CLAWDBOT_SERVICE_VERSION=<version>

救援機器人模式：保持第二個閘道隔離，使用自己的設定檔、狀態目錄、工作區和基礎埠間距。完整指南：救援機器人指南。

開發設定檔（`--dev`）

快速路徑：執行完全隔離的開發實例（配置/狀態/工作區）而不觸及你的主要設定。

bash

moltbot --dev setup
moltbot --dev gateway --allow-unconfigured
# 然後以開發實例為目標：
moltbot --dev status
moltbot --dev health

預設值（可透過 env/flags/config 覆寫）：

CLAWDBOT_STATE_DIR=~/.clawdbot-dev
CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/moltbot.json
CLAWDBOT_GATEWAY_PORT=19001（閘道 WS + HTTP）
瀏覽器控制服務埠 = 19003（衍生：gateway.port+2，僅 loopback）
canvasHost.port=19005（衍生：gateway.port+4）
當你在 --dev 下執行 setup/onboard 時，agents.defaults.workspace 預設變為 ~/clawd-dev。

衍生埠（經驗法則）：

基礎埠 = gateway.port（或 CLAWDBOT_GATEWAY_PORT / --port）
瀏覽器控制服務埠 = 基礎 + 2（僅 loopback）
canvasHost.port = 基礎 + 4（或 CLAWDBOT_CANVAS_HOST_PORT / 配置覆寫）
瀏覽器設定檔 CDP 埠從 browser.controlPort + 9 .. + 108 自動分配（每個設定檔持久化）。

每個實例的檢查清單：

唯一的 gateway.port
唯一的 CLAWDBOT_CONFIG_PATH
唯一的 CLAWDBOT_STATE_DIR
唯一的 agents.defaults.workspace
獨立的 WhatsApp 號碼（如果使用 WA）

每個設定檔的服務安裝：

bash

moltbot --profile main gateway install
moltbot --profile rescue gateway install

範例：

bash

CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a moltbot gateway --port 19001
CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b moltbot gateway --port 19002

協定（操作者視圖）

完整文件：閘道協定與橋接協定（舊版）。
客戶端的必要首幀：req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }。
閘道回覆 res {type:"res", id, ok:true, payload:hello-ok }（或帶有錯誤的 ok:false，然後關閉）。
握手後：
- 請求：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
- 事件：{type:"event", event, payload, seq?, stateVersion?}
結構化存在條目：{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }（對於 WS 客戶端，instanceId 來自 connect.client.instanceId）。
agent 回應是兩階段的：首先 res 確認 {runId,status:"accepted"}，然後在執行完成後最終 res {runId,status:"ok"|"error",summary}；串流輸出作為 event:"agent" 到達。

方法（初始集）

health — 完整健康快照（與 moltbot health --json 相同的形狀）。
status — 簡短摘要。
system-presence — 當前存在清單。
system-event — 發布存在/系統注意事項（結構化）。
send — 透過活動頻道發送訊息。
agent — 執行代理回合（在相同連線上串流事件回來）。
node.list — 列出配對 + 當前連接的節點（包括 caps、deviceFamily、modelIdentifier、paired、connected 和通告的 commands）。
node.describe — 描述節點（功能 + 支援的 node.invoke 指令；適用於配對節點和當前連接的未配對節點）。
node.invoke — 在節點上呼叫指令（例如 canvas.*、camera.*）。
node.pair.* — 配對生命週期（request、list、approve、reject、verify）。

另見：存在了解如何產生/去重存在以及為什麼穩定的 client.instanceId 很重要。

事件

agent — 來自代理執行的串流工具/輸出事件（seq 標記）。
presence — 存在更新（帶有 stateVersion 的差異）推送到所有連接的客戶端。
tick — 定期保持連線/無操作以確認存活。
shutdown — 閘道正在退出；有效負載包括 reason 和可選的 restartExpectedMs。客戶端應重新連接。

WebChat 整合

WebChat 是一個原生 SwiftUI UI，直接與閘道 WebSocket 通訊以獲取歷史、發送、中止和事件。
遠端使用透過相同的 SSH/Tailscale 通道；如果配置了閘道權杖，客戶端在 connect 期間包含它。
macOS 應用程式透過單一 WS（共享連線）連接；它從初始快照補充存在並監聽 presence 事件以更新 UI。

類型與驗證

伺服器使用 AJV 針對從協定定義發出的 JSON Schema 驗證每個入站幀。
客戶端（TS/Swift）使用產生的類型（TS 直接；Swift 透過儲存庫的產生器）。
協定定義是真相來源；使用以下方式重新產生 schema/模型：
- pnpm protocol:gen
- pnpm protocol:gen:swift

連線快照

hello-ok 包括帶有 presence、health、stateVersion 和 uptimeMs 的 snapshot，加上 policy {maxPayload,maxBufferedBytes,tickIntervalMs}，以便客戶端可以立即渲染而無需額外請求。
health/system-presence 仍可用於手動重新整理，但在連線時不需要。

錯誤碼（res.error 形狀）

錯誤使用 { code, message, details?, retryable?, retryAfterMs? }。
標準碼：
- NOT_LINKED — WhatsApp 未驗證。
- AGENT_TIMEOUT — 代理未在配置的截止時間內回應。
- INVALID_REQUEST — schema/參數驗證失敗。
- UNAVAILABLE — 閘道正在關閉或相依性不可用。

保持連線行為

定期發出 tick 事件（或 WS ping/pong），以便客戶端知道即使沒有流量時閘道也是存活的。
發送/代理確認保持獨立的回應；不要為發送重載 tick。

重播 / 間隙

事件不會重播。客戶端檢測 seq 間隙並應在繼續之前重新整理（health + system-presence）。WebChat 和 macOS 客戶端現在在間隙時自動重新整理。

監督（macOS 範例）

使用 launchd 保持服務存活：
- Program：moltbot 的路徑
- Arguments：gateway
- KeepAlive：true
- StandardOut/Err：檔案路徑或 syslog
失敗時，launchd 重新啟動；致命錯誤配置應繼續退出，以便操作者注意到。
LaunchAgents 是每個使用者的，需要已登入的會話；對於無頭設定，使用自訂 LaunchDaemon（未附帶）。
- moltbot gateway install 寫入 ~/Library/LaunchAgents/bot.molt.gateway.plist （或 bot.molt.<profile>.plist；舊版 com.clawdbot.* 會清理）。
- moltbot doctor 審核 LaunchAgent 配置並可以將其更新為當前預設值。

閘道服務管理（CLI）

使用閘道 CLI 進行 install/start/stop/restart/status：

bash

moltbot gateway status
moltbot gateway install
moltbot gateway stop
moltbot gateway restart
moltbot logs --follow

注意事項：

gateway status 預設使用服務的解析埠/配置探測閘道 RPC（使用 --url 覆寫）。
gateway status --deep 新增系統級掃描（LaunchDaemons/system units）。
gateway status --no-probe 跳過 RPC 探測（當網路不可用時有用）。
gateway status --json 對腳本穩定。
gateway status 分別報告監督程式執行時期（launchd/systemd 執行）與 RPC 可達性（WS 連接 + 狀態 RPC）。
gateway status 列印配置路徑 + 探測目標以避免「localhost vs LAN 綁定」混淆和設定檔不匹配。
當服務看起來正在執行但埠已關閉時，gateway status 包括最後的閘道錯誤行。
logs 透過 RPC 尾隨閘道檔案日誌（無需手動 tail/grep）。
如果檢測到其他類似閘道的服務，CLI 會警告，除非它們是 Moltbot 設定檔服務。我們仍建議大多數設定每台機器一個閘道；使用隔離的設定檔/埠進行冗餘或救援機器人。參見多個閘道。
- 清理：moltbot gateway uninstall（當前服務）和 moltbot doctor（舊版遷移）。
當已安裝時，gateway install 是無操作；使用 moltbot gateway install --force 重新安裝（設定檔/env/路徑變更）。

捆綁的 mac 應用程式：

Moltbot.app 可以捆綁基於 Node 的閘道中繼並安裝標記為 bot.molt.gateway（或 bot.molt.<profile>；舊版 com.clawdbot.* 標籤仍可乾淨卸載）的每個使用者 LaunchAgent。
要乾淨地停止它，使用 moltbot gateway stop（或 launchctl bootout gui/$UID/bot.molt.gateway）。
要重啟，使用 moltbot gateway restart（或 launchctl kickstart -k gui/$UID/bot.molt.gateway）。
- launchctl 僅在安裝 LaunchAgent 時有效；否則先使用 moltbot gateway install。
- 執行命名設定檔時，將標籤替換為 bot.molt.<profile>。

監督（systemd 使用者單元）

Moltbot 預設在 Linux/WSL2 上安裝 systemd 使用者服務。我們建議對單使用者機器使用使用者服務（更簡單的 env，每個使用者的配置）。對多使用者或永遠線上伺服器使用系統服務（不需要 lingering，共享監督）。

moltbot gateway install 寫入使用者單元。moltbot doctor 審核單元並可以將其更新為符合當前建議的預設值。

建立 ~/.config/systemd/user/moltbot-gateway[-<profile>].service：

[Unit]
Description=Moltbot Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/moltbot gateway --port 18789
Restart=always
RestartSec=5
Environment=CLAWDBOT_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser

[Install]
WantedBy=default.target

啟用 lingering（必需，以便使用者服務在登出/閒置後存活）：

sudo loginctl enable-linger youruser

引導在 Linux/WSL2 上執行此操作（可能提示 sudo；寫入 /var/lib/systemd/linger）。然後啟用服務：

systemctl --user enable --now moltbot-gateway[-<profile>].service

替代方案（系統服務） - 對於永遠線上或多使用者伺服器，你可以安裝 systemd 系統單元而不是使用者單元（不需要 lingering）。建立 /etc/systemd/system/moltbot-gateway[-<profile>].service（複製上面的單元，切換 WantedBy=multi-user.target，設定 User= + WorkingDirectory=），然後：

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

Windows（WSL2）

Windows 安裝應使用 WSL2 並遵循上面的 Linux systemd 部分。

操作檢查

存活性：開啟 WS 並發送 req:connect → 預期帶有 payload.type="hello-ok"（帶有快照）的 res。
就緒性：呼叫 health → 預期 ok: true 和 linkChannel 中的連結頻道（如適用）。
除錯：訂閱 tick 和 presence 事件；確保 status 顯示連結/驗證年齡；存在條目顯示閘道主機和連接的客戶端。

安全保證

預設假設每個主機一個閘道；如果你執行多個設定檔，隔離埠/狀態並以正確的實例為目標。
沒有後備到直接 Baileys 連線；如果閘道關閉，發送快速失敗。
非連接首幀或格式錯誤的 JSON 會被拒絕，socket 會關閉。
優雅關機：在關閉前發出 shutdown 事件；客戶端必須處理關閉 + 重新連接。

CLI 輔助工具

moltbot gateway health|status — 透過閘道 WS 請求健康/狀態。
moltbot message send --target <num> --message "hi" [--media ...] — 透過閘道發送（WhatsApp 的冪等）。
moltbot agent --message "hi" --to <num> — 執行代理回合（預設等待最終）。
moltbot gateway call <method> --params '{"k":"v"}' — 用於除錯的原始方法呼叫器。
moltbot gateway stop|restart — 停止/重啟受監督的閘道服務（launchd/systemd）。
閘道輔助子指令假設在 --url 上執行閘道；它們不再自動產生一個。

遷移指南

停用 moltbot gateway 和舊版 TCP 控制埠的使用。
更新客戶端以使用必要的連接和結構化存在來說 WS 協定。

閘道服務操作手冊 ​

它是什麼 ​

如何執行（本地） ​

遠端存取 ​

多個閘道（相同主機） ​

開發設定檔（--dev） ​

協定（操作者視圖） ​

方法（初始集） ​

事件 ​

WebChat 整合 ​

類型與驗證 ​

連線快照 ​

錯誤碼（res.error 形狀） ​

保持連線行為 ​

重播 / 間隙 ​

監督（macOS 範例） ​

閘道服務管理（CLI） ​

監督（systemd 使用者單元） ​

Windows（WSL2） ​

操作檢查 ​

安全保證 ​

CLI 輔助工具 ​

遷移指南 ​

閘道服務操作手冊

它是什麼

如何執行（本地）

遠端存取

多個閘道（相同主機）

開發設定檔（`--dev`）

協定（操作者視圖）

方法（初始集）

事件

WebChat 整合

類型與驗證

連線快照

錯誤碼（res.error 形狀）

保持連線行為

重播 / 間隙

監督（macOS 範例）

閘道服務管理（CLI）

監督（systemd 使用者單元）

Windows（WSL2）

操作檢查

安全保證

CLI 輔助工具

遷移指南