From 772911b670f80717ba75a15da9623bc2e3a1b942 Mon Sep 17 00:00:00 2001
From: choiking <samsamuels1927@gmail.com>
Date: Sat, 7 Mar 2026 16:14:30 +0800
Subject: [PATCH 1/2] docs: add Telegram multi-agent group setup example

Add a dedicated section to the multi-agent routing docs covering how to
put multiple Telegram bot accounts into a single group chat. Includes:

- Complete config example with two agents/accounts/bindings
- Privacy mode gotchas (must disable + re-add bots)
- groupPolicy/groupAllowFrom clarification (filters sender IDs, not group IDs)
- Top-level vs per-account groupPolicy interaction
---
 docs/concepts/multi-agent.md | 61 ++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index 6f0bd086690..d45143fcf03 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -499,6 +499,67 @@ Notes:
 - For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep
   group allowlists enabled for the channel.
 
+## Multiple Telegram agents in one group
+
+Put two or more Telegram bot accounts into a single group so users can
+@-mention the right agent for the job. Each bot needs its own BotFather token
+and a separate channel account.
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        name: "Assistant",
+        workspace: "~/.openclaw/workspace",
+        identity: { name: "Assistant", emoji: "🤖" },
+      },
+      {
+        id: "marketing",
+        name: "MarketingBot",
+        workspace: "~/.openclaw/workspace-marketing",
+        identity: { name: "MarketingBot", emoji: "📢" },
+      },
+    ],
+  },
+  channels: {
+    telegram: {
+      enabled: true,
+      groupPolicy: "open",
+      accounts: {
+        default: {
+          botToken: "TOKEN_FOR_ASSISTANT",
+          groupPolicy: "open",
+          allowFrom: [YOUR_USER_ID],
+        },
+        marketing: {
+          botToken: "TOKEN_FOR_MARKETING_BOT",
+          groupPolicy: "open",
+          allowFrom: [YOUR_USER_ID],
+        },
+      },
+    },
+  },
+  bindings: [
+    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
+    { agentId: "marketing", match: { channel: "telegram", accountId: "marketing" } },
+  ],
+}
+```
+
+Important setup steps:
+
+1. **Disable Privacy Mode** for each bot in @BotFather (`/setprivacy` → Disable),
+   otherwise bots only see `/commands` and direct replies in groups.
+2. **Re-add bots** to the group after changing privacy mode — Telegram caches
+   the setting per-group and only applies changes on re-join.
+3. `groupPolicy` must be `"open"` (or `"allowlist"` with your user ID in
+   `groupAllowFrom`). Note that `groupAllowFrom` filters by **sender user ID**,
+   not by group chat ID.
+4. Both top-level `channels.telegram.groupPolicy` and per-account `groupPolicy`
+   must allow group messages — the top-level setting is checked first.
+
 ## Per-Agent Sandbox and Tool Configuration
 
 Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:

From c69b8e314f29a6d506b7bff8a4549aca300aedf5 Mon Sep 17 00:00:00 2001
From: choiking <samsamuels1927@gmail.com>
Date: Sat, 7 Mar 2026 16:35:24 +0800
Subject: [PATCH 2/2] fix: address review comments

- Use groupAllowFrom (not allowFrom) for group sender filtering
- Replace YOUR_USER_ID with numeric placeholder (123456789)
- Correct groupPolicy precedence: per-account overrides top-level
---
 docs/concepts/multi-agent.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index d45143fcf03..7ed9a3c9c0e 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -531,12 +531,14 @@ and a separate channel account.
         default: {
           botToken: "TOKEN_FOR_ASSISTANT",
           groupPolicy: "open",
-          allowFrom: [YOUR_USER_ID],
+          allowFrom: [123456789],
+          groupAllowFrom: [123456789],
         },
         marketing: {
           botToken: "TOKEN_FOR_MARKETING_BOT",
           groupPolicy: "open",
-          allowFrom: [YOUR_USER_ID],
+          allowFrom: [123456789],
+          groupAllowFrom: [123456789],
         },
       },
     },
@@ -556,9 +558,11 @@ Important setup steps:
    the setting per-group and only applies changes on re-join.
 3. `groupPolicy` must be `"open"` (or `"allowlist"` with your user ID in
    `groupAllowFrom`). Note that `groupAllowFrom` filters by **sender user ID**,
-   not by group chat ID.
-4. Both top-level `channels.telegram.groupPolicy` and per-account `groupPolicy`
-   must allow group messages — the top-level setting is checked first.
+   not by group chat ID. `allowFrom` is for DM access; `groupAllowFrom` is for
+   group sender filtering (falls back to `allowFrom` when unset).
+4. Per-account `groupPolicy` overrides the top-level `channels.telegram.groupPolicy`.
+   If you only want one account open for groups, set `groupPolicy` on that
+   account and leave the top-level restrictive.
 
 ## Per-Agent Sandbox and Tool Configuration