Clawdbot Gateway

Clawdbot Gateway 概覽

Clawdbot Gateway 是一個常駐進程，擁有消息連接（通過 Baileys 連接 WhatsApp、通過 grammY 連接 Telegram、Discord、Slack 等）以及控制/事件平面。它是讓您的 Clawdbot AI 助手全天候運行的核心服務。

什麼是 Gateway？

Gateway 是一個長期運行的守護進程，它：

• 維護所有消息提供者連接
• 暴露用於請求、響應和伺服器推送事件的類型化 WebSocket API
• 根據 JSON Schema 驗證入站幀
• 發出事件如 agent、chat、presence、health、heartbeat、cron

核心原則：每台主機一個 Gateway；它是唯一開啟消息會話（如 WhatsApp）的地方。

快速開始

啟動 Gateway

clawdbot gateway --port 18789

如需完整的調試/追蹤日誌：

clawdbot gateway --port 18789 --verbose

如果端口被佔用，終止監聽器後再啟動：

clawdbot gateway --force

開發模式

開發時自動重載 TypeScript 變更：

pnpm gateway:watch

Gateway 架構

組件

連接流程

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

Gateway 配置

基本配置

配置檔案位置：~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

端口配置

端口優先順序：

1. --port CLI 標誌
2. CLAWDBOT_GATEWAY_PORT 環境變數
3. 配置中的 gateway.port
4. 預設值：18789

認證

Gateway 認證預設為必須。設置方式：

• 配置中的 gateway.auth.token
• CLAWDBOT_GATEWAY_TOKEN 環境變數
• gateway.auth.password 用於密碼認證

客戶端必須發送 connect.params.auth.token 或 connect.params.auth.password。

熱重載

配置熱重載監視 ~/.clawdbot/clawdbot.json：

Gateway 服務

HTTP 端點

Gateway 在同一端口上提供多個 HTTP 端點：

Canvas Host

預設在端口 18793 啟動，服務：

http://<gateway-host>:18793/__clawdbot__/canvas/

來自 ~/.clawdbot/workspace/canvas。禁用方式：

• canvasHost.enabled: false
• CLAWDBOT_SKIP_CANVAS_HOST=1

儀表板

在以下位置訪問控制 UI：

http://127.0.0.1:18789/

或運行：

clawdbot dashboard

遠程訪問

SSH 隧道（推薦）

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

客戶端然後通過隧道連接到 ws://127.0.0.1:18789。

Tailscale/VPN

生產環境遠程訪問的首選。相同的握手 + 認證令牌適用。

Gateway 管理

服務命令

# 檢查狀態
clawdbot gateway status

# 健康檢查
clawdbot health

# 安全審計
clawdbot security audit --deep

# 停止 gateway
clawdbot gateway stop

監督

macOS：使用 LaunchAgent（bot.molt.<profile>）

Linux：使用 systemd 用戶服務（clawdbot-gateway-<profile>.service）

Windows：使用 Windows 服務（Clawdbot Gateway (<profile>)）

多個 Gateway

通常不需要——一個 Gateway 可以服務多個頻道和代理。僅在以下情況使用多個 Gateway：

• 冗餘
• 嚴格隔離（例如，救援機器人）

要求：

• 隔離狀態 + 配置
• 使用唯一端口

Wire 協議

傳輸

• 使用包含 JSON 有效載荷的文本幀的 WebSocket
• 第一幀必須是 connect

消息類型

請求：

{"type": "req", "id": "...", "method": "...", "params": {...}}

響應：

{"type": "res", "id": "...", "ok": true, "payload": {...}}

事件：

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

冪等性

副作用方法（send、agent）需要冪等鍵以安全重試。

故障排除

Gateway 無法啟動

1. 檢查端口是否被佔用：lsof -i :18789
2. 查看日誌：cat /tmp/clawdbot/gateway.log
3. 使用 --force 終止現有監聽器

連接問題

1. 驗證認證令牌匹配
2. 檢查網絡連接
3. 使用 --verbose 查看 WebSocket 握手日誌

頻道問題

1. 檢查頻道狀態：clawdbot channels status
2. 重新認證頻道：clawdbot channels login
3. 查看特定頻道的日誌

最佳實踐

1. 使用認證令牌：始終配置 gateway.auth.token 以確保安全
2. 監控健康狀態：定期檢查 clawdbot health
3. 使用監督：讓 launchd/systemd 管理重啟
4. 備份配置：保留 ~/.clawdbot/clawdbot.json 的備份
5. 查看日誌：定期檢查日誌以發現問題

後續步驟

• Clawdbot 設置指南 - 完整安裝指南
• Clawdbot WhatsApp 整合 - 連接 WhatsApp
• Clawdbot Telegram 整合 - 連接 Telegram