OpenClaw Gateway 是整個 OpenClaw 系統(tǒng)的“控制中樞”和“通信樞紐”，負(fù)責(zé)統(tǒng)一管理所有聊天渠道（如 Telegram、WhatsApp、飛書等）的連接、消息路由、會話狀態(tài)維護(hù)以及安全認(rèn)證，是實現(xiàn)本地化 AI 助手運(yùn)行的核心組件。Gateway 是什么？為什么要有它？它是怎么一步步被設(shè)計出來的？

核心功能與職責(zé)：

• ‌消息接入與協(xié)議適配‌
  支持多種即時通訊平臺（IM），將不同平臺的消息格式統(tǒng)一處理，確保跨渠道通信無縫銜接。
• ‌智能路由與會話管理‌
  根據(jù)用戶身份、聊天來源自動識別會話上下文，并將請求精準(zhǔn)路由到對應(yīng)的 AI Agent，保持對話連貫性。
• ‌執(zhí)行調(diào)度與工具調(diào)用‌
  協(xié)調(diào) AI 模型推理、工具調(diào)用（如瀏覽器操作、文件讀寫、定時任務(wù)）及多 Agent 協(xié)同工作，驅(qū)動實際任務(wù)執(zhí)行。
• ‌安全控制與認(rèn)證機(jī)制‌
  提供訪問令牌、密碼認(rèn)證、設(shè)備配對等功能，保障本地服務(wù)不被未授權(quán)訪問；默認(rèn)僅綁定本地回環(huán)地址（127.0.0.1），增強(qiáng)安全性。
• ‌WebSocket 與 HTTP API 服務(wù)‌
  對外提供 OpenAI 兼容 API 和響應(yīng)式接口，支持 CLI、Web 控制臺、移動端等多種客戶端接入。

工作原理簡述：

• 所有用戶消息首先發(fā)送至 Gateway；
• Gateway 進(jìn)行身份驗證、會話識別后，將任務(wù)分發(fā)給相應(yīng)的 AI Agent；
• Agent 在本地或遠(yuǎn)程節(jié)點(diǎn)完成推理與執(zhí)行，結(jié)果返回 Gateway；
• 最終由 Gateway 通過原始通信渠道將回復(fù)傳回用戶。

先從你作為用戶的體驗說起

假設(shè)你已經(jīng)裝好了 OpenClaw，你的日常使用是這樣的：

• 早上在手機(jī) WhatsApp 問它：“幫我整理一下今天的會議紀(jì)要”，它打開你電腦上的文件夾，生成文檔，然后把鏈接發(fā)回給你
• 下午在電腦 Slack 頻道里問它：“現(xiàn)在服務(wù)器狀態(tài)怎么樣”，它 SSH 進(jìn)服務(wù)器跑命令，把結(jié)果返回給你
• 同時，你打開瀏覽器的 Web UI，看到它正在執(zhí)行的任務(wù)進(jìn)度，實時滾動的日志
• 你的 iPhone 也在旁邊，能隨時語音喚醒它

這里面有一件微妙的事情：這四個入口（WhatsApp、Slack、Web UI、iPhone）同時在用同一個 AI 助手，而且它們看到的狀態(tài)是同步的。

這就帶來了一個工程問題。

問題：誰來協(xié)調(diào)這一切？

不妨想象一下，如果沒有任何中樞，會發(fā)生什么：

WhatsApp 連接 → AI 進(jìn)程 A
Slack 連接    → AI 進(jìn)程 B
Web UI 連接   → AI 進(jìn)程 C
iPhone 連接   → AI 進(jìn)程 D

四個進(jìn)程各自獨(dú)立。在 WhatsApp 問的問題，Slack 里看不到；Web UI 看到的狀態(tài)，和真實執(zhí)行進(jìn)度不同步；你在 Slack 說"停止"，WhatsApp 那邊的 AI 還在跑。

這行不通。

所有的入口必須共享同一個 AI 的同一個狀態(tài)。 這意味著需要一個單一的協(xié)調(diào)中心——它連接所有的消息通道，管理唯一一個 AI 執(zhí)行進(jìn)程，并把狀態(tài)實時同步給所有連接的客戶端。

這就是 OpenClaw Gateway 存在的根本原因。

Gateway 的本質(zhì)：一個控制平面

OpenClaw 的代碼注釋用了一個專業(yè)術(shù)語來描述 Gateway：

Gateway WebSocket control plane

控制平面（Control Plane） 是網(wǎng)絡(luò)工程里的概念：負(fù)責(zé)"決策和協(xié)調(diào)"的那一層，而不是"傳輸數(shù)據(jù)"的那一層。

用更直白的話說，Gateway 干三件事：

① 消息樞紐：所有消息通道（WhatsApp、Telegram、Slack…）的消息都匯入 Gateway，Gateway 決定交給哪個 AI 會話處理，再把 AI 的回復(fù)分發(fā)出去。

② 命令中心：CLI、macOS App、Web UI、手機(jī) App 都通過 Gateway 控制 AI——啟停會話、查看狀態(tài)、修改配置、觸發(fā)任務(wù)。

③ 狀態(tài)廣播站：AI 在執(zhí)行任務(wù)時，Gateway 把實時狀態(tài)廣播給所有連接的客戶端。你在手機(jī)上問的問題，在電腦 Web UI 上也能實時看到 AI 的思考過程。

理解這三件事，Gateway 后面所有的設(shè)計決策都會變得順理成章。

第一個設(shè)計決策：為什么用 WebSocket？

確定了"Gateway 需要實時同步狀態(tài)給多個客戶端"之后，接下來的問題是：用什么協(xié)議？

最常見的選項是 HTTP。但 HTTP 有一個根本性的限制：它是請求-響應(yīng)模式，必須客戶端先問，服務(wù)端才能答。服務(wù)端沒有辦法主動推送消息。

而 Gateway 有一個強(qiáng)烈的需求：AI 在生成回復(fù)時，要把每個字實時推給所有客戶端。不是等 AI 生成完整段話再一次性發(fā)過來，而是像打字機(jī)一樣，生成一個字就推一個字（這就是 LLM 的"流式輸出"）。

用 HTTP 實現(xiàn)這個需求有兩種方式：

• 長輪詢（Long Polling）：客戶端不斷問"有新內(nèi)容嗎"，服務(wù)器有了再回答。延遲高，連接開銷大。
• SSE（Server-Sent Events）：服務(wù)器可以主動推，但只能單向，客戶端沒辦法同時發(fā)命令。

這兩種都滿足不了需求。OpenClaw 需要的是：客戶端和服務(wù)端都能隨時主動發(fā)消息，而且是持久連接，不用每次都重新握手。

這正是 WebSocket 的設(shè)計目標(biāo)。一旦建立連接，雙方可以隨時互發(fā)消息，延遲極低，也沒有重復(fù)握手的開銷。

普通 HTTP：
  客戶端 →→→ 請求 →→→ 服務(wù)端
  客戶端 ←←← 響應(yīng) ←←← 服務(wù)端
  （連接關(guān)閉，下次再來）

WebSocket：
  建立一次連接后，雙方隨時可以發(fā)：
  客戶端 →→→ "執(zhí)行這個命令" →→→ 服務(wù)端
  服務(wù)端 ←←← "AI 正在思考..." ←←← 服務(wù)端（主動推）
  服務(wù)端 ←←← "AI 說：..." ←←← 服務(wù)端（繼續(xù)推）
  客戶端 →→→ "停止" →→→ 服務(wù)端
  （連接一直保持）

這就是 Gateway 選擇 WebSocket 作為主協(xié)議的原因——不是因為 WebSocket 時髦，而是業(yè)務(wù)需求決定的。

HTTP 并沒有消失。Gateway 同時監(jiān)聽 HTTP，用于：瀏覽器訪問 Web UI（必須 HTTP）、Slack/Webhook 等外部回調(diào)（第三方只會發(fā) HTTP）、OpenAI 兼容接口（方便接入現(xiàn)有 SDK）。但這些都是輔助場景。

第二個設(shè)計決策：連接進(jìn)來之后怎么認(rèn)識你？

Gateway 現(xiàn)在用 WebSocket 對外提供服務(wù)。連接進(jìn)來的客戶端可能是：

• 你自己的 CLI（完全可信，可以做任何事）
• 你的 Web UI（你自己用，但最好限制只讀，防止誤操作）
• 你的 iPhone 節(jié)點(diǎn)（它能上報攝像頭畫面，但不應(yīng)該能修改配置）
• 一個 Webhook 調(diào)用（外部觸發(fā)，權(quán)限最?。?/li>

這四種客戶端需要不同的權(quán)限。 怎么區(qū)分它們？

最簡單的方案是：每種客戶端用不同的 Token。但這樣管理成本高，而且粒度太粗——你沒法做到"Web UI 可以查看會話列表，但不能刪除會話"。

OpenClaw 的解法是三層認(rèn)證模型，每層解決不同的問題：

第一層：你是誰？（HTTP 層 Token）

建立 WebSocket 連接的那一刻，HTTP Upgrade 請求里必須帶 Token：

GET /ws HTTP/1.1
Authorization: Bearer your-token-here

這一層只判斷一件事：這個 Token 是不是合法的 Gateway Token。合法就允許建立連接，不合法直接斷開。這是門衛(wèi)，只管"能不能進(jìn)門"。

第二層：你是什么角色？（連接握手 Role）

進(jìn)門之后，客戶端發(fā)第一條消息——connect 消息：

{
  "method": "connect",
  "params": {
    "token": "...",
    "role": "operator",
    "clientId": "macos-app"
  }
}

這里的 role 只有兩個值：

• operator：人類操作者。CLI、macOS App、Web UI 都是 operator。
• node：設(shè)備節(jié)點(diǎn)。iPhone、Android、macOS 節(jié)點(diǎn)模式。

兩種角色能調(diào)用的方法完全隔離：

// src/gateway/role-policy.ts
export function isRoleAuthorizedForMethod(role, method) {
  if (isNodeRoleMethod(method)) {
    return role === "node";   // node 專屬方法：只有設(shè)備節(jié)點(diǎn)能調(diào)用
  }
  return role === "operator"; // 其余方法：只有人類操作者能調(diào)用
}

iPhone（node 角色）不能調(diào)用 config.apply 修改配置——即使它拿到了合法 Token，role 不對就是不行。反過來，CLI（operator 角色）也調(diào)不了 node.invoke.result（那是設(shè)備節(jié)點(diǎn)上報執(zhí)行結(jié)果用的）。

為什么要把 role 放在 connect 消息而不是 HTTP 層？

因為 HTTP 層只是"進(jìn)門"，而 role 決定"進(jìn)門后能去哪個房間"。把兩層分開，可以用同一個 Token 連接，但根據(jù) role 獲得不同權(quán)限——這在測試和調(diào)試時非常方便。

第三層：你能做什么？（Scope 細(xì)粒度控制）

對于 operator 角色，還有更細(xì)的 scope 控制：

// src/gateway/method-scopes.ts
const READ_SCOPE  = "operator.read";   // 只讀：看狀態(tài)、查配置
const WRITE_SCOPE = "operator.write";  // 寫操作：觸發(fā) Agent、改配置
const ADMIN_SCOPE = "operator.admin";  // 全部權(quán)限

這解決了一個實際需求：Web UI 可以對外暴露（比如給團(tuán)隊成員查看 AI 執(zhí)行日志），但你不想讓他們能觸發(fā) Agent 運(yùn)行或修改配置。只要給他們的連接只分配 READ_SCOPE，就做到了權(quán)限隔離，而不需要維護(hù)多套 Token。

三層合在一起：

HTTP Token   → 你能不能連進(jìn)來？
Role         → 你是人類操作者還是設(shè)備節(jié)點(diǎn)？
Scope        → 在你的角色范圍內(nèi)，你能做哪些具體操作？

第三個設(shè)計決策：connect為什么必須是第一條消息？

現(xiàn)在理解了認(rèn)證的三層設(shè)計，你會自然想到一個問題：

Role 和 Scope 信息在 connect 消息里，但 Token 在 HTTP 頭里。為什么不把所有認(rèn)證信息都放 HTTP 頭里，省掉這個 connect 步驟？

因為 WebSocket 連接在 HTTP 升級之后，服務(wù)端就不知道這個連接的身份了——HTTP 頭只在建立連接時傳一次，之后的 WebSocket 幀里沒有 HTTP 頭。

所以必須在 WebSocket 層再做一次認(rèn)證握手，connect 消息就是這個握手。

客戶端 → 服務(wù)端: HTTP Upgrade（帶 Bearer Token）
                 [第一層：能不能進(jìn)門]

WebSocket 連接建立

客戶端 → 服務(wù)端: { method: "connect", params: { role, scopes, clientId, ... } }
                 [第二層+第三層：進(jìn)來之后是誰，能做什么]

服務(wù)端 → 客戶端: { type: "hello-ok", gatewayMethods: [...], events: [...], ... }
                 [握手完成，告訴客戶端這個 Gateway 支持什么]

如果 connect 之后再發(fā)一次 connect 會怎樣？

// src/gateway/server-methods/connect.ts
export const connectHandlers = {
  connect: ({ respond }) => {
    respond(false, undefined, errorShape("connect is only valid as the first request"));
  },
};

直接報錯。這 12 行的文件就是一個兜底——真正的 connect 處理邏輯在更底層（ws-connection/message-handler.ts），在進(jìn)入 Handler 路由之前就已經(jīng)處理了。正常連接中你永遠(yuǎn)不會碰到這個兜底 Handler。

hello-ok 里有什么？

服務(wù)端返回的不只是"認(rèn)證成功"，還有完整的能力清單：

{
  type: "hello-ok",
  gatewayMethods: ["health", "agent", "sessions.list", ...],  // 這個 Gateway 支持哪些 RPC 方法
  events: ["agent", "presence", "tick", ...],                  // 會推哪些事件
  healthSnapshot: { ... },    // 當(dāng)前系統(tǒng)健康快照
  presenceSnapshot: { ... },  // 當(dāng)前在線狀態(tài)快照
}

注意 gatewayMethods 是動態(tài)生成的：

// src/gateway/server-methods-list.ts
export function listGatewayMethods(): string[] {
  const channelMethods = listChannelPlugins()
    .flatMap((plugin) => plugin.gatewayMethods ?? []);
  return Array.from(new Set([...BASE_METHODS, ...channelMethods]));
}

如果你安裝了 MS Teams 插件，它可以注冊自己的 RPC 方法，這個列表就會多出來。客戶端在握手時就知道服務(wù)端支持什么，不用靠文檔猜，也不用靠版本號判斷兼容性。

第四個設(shè)計決策：90 個方法怎么管理？

Gateway 總共支持約 90 個 RPC 方法（health、agent、sessions.list、config.set…）。

這些方法怎么注冊？OpenClaw 的解法出奇地簡單：

// src/gateway/server-methods.ts
export const coreGatewayHandlers = {
  ...connectHandlers,    // connect
  ...healthHandlers,     // health
  ...agentHandlers,      // agent, agent.wait
  ...sessionsHandlers,   // sessions.list, sessions.patch, sessions.reset ...
  ...configHandlers,     // config.get, config.set, config.apply ...
  ...cronHandlers,       // cron.list, cron.add, cron.run ...
  ...skillsHandlers,     // skills.status, skills.install ...
  ...nodeHandlers,       // node.list, node.invoke ...
  // ... 共約 30 個 handler 組
};

這是一個扁平的 JavaScript 對象：key 是方法名字符串，value 是處理函數(shù)。沒有路由樹，沒有中間件鏈，就是一個 Map。

當(dāng)一條消息進(jìn)來：

// 查找 handler → 調(diào)用
const handler = extraHandlers?.[req.method] ?? coreGatewayHandlers[req.method];
if (!handler) { respond(error("unknown method")); return; }
handler({ req, respond, client, context });

為什么不用更"正規(guī)"的路由框架？

因為 90 個方法對路由樹來說完全沒必要——哈希表查找是 O(1)，路由樹反而引入了額外的解析開銷和代碼復(fù)雜度。

插件怎么擴(kuò)展方法？

注意 extraHandlers?.[req.method] 在前面——插件注冊的 Handler 優(yōu)先級高于核心 Handler。插件只需要 export 一個同類型的對象，在加載時 spread 進(jìn)去，就能注冊新方法，甚至可以覆蓋內(nèi)置方法的行為。

第五個設(shè)計決策：如何讓多個客戶端實時同步？

Gateway 維護(hù)了一個所有已連接客戶端的集合：

const clients = new Set<GatewayWsClient>();

當(dāng) AI 產(chǎn)生新的輸出，Gateway 調(diào)用 broadcast 函數(shù)，向集合里的每個客戶端發(fā)送事件：

broadcast("agent", {
  phase: "streaming",
  sessionKey: "agent:main:dm:alice",
  text: "正在分析你的文件...",
})

所有連接的客戶端——不管是 CLI、Web UI 還是 iPhone——同時收到這條消息，實時顯示 AI 的輸出。

一個細(xì)節(jié)：如果客戶端斷線重連，怎么恢復(fù)狀態(tài)？

broadcast 函數(shù)有一個 stateVersion 參數(shù)：

broadcast("presence", payload, {
  stateVersion: { presence: currentPresenceVersion }
})

每次狀態(tài)變化，版本號 +1?？蛻舳酥剡B時，帶上自己記住的最后版本號。如果服務(wù)端的版本更新了，就發(fā)送完整的狀態(tài)快照而不是增量。

這解決了一個經(jīng)典的分布式問題：客戶端斷線期間錯過的狀態(tài)變化，怎么補(bǔ)齊？ 答案是：不補(bǔ)，直接發(fā)最新全量狀態(tài)。簡單可靠，不會出現(xiàn)漏更新導(dǎo)致的狀態(tài)不一致。

把所有設(shè)計連起來看

現(xiàn)在可以畫出 Gateway 的完整工作流程：

1. 用戶在 WhatsApp 發(fā)消息
          ↓
2. WhatsApp 通道收到消息，通過內(nèi)部事件傳給 Gateway
          ↓
3. Gateway 路由層決定交給哪個 Agent 的哪個會話
（這部分是下一篇的主題：通道與路由系統(tǒng)）
          ↓
4. Agent 開始執(zhí)行，產(chǎn)生流式輸出
          ↓
5. Gateway 調(diào)用 broadcast("agent", { text: "..." })
          ↓
6. 所有連接的客戶端同時收到：
   - Web UI 實時顯示進(jìn)度
   - iPhone App 顯示通知
   - CLI 打印輸出
          ↓
7. Agent 執(zhí)行完，回復(fù)通過 Gateway 發(fā)回 WhatsApp

每一個環(huán)節(jié)的設(shè)計選擇都有清晰的來由：

啟動流程：Gateway 上電時做了什么

理解了設(shè)計之后，再來看啟動流程就很自然了。Gateway 的 startGatewayServer() 函數(shù)按以下順序初始化：

① 讀取配置文件，如果是舊格式就自動遷移
② 預(yù)檢所有密鑰引用——有一個不存在就立刻報錯退出（Fail-Fast）
③ 生成或驗證 Gateway Token
④ 加載所有插件（通道插件、功能插件）
⑤ 建立所有消息通道的連接（WhatsApp、Telegram、Slack...）
⑥ 掛載 WebSocket 處理器，開始監(jiān)聽
⑦ 啟動 Cron 任務(wù)調(diào)度、心跳監(jiān)控、本地網(wǎng)絡(luò)發(fā)現(xiàn)

第②步的"Fail-Fast"設(shè)計值得單獨(dú)說一下：如果配置里引用了一個不存在的 API Key，很多系統(tǒng)的處理方式是"先跑起來，用到的時候再報錯"。OpenClaw 不這樣——啟動時就檢查，發(fā)現(xiàn)問題就拒絕啟動，明確報錯。

這對個人 AI 助手來說尤為重要：一個帶著錯誤配置運(yùn)行的助手，會出現(xiàn)"發(fā)消息沒有回應(yīng)"這種極難調(diào)試的問題。不如一開始就讓它無法啟動，錯誤信息清清楚楚。

小結(jié)

本篇從用戶使用場景出發(fā)，推導(dǎo)了 Gateway 的每一個核心設(shè)計：

• 為什么需要 Gateway：多通道、多客戶端需要一個協(xié)調(diào)中樞
• 為什么用 WebSocket：實時雙向通信是剛需，HTTP 做不到
• 為什么要 connect 握手：WebSocket 層需要自己的認(rèn)證機(jī)制
• 為什么三層認(rèn)證：不同客戶端信任級別不同，權(quán)限需要分層
• 為什么用扁平 Handler Map：簡單夠用，插件擴(kuò)展零阻力
• 為什么版本號 + 全量快照：斷線重連場景下最可靠

WhatsApp 來一條消息，OpenClaw 怎么知道應(yīng)該交給哪個 Agent？如果你配置了多個 Agent，不同的群組、不同的聯(lián)系人，怎么路由到正確的地方？

這背后是一套 8 級優(yōu)先級的路由規(guī)則，設(shè)計得相當(dāng)精妙。

對應(yīng)代碼：src/gateway/ | 關(guān)鍵文件：server.impl.ts、server-methods.ts、role-policy.ts、method-scopes.ts

到此這篇關(guān)于OpenClaw核心組件Gateway原理解析：聊天渠道的連接、消息路由、會話狀態(tài)維護(hù)以及安全認(rèn)證的文章就介紹到這了,更多相關(guān)OpenClaw核心組件Gateway原理解析內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論