OpenClaw 功能请求：Telegram 渠道支持 Thread Binding

文档信息

1. 问题描述

1.1 当前行为

当用户使用 sessions_spawn 创建子代理时，如果同时设置 mode="session" 和 thread=true 参数，系统会抛出以下错误：

mode="session" requires thread=true so the subagent can stay bound to a thread.
thread=true is unavailable because no channel plugin registered subagent_spawning hooks.

1.2 预期行为

用户应能够在 Telegram 渠道中使用 mode="session" 和 thread=true 参数组合，以创建持久化的子代理会话，并将子代理绑定到特定的 Telegram conversation/thread。

1.3 影响范围

• 受影响用户：所有使用 Telegram 渠道的 OpenClaw 用户
• 受影响功能：子代理会话持久化、线程绑定
• 当前限制：仅 Discord 渠道支持此功能

2. 原因分析

2.1 技术根因

2.2 源码位置

• Telegram 渠道入口：extensions/telegram/index.ts
• Discord 参考实现：extensions/discord/src/subagent-hooks.ts
• 关键函数：registerDiscordSubagentHooks
• 核心 API：autoBindSpawnedDiscordSubagent

2.3 缺失组件

Telegram 渠道缺少以下关键组件：

1. subagent_spawning 事件监听器注册
2. subagent_ended 事件监听器注册
3. Thread Binding 管理器
4. 相关配置项支持

3. 功能请求

3.1 核心需求

在 Telegram 渠道插件中注册 subagent_spawning hook，实现 thread binding 功能，使用户能够：

1. ✅ 使用 mode="session" 创建持久化子代理会话
2. ✅ 将子代理绑定到 Telegram 的 conversation/thread
3. ✅ 通过配置项控制 thread binding 行为

3.2 建议实现方案

3.2.1 代码结构

在 extensions/telegram/index.ts 中添加以下内容：

// 1. 注册 Telegram Subagent Hooks 函数
function registerTelegramSubagentHooks() {
  // 监听 subagent_spawning 事件
  // 监听 subagent_ended 事件
}

// 2. 创建 Thread Binding 管理器
function createTelegramThreadBindingManager() {
  // 管理 binding 状态
  // 处理会话生命周期
}

3.2.2 事件监听

3.2.3 配置项设计

添加新的配置项 channels.telegram.threadBindings：

channels:
  telegram:
    threadBindings:
      enabled: true              # 是否启用 thread binding
      spawnSubagentSessions: true # 是否允许创建子代理会话
      idleTimeoutMs: 3600000     # 空闲超时（1 小时）
      maxAgeMs: 86400000         # 最大生命周期（24 小时）

3.3 参考实现

完整参考 Discord 渠道的实现：

• 文件路径：extensions/discord/src/subagent-hooks.ts
• 入口函数：registerDiscordSubagentHooks()
• Binding API：autoBindSpawnedDiscordSubagent()

建议采用相似的设计模式，确保跨渠道一致性。

4. 用户价值

4.1 功能收益

4.2 使用场景

1. 长期对话任务：需要跨多轮对话保持上下文的场景
2. 复杂任务处理：需要子代理独立处理但保持关联的任务
3. 资源优化：避免频繁创建/销毁会话的开销

5. 技术评估

5.1 难度评估

5.2 测试建议

• 单元测试：hook 注册与事件处理
• 集成测试：子代理创建与 binding
• 配置测试：各项配置参数生效验证
• 边界测试：超时、生命周期管理

6. 附录

6.1 错误信息全文

mode="session" requires thread=true so the subagent can stay bound to a thread.
thread=true is unavailable because no channel plugin registered subagent_spawning hooks.

6.2 相关文件路径

extensions/telegram/index.ts          # 目标修改文件
extensions/discord/src/subagent-hooks.ts  # 参考实现

6.3 配置示例（完整版）

channels:
  telegram:
    threadBindings:
      enabled: true
      spawnSubagentSessions: true
      idleTimeoutMs: 3600000      # 1 小时
      maxAgeMs: 86400000          # 24 小时