OpenClaw 會話綁定架構:實現跨渠道路由與核心介面
寫過跨平台 Bot 的開發者都知道,處理 Session 綁定簡直是噩夢。你可能遇過訊息在 Discord 頻道和 Thread 之間亂跳,或者因為 Token 過期導致發送失敗,這些問題通常是因為業務邏輯與特定頻道的實作細節過度耦合。
這份文件定義了長期的 Channel Agnostic(頻道無關)Session 綁定模型,並明確了下一次實作迭代的具體範圍,幫助你建立更穩健的路由機制。
Session Binding Channel Agnostic 方案
Section titled “Session Binding Channel Agnostic 方案”本文件定義了長期的 Channel Agnostic Session 綁定模型,以及下一個實作迭代的具體範圍。
目標:
- 將 subagent 綁定的 Session 路由作為核心功能
- 將特定頻道的行為保留在 Adapter 中
- 避免 Discord 常規行為出現退化(Regression)
為什麼需要這個方案
Section titled “為什麼需要這個方案”目前的行為混合了以下內容:
- Completion 內容政策
- 目的地路由政策
- Discord 特定細節
這導致了一些邊緣情況:
- 在並行執行下,主頻道和 Thread 同時交付重複內容
- 在重複使用的 Binding Manager 上使用過期的 Token
- Webhook 發送時缺少活動統計
第一階段迭代範圍
Section titled “第一階段迭代範圍”此迭代刻意限制了範圍。
1. 新增 Channel Agnostic 核心介面
Section titled “1. 新增 Channel Agnostic 核心介面”為 Binding 和 Routing 增加核心類型與服務介面。
建議的核心類型:
export type BindingTargetKind = "subagent" | "session";export type BindingStatus = "active" | "ending" | "ended";
export type ConversationRef = { channel: string; accountId: string; conversationId: string; parentConversationId?: string;};
export type SessionBindingRecord = { bindingId: string; targetSessionKey: string; targetKind: BindingTargetKind; conversation: ConversationRef; status: BindingStatus; boundAt: number; expiresAt?: number; metadata?: Record<string, unknown>;};核心服務合約:
export interface SessionBindingService { bind(input: { targetSessionKey: string; targetKind: BindingTargetKind; conversation: ConversationRef; metadata?: Record<string, unknown>; ttlMs?: number; }): Promise<SessionBindingRecord>;
listBySession(targetSessionKey: string): SessionBindingRecord[]; resolveByConversation(ref: ConversationRef): SessionBindingRecord | null; touch(bindingId: string, at?: number): void; unbind(input: { bindingId?: string; targetSessionKey?: string; reason: string; }): Promise<SessionBindingRecord[]>;}2. 為 subagent completion 增加一個核心交付路由器
Section titled “2. 為 subagent completion 增加一個核心交付路由器”為 Completion 事件增加單一的目的地解析路徑。
路由器合約:
export interface BoundDeliveryRouter { resolveDestination(input: { eventKind: "task_completion"; targetSessionKey: string; requester?: ConversationRef; failClosed: boolean; }): { binding: SessionBindingRecord | null; mode: "bound" | "fallback"; reason: string; };}在此迭代中:
- 只有
task_completion會通過這個新路徑進行路由 - 其他事件類型的現有路徑保持不變
3. 保持 Discord 作為 Adapter
Section titled “3. 保持 Discord 作為 Adapter”Discord 仍然是第一個 Adapter 實作。
Adapter 的職責:
- 建立或重複使用 Thread 對話
- 透過 Webhook 或頻道發送來傳遞綁定的訊息
- 驗證 Thread 狀態(已封存或已刪除)
- 映射 Adapter 元數據(Webhook 身份、Thread ID)
4. 修正目前已知的正確性問題
Section titled “4. 修正目前已知的正確性問題”此迭代要求完成:
- 重複使用現有 Thread Binding Manager 時刷新 Token
- 記錄基於 Webhook 的 Discord 發送的 outbound 活動
- 當為 Session 模式 Completion 選擇了綁定的 Thread 目的地時,停止隱式回退到主頻道
5. 保留目前的執行安全性預設值
Section titled “5. 保留目前的執行安全性預設值”對於停用 Thread 綁定產生的用戶,行為不會改變。
預設值保持:
channels.discord.threadBindings.spawnSubagentSessions = false
結果:
- 一般 Discord 用戶維持現有行為
- 新的核心路徑僅影響已啟用的綁定 Session Completion 路由
不包含在第一階段的內容
Section titled “不包含在第一階段的內容”明確延後處理的項目:
- ACP 綁定目標 (
targetKind: "acp") - 除 Discord 以外的新頻道 Adapter
- 全域替換所有交付路徑(如
spawn_ack、未來的subagent_message) - 協議層級的變更
- 所有 Binding 持久化的存儲遷移或版本重新設計
關於 ACP 的說明:
- 介面設計為 ACP 預留了空間
- 此迭代不會開始 ACP 的實作
這些不變量在第一階段是強制性的。
- 目的地選擇與內容生成是分開的步驟
- 如果 Session 模式的 Completion 解析為一個活躍的綁定目的地,交付必須針對該目的地
- 不允許從綁定目的地隱藏重定向到主頻道
- 回退行為必須是明確且可觀察的
相容性與部署計畫
Section titled “相容性與部署計畫”相容性目標:
- 對於關閉 Thread 綁定產生的用戶,確保沒有功能退化
- 此迭代不對非 Discord 頻道進行任何變更
部署步驟:
- 在目前的 Feature Gate 下建立介面和路由器。
- 將 Discord Completion 模式的綁定交付引導至路由器。
- 為非綁定流程保留舊有路徑。
- 透過針對性測試和 Canary 執行日誌進行驗證。
第一階段必備測試
Section titled “第一階段必備測試”需要涵蓋單元測試與整合測試:
- Manager 重複使用後,Token 輪轉會使用最新的 Token
- Webhook 發送會更新頻道活動時間戳記
- 同一請求頻道中的兩個活躍綁定 Session 不會在主頻道產生重複內容
- 綁定 Session 模式執行的 Completion 僅解析為 Thread 目的地
- 停用 Spawn Flag 時,舊有行為保持不變
建議實作檔案
Section titled “建議實作檔案”核心部分:
src/infra/outbound/session-binding-service.ts(新檔案)src/infra/outbound/bound-delivery-router.ts(新檔案)src/agents/subagent-announce.ts(Completion 目的地解析整合)
Discord Adapter 與 Runtime:
src/discord/monitor/thread-bindings.manager.tssrc/discord/monitor/reply-delivery.tssrc/discord/send.outbound.ts
測試部分:
src/discord/monitor/provider*.test.tssrc/discord/monitor/reply-delivery.test.tssrc/agents/subagent-announce.format.test.ts
第一階段完成標準
Section titled “第一階段完成標準”- 核心介面已存在並完成 Completion 路由配置
- 上述正確性修正已併入並通過測試
- 在 Session 模式綁定執行中,不會出現主頻道與 Thread 重複交付 Completion 的情況
- 對於停用綁定產生的部署,行為沒有改變
- ACP 保持明確延後狀態
如果你在設定過程中遇到任何問題,可以參考我們的 AI Setup Assistant 獲取即時協助。
OpenClaw Expert
還是卡住了?
如果這篇文件沒有解決你的情境,直接問 OpenClaw Expert,拿到可執行步驟。