Telegram threads and sessions

Forum supergroups: topic session keys append :topic:<threadId>; replies and typing target the topic thread; topic config path is channels.telegram.groups.<chatId>.topics.<threadId>.

Topic IDs must be positive integers. OpenClaw rejects topic 0 in delivery targets and explicit thread options before making Telegram requests.

General topic (threadId=1) is a special case: message sends omit message_thread_id (Telegram rejects sendMessage(...thread_id=1) with "thread not found"), but typing actions still include message_thread_id (empirically required for the typing indicator to appear).

Topic entries inherit group settings unless overridden (requireMention, requireMentionInBotThreads, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId is topic-only and does not inherit from group defaults. topics."*" sets defaults for every topic in that group; exact topic IDs still win over "*".

Per-topic agent routing: each topic can route to a different agent via agentId in the topic config, giving it its own workspace, memory, and session:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic -> main agent
            "3": { agentId: "zu" },        // Dev topic -> zu agent
            "5": { agentId: "coder" }      // Code review -> coder agent
          }
        }
      }
    }
  }
}

Each topic then has its own session key, for example agent:zu:telegram:group:-1001234567890:topic:3.

Persistent ACP topic binding: forum topics can pin ACP harness sessions through top-level typed bindings (bindings[] with type: "acp", match.channel: "telegram", peer.kind: "group", and a topic-qualified id like -1001234567890:topic:42). Currently scoped to forum topics in groups/supergroups. See ACP Agents.

Thread-bound ACP spawn from chat: /acp spawn <agent> --thread here|auto binds the current topic to a new ACP session; follow-ups route there directly, and OpenClaw pins the spawn confirmation in-topic. Controlled by session.threadBindings.spawnSessions (default: true).

Startup waits for stored thread bindings before accepting updates. Shutdown drains accepted binding changes before a replacement bot reloads them. Bundled Telegram handlers persist bindings through the shared SQLite worker so storage does not block message handling. Deprecated synchronous Plugin SDK touch and lifecycle setters keep their immediate behavior on the same binding owner until the next SDK major.

Disabling threadBindings.enabled globally, for Telegram, or for one account leaves ordinary Telegram messages working.

Template context exposes MessageThreadId and IsForum. DM chats with message_thread_id keep reply metadata but only use thread-aware session keys when Telegram getMe reports has_topics_enabled: true. The retired dm.threadReplies and direct.*.threadReplies overrides are gone; BotFather threaded mode is the single source of truth. Run openclaw doctor --fix to remove stale config keys.