How Telegram Topics Became Separate OpenClaw Workspaces

A Telegram topic looks like a folder in the client. By March 2026, OpenClaw had made it something more consequential: a routing boundary that could own a separate conversation, model, agent workspace or persistent coding harness.

That did not arrive as one feature. It emerged in layers across three releases. Understanding those layers matters because a separate topic session is not automatically a separate agent, and a dedicated agent is not the same thing as a bound ACP coding session. Operators who collapse those concepts can isolate chat history while accidentally sharing a workspace, model or runtime.

January: a thread became a session boundary

The first important boundary was conversational. PR #1597, merged on 25 January 2026, derived thread-aware keys for Telegram direct-message topics. Its stated purpose was to make each DM thread its own session context while preserving DM history-limit lookup and command targeting.

The v2026.1.24 release, published later that day, explicitly shipped “DM topics as separate sessions.” Forum groups already used topic-qualified keys: the historical Telegram documentation shows group session keys ending in :topic:<threadId>, with replies and typing indicators sent back to the same thread.

The intended and shipped behaviour was a distinct session key for each supported topic. That separated which transcript OpenClaw loaded; it did not prove that every form of context mixing was solved, or mean topics had different workspaces or agents. The route could still resolve to the same agent.

The upstream PR reported a full pnpm test run, targeted Telegram and history-limit tests, and a manual check in which two DM threads produced distinct sessions and thread IDs. OpenClaw Academy did not reproduce that January build.

February: topics could choose models without changing agents

The next layer was inference routing. PR #22315 merged on 21 February and added channels.modelByChannel. The same day’s v2026.2.21 release shipped per-channel model overrides and surfaced them in /status.

Telegram topic IDs were first-class lookup keys. The following is a historical, non-deployable example of the configuration shape discussed for that release; current syntax may differ:

{
  channels: {
    modelByChannel: {
      telegram: {
        "-1001234567890": "openai/gpt-5.2",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

The merged tests covered a topic-specific match winning over its parent group and a topic falling back to the parent when no exact override existed. The documented precedence put an explicit session /model override above the channel mapping; a heartbeat model also had higher priority.

Operationally, this was useful for cost and capability segmentation, but it still did not create a different identity or filesystem boundary. A “code” topic could select a coding model while remaining a session of the same configured agent.

March: topics became agent and runtime boundaries

The decisive shift shipped in v2026.3.7 on 8 March. Three merged changes turned a Telegram forum into a practical multi-workspace surface.

First, PR #33647, merged on 4 March, added agentId to per-topic Telegram configuration. This historical example illustrates the release-era shape and is not deployable guidance; current syntax may differ:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },
            "3": { agentId: "research" },
            "5": { agentId: "coder" }
          }
        }
      }
    }
  }
}

The release documentation described the resulting key as, for example, agent:research:telegram:group:-1001234567890:topic:3. The important addition was not another suffix: changing the agent changed the workspace, memory and session store. The field was optional, so existing topic routes kept their prior behaviour.

Second, PR #34873 added persistent ACP bindings for Telegram forum topics. Bound conversations resolved to configured ACP sessions, and /new or /reset reset that bound runtime in place. This made a topic capable of retaining a coding-harness relationship across ordinary follow-up messages and restarts.

Third, PR #36683, merged on 6 March, made that path usable from Telegram itself: /acp spawn ... --thread here|auto could bind the current topic, subsequent messages routed there without /acp steer, and the successful binding confirmation was pinned in the topic. It also handled Unicode dash characters produced by Telegram on macOS and added inline approval handling.

The v2026.3.7 documentation is the safer configuration record than the earlier PR draft: the shipped docs used top-level typed bindings[] with a canonical peer ID such as -1001234567890:topic:42. That distinction is a useful historical warning—merged implementation discussions can contain an intermediate config shape; release-tagged documentation shows what operators were actually meant to deploy.

Upstream reported targeted Vitest suites and a build for persistent bindings. PR #36683 reported live checks on macOS with two topics bound to different working directories, plus screenshots; it explicitly did not live-test Discord. PR #33647 reported automated tests and noted that live Telegram testing was still ongoing. We inspected those records and the tagged docs but did not install or exercise the old releases.

Who had to change what

Single-user DM operators gained isolated topic history automatically when the relevant support shipped. Forum operators who only wanted separate conversations did not need to assign multiple agents.

Operators seeking stronger separation had to make deliberate choices:

• Different transcript only: rely on topic-scoped session keys.
• Different model: configure a topic-specific channels.modelByChannel entry, while remembering that /model can supersede it.
• Different workspace, memory and identity: set the topic’s agentId to an existing configured agent.
• Persistent coding harness: create a typed ACP binding or spawn one into the current thread using the release’s documented controls.

Permissions remained another layer. The v2026.3.7 docs said topic entries inherited group settings such as requireMention, allowFrom, skills, system prompt, enabled state and group policy unless overridden. agentId was topic-only and did not inherit. Routing a topic to a powerful coding agent therefore did not remove the need to review who could trigger that topic and whether mention gating was appropriate.

Operators also had to respect Telegram’s General topic special case. OpenClaw omitted message_thread_id for message sends to thread 1 because Telegram rejected it, while retaining the ID for typing indicators. Treating topic 1 like every other Bot API send target caused reliability problems even though OpenClaw still represented it as a topic session.

What this history explains today

Current Telegram documentation still presents the same conceptual stack: group isolation, topic-qualified sessions, per-topic agent routing and persistent ACP topic bindings. Later syntax and safeguards have continued to evolve, so old snippets should not be pasted blindly; the current docs are the configuration authority.

The durable lesson is architectural. Telegram supplies a chat and thread ID. OpenClaw progressively attached four independent decisions to that identity: conversation state, model selection, agent ownership and runtime binding. A topic became a workspace only when operators selected the layers they actually needed.

That is why troubleshooting should start by asking which boundary failed. Wrong history points to session keying. Wrong model points to override precedence. Wrong files or memory points to agent routing. Follow-ups escaping a coding harness point to the persistent binding. “The Telegram topic is broken” is too coarse; by March 2026, a topic was already several systems wearing one label.

Verification note: OpenClaw Academy checked the official releases, merged pull requests, commit metadata, v2026.3.7 tagged documentation and current Telegram documentation on 23 July 2026. Historical test and manual-verification claims above are attributed to upstream; old binaries were not independently reproduced.