跳到內容

OpenClaw 會話綁定架構:實現跨渠道路由與核心介面

寫過跨平台 Bot 的開發者都知道,處理 Session 綁定簡直是噩夢。你可能遇過訊息在 Discord 頻道和 Thread 之間亂跳,或者因為 Token 過期導致發送失敗,這些問題通常是因為業務邏輯與特定頻道的實作細節過度耦合。

這份文件定義了長期的 Channel Agnostic(頻道無關)Session 綁定模型,並明確了下一次實作迭代的具體範圍,幫助你建立更穩健的路由機制。

本文件定義了長期的 Channel Agnostic Session 綁定模型,以及下一個實作迭代的具體範圍。

目標:

  • 將 subagent 綁定的 Session 路由作為核心功能
  • 將特定頻道的行為保留在 Adapter 中
  • 避免 Discord 常規行為出現退化(Regression)

目前的行為混合了以下內容:

  • Completion 內容政策
  • 目的地路由政策
  • Discord 特定細節

這導致了一些邊緣情況:

  • 在並行執行下,主頻道和 Thread 同時交付重複內容
  • 在重複使用的 Binding Manager 上使用過期的 Token
  • Webhook 發送時缺少活動統計

此迭代刻意限制了範圍。

為 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 會通過這個新路徑進行路由
  • 其他事件類型的現有路徑保持不變

Discord 仍然是第一個 Adapter 實作。

Adapter 的職責:

  • 建立或重複使用 Thread 對話
  • 透過 Webhook 或頻道發送來傳遞綁定的訊息
  • 驗證 Thread 狀態(已封存或已刪除)
  • 映射 Adapter 元數據(Webhook 身份、Thread ID)

此迭代要求完成:

  • 重複使用現有 Thread Binding Manager 時刷新 Token
  • 記錄基於 Webhook 的 Discord 發送的 outbound 活動
  • 當為 Session 模式 Completion 選擇了綁定的 Thread 目的地時,停止隱式回退到主頻道

5. 保留目前的執行安全性預設值

Section titled “5. 保留目前的執行安全性預設值”

對於停用 Thread 綁定產生的用戶,行為不會改變。

預設值保持:

  • channels.discord.threadBindings.spawnSubagentSessions = false

結果:

  • 一般 Discord 用戶維持現有行為
  • 新的核心路徑僅影響已啟用的綁定 Session Completion 路由

明確延後處理的項目:

  • ACP 綁定目標 (targetKind: "acp")
  • 除 Discord 以外的新頻道 Adapter
  • 全域替換所有交付路徑(如 spawn_ack、未來的 subagent_message)
  • 協議層級的變更
  • 所有 Binding 持久化的存儲遷移或版本重新設計

關於 ACP 的說明:

  • 介面設計為 ACP 預留了空間
  • 此迭代不會開始 ACP 的實作

這些不變量在第一階段是強制性的。

  • 目的地選擇與內容生成是分開的步驟
  • 如果 Session 模式的 Completion 解析為一個活躍的綁定目的地,交付必須針對該目的地
  • 不允許從綁定目的地隱藏重定向到主頻道
  • 回退行為必須是明確且可觀察的

相容性目標:

  • 對於關閉 Thread 綁定產生的用戶,確保沒有功能退化
  • 此迭代不對非 Discord 頻道進行任何變更

部署步驟:

  1. 在目前的 Feature Gate 下建立介面和路由器。
  2. 將 Discord Completion 模式的綁定交付引導至路由器。
  3. 為非綁定流程保留舊有路徑。
  4. 透過針對性測試和 Canary 執行日誌進行驗證。

需要涵蓋單元測試與整合測試:

  • Manager 重複使用後,Token 輪轉會使用最新的 Token
  • Webhook 發送會更新頻道活動時間戳記
  • 同一請求頻道中的兩個活躍綁定 Session 不會在主頻道產生重複內容
  • 綁定 Session 模式執行的 Completion 僅解析為 Thread 目的地
  • 停用 Spawn Flag 時,舊有行為保持不變

核心部分:

  • 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.ts
  • src/discord/monitor/reply-delivery.ts
  • src/discord/send.outbound.ts

測試部分:

  • src/discord/monitor/provider*.test.ts
  • src/discord/monitor/reply-delivery.test.ts
  • src/agents/subagent-announce.format.test.ts
  • 核心介面已存在並完成 Completion 路由配置
  • 上述正確性修正已併入並通過測試
  • 在 Session 模式綁定執行中,不會出現主頻道與 Thread 重複交付 Completion 的情況
  • 對於停用綁定產生的部署,行為沒有改變
  • ACP 保持明確延後狀態

如果你在設定過程中遇到任何問題,可以參考我們的 AI Setup Assistant 獲取即時協助。

OpenClaw

OpenClaw Expert

還是卡住了?

如果這篇文件沒有解決你的情境,直接問 OpenClaw Expert,拿到可執行步驟。