一個人用剛好,一百人就擠 左邊一大群使用者擠向中間的 Gateway 圓點,越靠近越擁擠;Gateway 把會話寫進一疊 JSONL 檔案,檔案上掛著一把鎖;鎖後面一長串寫入請求蛇形排隊,等著同一把鎖。 Gateway

Gateway 是 OpenClaw 生態中的常駐閘道器程序。它以單例項執行,持有所有訊息渠道的連線——WhatsApp、Telegram、Slack、Discord、Signal、iMessage——是所有訊息進出的唯一入口。使用者從任何渠道發來的訊息,都先到 Gateway,由它路由到對應的 AI agent,再把響應送回去。控制面客戶端(macOS app、CLI、Web UI)透過 WebSocket 連線 Gateway,Gateway 再對接各訊息平臺和 AI 後端。換句話說,它既是訊息的中樞,也是會話狀態的管理中心。

這篇文章要聊的就是後者——Gateway 怎麼管理會話狀態。它最核心的工作不是轉發請求,而是把一條條離散的訊息串成連貫的對話。OpenClaw 的會話管理設計在小規模場景下優雅得令人舒適,但當使用者和任務規模上來之後,它的檔案系統架構會成為瓶頸。


一、會話串聯機制

Session Key:一切的起點

使用者從 WhatsApp 發來一條訊息,Gateway 要解決的第一個問題是:這條訊息屬於哪個對話?

OpenClaw 的做法是給每個對話分配一個 Session Key——一個結構化的路由識別符號。格式長這樣:

agent:<agentId>:<channel>:dm:<peerId>
agent:<agentId>:<channel>:group:<groupId>
agent:<agentId>:<channel>:channel:<channelId>

Channel 是訊息來源(WhatsApp、Telegram、Slack),peerId 是傳送者的唯一標識,agentId 是處理這條訊息的 AI agent。三層組合,精確鎖定一個對話上下文。

關鍵在於,同一個使用者從不同渠道發來的訊息,可以透過 Identity Links 對映到同一個 canonical identity,進而路由到同一個 Session。也就是說,你在 WhatsApp 上跟 AI 聊了半截,切到 Telegram 繼續聊,上下文不丟。

兩層持久化模型

Session 找到了,接下來要把歷史上下文載入出來。OpenClaw 用了兩層儲存:

第一層:Session Store(sessions.json)

一個 JSON 檔案,存在 ~/.openclaw/agents/<agentId>/sessions/sessions.json,是所有 session 的索引。每個 entry 記錄了 session 的後設資料——最近活躍時間、token 用量、關聯的 transcript 檔案路徑。

讀取時走記憶體快取(TTL 45 秒),避免每次請求都讀磁碟。寫入時用檔案鎖 + 臨時檔案原子重新命名,保證併發安全。

第二層:Transcript 檔案(*.jsonl)

每個 session 對應一個 JSONL 檔案,存完整的對話歷史。格式是追加寫入的樹結構——每條記錄有 id 和 parentId,支援對話分叉和回溯。

~/.openclaw/agents/<agentId>/sessions/
├── sessions.json # session 索引
├── abc123.jsonl # session abc123 的完整对话
├── def456.jsonl # session def456 的完整对话
└── ...

一次請求的完整鏈路

把流程拉直了看:

1. 消息进来 → 提取 channel + peerId + agentId
2. 构造 Session Key → "agent:bot1:whatsapp:dm:user42"
3. 查 Session Store → 命中缓存或读 sessions.json
4. 加载 Transcript → 读 JSONL,重建对话树
5. 构建上下文 → 从树中提取最近的对话路径
6. 发给模型 → 带着完整上下文调 Claude/GPT
7. 追加响应 → 写入 JSONL,更新 sessions.json
8. 返回给用户

步驟 4 和 5 是精髓。對話不是一個扁平的訊息列表,而是一棵樹。當對話太長觸發壓縮時,舊的訊息會被 AI 總結成摘要,保留在樹的根部。新訊息掛在摘要節點下面,模型看到的是”摘要 + 最近的訊息”——既不丟上下文,又控制了 token 用量。

這就是 Gateway 把前後串起來的方式:用 Session Key 路由,用 JSONL 存歷史,用樹結構管理上下文視窗。


二、架構優勢

1. 跨渠道的上下文連續性

使用者不需要關心自己在哪個平臺。WhatsApp 上問了一半的問題,切到 Slack 上繼續追問,AI 記得之前說了什麼。

這在實際使用中的體驗提升是巨大的。特別是對於需要在手機和電腦之間切換的場景——手機上用 WhatsApp 快速發個指令,回到電腦上在 Slack 裡看詳細結果,對話不會斷。

2. 對話樹而非對話列表

JSONL 的樹結構允許對話分叉。你可以從對話的某個中間節點重新開始,不需要清掉後面的內容。這對除錯和實驗特別有用——“從第三輪重來,換個方向試試”。

append-only 的寫入模式也意味著不會丟資料。即使程序崩潰,最多丟當前這一輪的響應,歷史對話完好無損。

3. 自動壓縮保持上下文視窗可控

當對話超過 token 閾值時,自動觸發 compaction:舊訊息被總結成摘要,釋放 token 空間。預設預留 16,384 token 給新的對話輪次。

這個設計讓長對話成為可能。你不需要手動”清理上下文”或者擔心”聊太多了模型忘了前面的”——系統自動處理。代價是壓縮過程中可能丟失一些細節,但對大部分場景來說是可接受的 trade-off。

4. Session Scope 的靈活配置

Gateway 提供了四檔 DM 隔離級別:

級別說明適用場景
main所有 DM 共享一個 session個人使用,只有自己在聊
per-peer按傳送者隔離多人共用一個 agent
per-channel-peer按渠道+傳送者隔離多渠道多人
per-account-channel-peer按賬號+渠道+傳送者隔離多賬號多渠道多人

一個配置項就能調整隔離粒度。個人用選 main,團隊用選 per-channel-peer,SaaS 用選最細粒度。

5. 零外部依賴

不需要 Redis,不需要 PostgreSQL,不需要任何外部儲存。一個檔案系統就夠了。部署時不需要操心資料庫連線池、Redis sentinel、儲存叢集——裝好 Node.js 就能跑。

對於個人開發者和小團隊,這是一個巨大的優點。運維複雜度低,除錯方便(直接看 JSON 檔案),備份簡單(cp -r 就行)。


三、規模化瓶頸

1. 檔案系統架構的天花板

所有 session 的寫操作都透過 withSessionStoreLock() 序列化——同一時刻只有一個寫入能執行。當併發寫入多了,後面的請求就在佇列裡排隊,超時設定是 10 秒。

來算一筆賬。假設一個 gateway 例項服務 100 個活躍使用者,每人每分鐘發 2 條訊息。每次寫入涉及更新 sessions.json + 追加 JSONL 檔案。如果單次寫入耗時 5ms,每秒 3.3 次寫入,看起來還好。

但實際上,檔案 I/O 的耗時波動很大。磁碟繁忙時一次寫入可能飆到 100ms 甚至更高。再加上 sessions.json 會隨著 session 數量增長變大(上限 10MB),讀寫時間也會增長。當寫入佇列開始積壓,使用者感知到的就是”發了訊息,AI 很久不回”。

正常情况:消息 → 5ms 锁等待 → 处理 → 响应
高负载时:消息 → 800ms 锁等待 → 处理 → 响应(用户已经发了第二条催促消息)
极端情况:消息 → 10s 超时 → 写入失败 → session 状态不一致

檔案鎖的瓶頸還只是縱向的問題。橫向上,Gateway 的架構是單程序、單主機——一個例項持有所有 messaging surface 的連線(WhatsApp session、Telegram bot token、Slack WebSocket),session 資料存在本地檔案系統。這意味著不能啟動第二個例項來分擔負載(WhatsApp 只允許一個活躍 session),不能把 session 資料遷移到另一臺機器(沒有分散式儲存),也沒有內建的叢集方案、session 複製或 failover。當你的使用者從 50 人漲到 500 人,唯一的出路是升級這臺機器的配置。垂直擴充套件總有盡頭。

2. 預設配置下的上下文洩露

dmScope 的預設值是 main——所有 DM 共享同一個 session。這在個人使用時完全沒問題,但當多個使用者同時跟 agent 對話時,A 能看到 B 的對話上下文。

官方文件明確警告了這個問題:

If your agent receives DMs from multiple people, you MUST enable secure DM mode. Without it, all users share the same conversation context, which can leak private information between users.

但預設值就是不安全的。對於不看文件的開發者(多數人),部署上線後才發現使用者之間能看到彼此的對話——這是一個嚴肅的隱私事故。

3. Session 膨脹與可觀測性缺失

每個對話一個 JSONL 檔案。檔案維護策略是:預設保留 500 個 session entry,超過 30 天的自動清理。聽起來還行?

但實際場景中,session 的增長速度往往超出預期:

  • 一個 Slack workspace 裡 50 個人跟 agent 聊天 → 50 個 session
  • 每個人同時在 DM 和 3 個 channel 裡跟 agent 互動 → 200 個 session
  • 再加上定時任務(cron job)觸發的 session → 每天多幾十個
  • 一個月下來輕輕鬆鬆破千

session 檔案的 JSONL 格式是 append-only,長對話的檔案會持續膨脹。一個活躍使用者一天幾百輪對話,JSONL 檔案幾 MB。sessions.json 作為索引檔案也在膨脹,接近 10MB 時觸發 rotation——但 rotation 本身就是一個耗時操作。檔案系統層面,一個目錄下幾千個檔案,ls 都開始變慢,更別說 Gateway 啟動時要掃描這個目錄了。

更棘手的是,這種膨脹幾乎是悄無聲息的。當前 Gateway 沒有提供 session 級別的指標儀表板(活躍 session 數、平均對話長度、壓縮頻率),沒有 session 生命週期事件的結構化日誌,也沒有異常 session 的告警機制(如某個 session 的 JSONL 檔案異常膨脹)。運維人員想回答”現在有多少活躍對話”這個問題,只能去數檔案;想知道”哪些 session 佔用了最多 token”,只能自己寫指令碼解析 JSONL。

在小規模使用時這不是問題——出了事直接看檔案。但當 session 數以千計時,缺乏可觀測性意味著你只能等問題爆發,而不是提前發現。Session 膨脹本身是可以管理的,前提是你能看見它——而這套系統恰恰讓你看不見。

4. 壓縮是有損的

對話壓縮看起來很美好——自動總結舊訊息,釋放 token 空間。但總結本身就是有失真壓縮。

被壓縮掉的內容包括:

  • 具體的數字和引數(“上次你說預算是 50 萬” → 壓縮後可能變成”之前討論了預算”)
  • 對話中的細微轉折(“你先說要 A,後來改主意要 B” → 可能只保留了 B)
  • 工具呼叫的詳細引數和返回值
  • 使用者糾正 AI 錯誤的過程

在任務型對話中,這些細節可能很關鍵。使用者說”按上次說的那個方案來”,但”上次說的方案”已經被壓縮成一句摘要了——AI 只能猜。

更麻煩的是,壓縮觸發時機不透明。使用者不知道哪些上下文還在、哪些已經被壓縮了。當 AI 突然”忘了”之前討論過的細節,使用者會困惑:是模型的問題還是上下文丟了?

5. 多 Agent 協作與長時任務

OpenClaw 支援多個 agent,每個 agent 有獨立的 session 空間。但 agent 之間沒有共享上下文的機制。一個典型場景:Agent A 負責客服,Agent B 負責技術支援,使用者先跟 A 聊了問題背景,A 判斷需要轉給 B——轉過去之後,B 對之前的對話一無所知,使用者要重新描述一遍。沒有 session 共享、沒有 session 轉移、沒有跨 agent 的上下文傳遞,每個 agent 是一個孤島。

跨 agent 協作的缺失只是表象,更深層的問題是系統缺乏高於 session 的任務抽象。OpenClaw 的典型任務——程式碼生成、文件分析、多輪工具呼叫——常常執行數十分鐘,但系統沒有一等公民的 Task 概念。當前的做法是用 sub-agent session 隱式承擔 task 角色:sessions_spawn() 建立一個獨立的 session,完成後透過 announce queue 通知主 session。這在簡單場景下夠用,但 sub-agent session 與真正的 Task 之間有明顯的 gap:

  • 無顯式狀態機——session 沒有 pending → running → succeeded/failed 的生命週期,只有”存在”和”不存在”
  • 無進度追蹤——主 session 不知道 sub-agent 執行到哪一步了,只能等最終結果
  • 無重試機制——sub-agent 失敗了就失敗了,沒有自動重試或斷點續跑
  • 無持久化佇列——如果 Gateway 程序崩潰,正在執行的 sub-agent 任務全部丟失

有趣的是,CronJob 反而有最完整的任務生命週期管理——runningAtMs 追蹤執行狀態、lastRunStatus 記錄成功失敗、還有卡住檢測機制。但這套邏輯僅限定時觸發場景,沒有泛化成通用的 Task 原語。

GitHub issue 也反映了這些痛點:

  • #6042:sub-agent 達到 context 上限後直接終止,沒有優雅降級或任務移交
  • #10334:announce 機制阻塞主 session,長時任務拖慢整個對話
  • #10467:缺乏 lane 隔離,多個長時任務互相干擾

本質上,OpenClaw 選擇了”漸進增強 session”而非引入獨立的 Task 原語。這與其”兩個抽象解釋一切”的設計哲學一致——Session 和 Agent 已經足夠解釋系統中的大部分行為,加入 Task 會打破這種簡潔性。但無論是跨 agent 協作還是長時任務管理,用 session 硬扛更高層抽象的職責,付出的都是可靠性的代價。


四、根源與出路

上面列的這些缺點不是因為程式碼寫得爛。恰恰相反,OpenClaw 的 session 管理程式碼質量很高——原子寫入、檔案鎖、快取失效、優雅降級,每一個細節都處理得很用心。

問題出在架構假設上——不止一個,而是兩個層面。

基礎設施層的假設

這套系統是為”一個人或一個小團隊在一臺機器上執行一個 AI 助手”設計的。在這個假設下,檔案系統是最好的選擇——簡單、可靠、零依賴。

但當使用場景從”Peter 的個人 WhatsApp 助手”變成”100 人團隊的 AI 基礎設施”時,這個假設就不再成立了。檔案鎖扛不住高併發,單機扛不住大流量,本地儲存扛不住多例項,預設配置扛不住多使用者。

領域模型層的假設

還有一個更隱蔽的問題:Session 的抽象直接耦合了外部平臺的概念,而不是建立在平臺無關的內部模型上。

回頭看 Session Key 的格式:agent:<agentId>:<channel>:dm:<peerId>。這裡的 channel——WhatsApp、Telegram、Slack——是一個外部平臺標識,被硬編碼進了路由層的最核心位置。系統的會話路由、隔離粒度、甚至 agent 協作,都建立在”訊息來自哪個平臺”這個外部概念上。

這帶來了幾個連鎖效應:

  • Identity Links 是補丁,不是地基。 跨平臺的身份關聯透過 Identity Links 實現——把 WhatsApp 的 user42 和 Telegram 的 user42 對映到同一個 canonical identity。但這是一層事後補上的對映關係,不是系統從一開始就內建的統一身份。如果系統有一個平臺無關的 Person 概念,跨平臺身份就不是”需要額外配置的特性”,而是”預設行為”。

  • dmScope 的隔離粒度用平臺維度定義。 per-channel-peer、per-account-channel-peer——這些隔離級別的命名方式本身就說明問題:隔離粒度是按”渠道”和”賬號”切分的,而不是按”這是誰”和”這是哪個群”切分的。如果系統內建 Person 和 Group 概念,隔離粒度是天然內建的——一個 Person 就是一個對話上下文,不需要額外配置 scope。

  • 跨 agent 協作困難,部分原因在這裡。 第三章提到 Agent A 轉給 Agent B 時上下文全丟。Session 繫結在 agent + channel + peerId 上,換一個 agent 就是換一個 session。但如果 session 繫結在 Person 上,agent 只是服務這個 Person 的執行者——換 agent 不需要換對話上下文,因為上下文屬於 Person,不屬於 agent。

本質上,OpenClaw 把”訊息來自 WhatsApp 還是 Telegram”當成了一等公民,而把”訊息來自張三還是李四”當成了需要額外配置才能識別的東西。這個優先順序是反的。在一個 IM 閘道器係統裡,Person 和 Group 才應該是一等公民,外部平臺應該只是介面卡。

兩層假設疊加,形成了經典困境

基礎設施層假設檔案系統夠用,領域模型層假設外部平臺概念可以直接作為內部抽象。兩個假設在小規模場景下都合理——一個人在一臺機器上透過一兩個平臺聊天,檔案系統夠用,平臺概念和內部模型也確實沒什麼區別。但當規模增長,這兩個假設同時失效:檔案系統扛不住併發,平臺耦合扛不住多樣性。

這是一個經典的架構演進困境:讓你快速起步的設計,恰恰是阻礙你規模化的那個東西。

出路

如果 OpenClaw 要認真地解決規模化問題,需要在以下方向上做出改變:

  1. 引入外部 session 儲存——Redis 或 PostgreSQL,支援多例項共享 session 狀態
  2. Gateway 叢集化——支援多例項部署,session 資料透過外部儲存共享
  3. 預設安全的隔離策略——dmScope 的預設值應該是 per-channel-peer 而不是 main
  4. session 的可觀測性——內建 metrics endpoint,暴露 session 級別的指標
  5. 跨 agent session 傳遞——允許 agent 之間共享或轉移對話上下文
  6. 引入 Task 抽象——為長時執行的操作提供顯式的生命週期管理(狀態機、進度追蹤、重試、持久化佇列),而不是繼續用 session 隱式承載
  7. 引入平臺無關的內部會話模型——以 Person 和 Group 為一等公民構建 session 路由,外部平臺(WhatsApp、Telegram、Slack)降級為介面卡層;Session Key 不再編碼 channel,Identity Links 從可選配置變成預設行為,隔離粒度自然內建於 Person/Group 的邊界中

但這些改變中的每一項都會增加複雜度,犧牲當前架構”零依賴、開箱即用”的核心優勢。這又回到了那個永恆的 trade-off:簡單和可擴充套件,你只能選一個。

OpenClaw 選了簡單。對它的目標使用者來說,這可能是對的。