Telegram Topics Guide

1. Why Topics?

Without topics, every message in a Telegram group goes to the same agent, in the same session. Conversations about client work, infrastructure, and strategy all blend together into one stream.

With Telegram forum topics, you can:

• Give each agent its own topic (SEO agent in one, dev agent in another)
• Give each client its own topic (Client A in one, Client B in another)
• Give each function its own topic (Strategy, Infrastructure, Agent Ops)
• Keep separate sessions per topic (memory and context don't bleed across)

Each topic gets its own session key, its own memory context, and optionally its own agent with its own workspace.

2. Step 1: Enable Topics in Telegram

1. Open your Telegram group
2. Tap the group name to open settings
3. Go to Edit (pencil icon)
4. Scroll down and enable Topics
5. The group becomes a forum supergroup

After enabling, you'll see a "General" topic and can create new topics by tapping the topic list icon.

3. Step 2: Find Your Group and Topic IDs

OpenClaw needs numeric IDs, not names. Here's how to get them:

Group ID

# Use the directory command
openclaw directory resolve --channel telegram --name "Your Group Name"

Group IDs are negative numbers that start with -100, like -1001234567890.

Topic IDs

Topic IDs are the message_thread_id from Telegram. You can find them by:

• From the URL: Open the topic in Telegram Web. The URL contains the thread ID: https://web.telegram.org/.../thread/5 — the topic ID is 5
• From bot messages: When your bot receives a message in a topic, the gateway log shows the message_thread_id
• General topic is always 1

openclaw logs | grep "message_thread_id"

4. Step 3: Configure OpenClaw

Add your group and topics to openclaw.json:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "allowFrom": ["chat_id:123456789"],
          "requireMention": true,
          "topics": {
            "1": {},
            "5": {},
            "6": {},
            "7": {}
          }
        }
      }
    }
  }
}

This registers topics 1 (General), 5, 6, and 7 in the group. Each gets its own session automatically.

5. Step 4: Route Different Agents to Different Topics

This is the power feature. Each topic can route to a different agent, with its own workspace, memory, model, and personality:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "allowFrom": ["chat_id:123456789"],
          "topics": {
            "1": { "agentId": "main" },
            "5": { "agentId": "seo-agent" },
            "6": { "agentId": "dev-agent" },
            "7": { "agentId": "content-agent" }
          }
        }
      }
    }
  }
}

Now:

• General (topic 1) → main agent (orchestrator)
• SEO (topic 5) → seo-agent (search analysis)
• Dev (topic 6) → dev-agent (development)
• Content (topic 7) → content-agent (content writing)

6. Per-Topic Settings

Topics inherit group settings by default, but you can override per topic:

Example: Bot responds to every message in the dev topic (no @mention needed), but requires mention everywhere else:

{
  "topics": {
    "1": { "agentId": "main", "requireMention": true },
    "6": { "agentId": "dev-agent", "requireMention": false }
  }
}

7. How Session Keys Work

OpenClaw generates a unique session key for each topic. The format:

agent:<agentId>:telegram:group:<chatId>:topic:<threadId>

Examples:

• agent:main:telegram:group:-1001234567890:topic:1 — General topic, main agent
• agent:seo-agent:telegram:group:-1001234567890:topic:5 — SEO topic, seo-agent
• agent:dev-agent:telegram:group:-1001234567890:topic:6 — Dev topic, dev-agent

This means:

• Memory and context are isolated per topic
• Cron jobs can target a specific topic using the session key
• Session history is separate per topic

8. Advanced: ACP Sessions in Topics

You can bind a persistent ACP (Agent Control Protocol) session to a forum topic. This lets you have a persistent Codex or Claude Code session running inside a specific topic:

{
  "agents": {
    "list": [
      {
        "id": "codex-topic",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "codex",
            "backend": "acpx",
            "mode": "persistent",
            "cwd": "/path/to/project"
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex-topic",
      "match": {
        "channel": "telegram",
        "accountId": "default",
        "peer": {
          "kind": "group",
          "id": "-1001234567890:topic:42"
        }
      }
    }
  ]
}

Messages in topic 42 now route directly to a persistent Codex session.

You can also spawn ACP sessions on-the-fly in any topic:

/acp spawn codex --thread here

This requires channels.telegram.threadBindings.spawnAcpSessions: true in config.

9. Gotchas

openclaw gateway restart

openclaw message channel topic-create --chat-id "-1001234567890" --name "New Topic"

10. Real-World Example

Here's a practical setup for a business with multiple specialist agents:

{
  "channels": {
    "telegram": {
      "groups": {
        "-1001234567890": {
          "allowFrom": ["chat_id:123456789"],
          "requireMention": true,
          "topics": {
            "1": {
              "agentId": "main",
              "requireMention": false
            },
            "5": {
              "agentId": "seo-agent",
              "systemPrompt": "You are in the Client A topic. Focus on this client."
            },
            "6": {
              "agentId": "main"
            },
            "7": {
              "agentId": "main"
            },
            "8": {
              "agentId": "main"
            }
          }
        }
      }
    }
  }
}

This gives you:

Each topic has its own session, so conversations about Client A don't pollute the Strategy topic's context, and infrastructure debugging stays separate from client work.

True Webmaster — March 24, 2026
Verified against OpenClaw 2026.3.22