Gateway - Neotask by Neotask Documentation | Neotask

Gateway

什麼是 Gateway？

Gateway 是 Open Claw 的核心——一個管理所有代理程式工作階段、訊息頻道、工具執行和裝置連接的長期執行服務。所有事情都透過 Gateway 流轉。

它是一個 WebSocket 伺服器，監聽來自用戶端（桌面應用程式、行動應用程式、網頁儀表板）的連接，並管理整個 AI 助理的生命週期。

架構

元件

  • WebSocket 伺服器 — 接受用戶端連接（預設連接埠 18789）
  • HTTP 伺服器 — 提供控制 UI、畫布主機和健康端點
  • 頻道轉接器 — 維護與訊息平台的連接（WhatsApp、Telegram、Discord 等）
  • 工作階段管理器 — 持久化並管理代理程式對話狀態
  • Cron 排程器 — 執行排程工作和心跳喚醒
  • 外掛執行期 — 載入和管理外掛生命週期
  • 瀏覽器服務 — 控制 Chromium 實例進行網頁自動化

    • 綁定模式

    | 模式 | 說明 | |------|------| | Loopback | 預設。只能從 localhost（127.0.0.1）存取 | | LAN | 可在本機網路上存取。透過 Bonjour/mDNS 自動探索 | | Tailnet | 透過 Tailscale VPN 和 MagicDNS 存取 | | Custom | 綁定至特定位址 |

    驗證

    | 方法 | 說明 | |------|------| | Token | WebSocket 不記名令牌（UUID 或自訂字串） | | Password | 基於密碼的驗證（bcrypt 雜湊） | | Trusted Proxy | 用於帶有預驗證標頭的反向代理 | | Local Trust | 回送連接自動核准 |

    設定

    Gateway 透過 openclaw.json（JSON5 格式）進行設定。主要區段：

    | 區段 | 控制 | |------|------| | agents | 代理程式清單、預設值、工作空間 | | gateway | 連接埠、綁定模式、驗證、重新載入行為 | | channels | 每頻道設定和憑證 | | tools | 工具權限、設定檔、安全性 | | plugins | 外掛載入、啟用、每外掛設定 | | models | 提供者驗證、備援、提供者設定 | | skills | 技能目錄、每技能設定 | | browser | 瀏覽器設定檔、連接埠、無頭模式 | | cron | 排程器設定 | | session | 重置規則、壓縮閾值 | | messages | TTS 設定、媒體策略 | | memory | 記憶體索引設定 | | security | 沙盒、提升模式、核准 |

    熱重載

    設定更改可以在不重新啟動的情況下套用：

    | 模式 | 行為 | |------|------| | Hybrid（預設） | 熱套用安全更改，其他更改需重新啟動 | | Hot | 只套用熱安全更改，忽略其他更改 | | Restart | 在任何需要重新載入的更改時重新啟動 | | Off | 無自動重新載入 |

    遠端存取

    Tailscale（推薦）

    Tailscale 提供安全的零設定遠端存取：

  • 將 Gateway 綁定到您的 Tailnet
  • 從同一 Tailscale 網路上的任何裝置存取
  • 透過 MagicDNS 自動 DNS
  • Tailscale Serve 可以透過 HTTPS 暴露儀表板

    • SSH 隧道

    透過 SSH 轉發 Gateway 連接埠：

  • 簡單、安全，無需更改設定
  • 適用於任何支援 SSH 的機器
  • 支援完整的 WebSocket 協定和控制 UI

    • 安全規則

  • Loopback + SSH/Tailscale 是最安全的組合
  • 非回送綁定需要驗證令牌設定
  • 可提供 TLS 指紋釘選以獲得額外安全性
  • 預設情況下，遠端連接停用瀏覽器控制

    • 健康監控

    健康端點

    /health HTTP 端點返回：

  • Gateway 狀態
  • RPC 活躍性
  • 每頻道健康狀況（連接狀態、驗證狀態、帳戶數量）
  • 瀏覽器就緒狀態
  • 活躍代理程式和已連接節點
  • 正常運行時間

    • 探測

  • RPC 活躍性 — WebSocket 連接 + 回聲測試
  • 頻道健康 — 每頻道驗證檢查 + API ping
  • 瀏覽器就緒性 — 連接埠檢查、程序檢查
  • 節點連通性 — 上次心跳時間戳記

    • 探索

    Bonjour/mDNS

    當綁定至區域網路時，Gateway 透過多播 DNS 廣播自己：

  • 服務類型：_openclaw-gw._tcp
  • 包含連接埠、傳輸方式、TLS 狀態和 Tailscale DNS 資訊
  • 伴侶應用程式自動探索 Gateway

    • 廣域探索

    透過可設定的超時時間探索網路上的 Gateway。支援本機 Bonjour 和 Tailscale DNS 探索。

    多個 Gateway

    您可以使用設定檔在同一台機器上執行多個 Gateway 實例：

  • 每個設定檔都有獨立的設定、工作空間、工作階段和狀態
  • 每個 Gateway 使用不同的連接埠
  • 適用於隔離（個人與工作）或測試

    • 診斷

    醫生

    內建診斷工具檢查：

  • 設定有效性
  • 檔案權限
  • 頻道連通性
  • 模型驗證狀態
  • Node.js 版本相容性
  • 常見設定錯誤

    • 獲得許可後，它可以自動修復許多問題。

    日誌記錄

    Gateway 日誌寫入每日 JSONL 檔案：

  • 每次完成的令牌使用量追蹤
  • 頻道事件日誌
  • 帶有結構化上下文的錯誤日誌記錄
  • 可設定的日誌層級

    • View full documentation