OpenClaw Telegram threads and sessions

A Telegram forum supergroup is a set of topics that behave like separate rooms, and OpenClaw treats them that way: each topic gets its own session key, can inherit or override the group's settings, and can be routed to a different agent with its own workspace and memory. Here is the session key shape, the General topic quirk, the inheritance rules, the per-topic agent pattern, the ACP bindings, and the rule for DM threads.

Topics as sessions

• In forum supergroups the topic session key appends a topic suffix with the thread ID, replies and typing target the topic thread, and the topic's config lives under the group entry's topics map keyed by thread ID.
• The General topic, thread ID one, is special: message sends omit the thread ID because Telegram rejects a send addressed to thread one with a thread-not-found error, while typing actions still include it, since that is empirically required for the typing indicator to appear.
• Topic entries inherit the group's mention requirement, allowlist, skills, system prompt, enabled flag and group policy unless overridden, the agent ID is topic-only and never inherits from the group defaults, and a wildcard topic entry sets defaults for every topic in that group with exact topic IDs still winning.
• Each topic can route to a different agent through the agent ID in its config, giving it its own workspace, memory and session: the docs' example sends the General topic to the main agent, a Dev topic to a second agent and a code-review topic to a coder agent, and each topic then has a session key naming its agent, the channel, the group and the topic.

BotFather threaded mode is the single source of truth.

ACP bindings

Forum topics can pin ACP harness sessions through top-level typed bindings: a binding of type acp matching the Telegram channel with a group peer and a topic-qualified ID, the group chat ID followed by the topic suffix and thread ID, currently scoped to forum topics in groups and supergroups. From inside a chat, the spawn command with a thread flag set to here or auto binds the current topic to a new ACP session, follow-ups route there directly, and OpenClaw pins the spawn confirmation in the topic; the behaviour is controlled by the thread-bindings spawn-sessions setting under the session block, which is on by default.

Template context and DM threads

• Template context exposes the message thread ID and whether the chat is a forum, so prompts and templates can branch on the topic they are running in.
• DM chats with a thread ID keep their reply metadata but only use thread-aware session keys when the bot's getMe reports topics enabled, which BotFather's threaded mode controls; otherwise DMs stay on the flat session.
• The retired DM thread-replies overrides at the DM level and under each direct entry are gone, BotFather threaded mode is the single source of truth, and the doctor fix removes the stale keys from an upgraded config.

OpenClaw on Telegram is the channel post these sessions belong to, and OpenClaw Telegram message behaviour how a reply is delivered into the right topic.

One group, several agents

Per-topic agents are the cleanest way to run a small team of specialists inside one supergroup: the same people, the same group rules, but a different agent, workspace and memory behind each topic. OpenClaw channel routing explains the binding model that makes the topic-qualified peer a route, and OpenClaw Slack threads and sessions shows how Slack reaches a similar result with threads instead of topics.

On Diali

Telegram is one of the channels Diali connects from the dashboard, with the runtime config generated and replaced at each release, so the topic and session keys here describe how a hosted agent behaves in a forum group rather than a file you maintain. Telegram on Diali is the channel on Diali and Hosted OpenClaw on Diali the assistant behind it.

• Every topic is its own session; General sends without a thread ID.
• Topics inherit group settings, never the agent ID.
• DM threads split only when BotFather's threaded mode is on.