From 3256cf4fc7d4d1d18478039a2072413d568f253f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 28 Apr 2026 07:55:36 +0100
Subject: [PATCH] docs: clarify group visible replies

---
 docs/gateway/config-channels.md        |  9 ++++++++-
 docs/gateway/configuration-examples.md | 14 +++++++++-----
 docs/gateway/configuration.md          | 10 ++++++++--
 3 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md
index 4dd4d432b4f..04a1463b0b0 100644
--- a/docs/gateway/config-channels.md
+++ b/docs/gateway/config-channels.md
@@ -753,6 +753,8 @@ See the full channel index: [Channels](/channels).
 
 Group messages default to **require mention** (metadata mention or safe regex patterns). Applies to WhatsApp, Telegram, Discord, Google Chat, and iMessage group chats.
 
+Visible replies are controlled separately. Group/channel rooms default to `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw still processes the turn, but normal final replies stay private and visible room output requires `message(action=send)`. Set `"automatic"` only when you want the legacy behavior where normal replies are posted back to the room.
+
 **Mention types:**
 
 - **Metadata mentions**: Native platform @-mentions. Ignored in WhatsApp self-chat mode.
@@ -762,7 +764,10 @@ Group messages default to **require mention** (metadata mention or safe regex pa
 ```json5
 {
   messages: {
-    groupChat: { historyLimit: 50 },
+    groupChat: {
+      historyLimit: 50,
+      visibleReplies: "message_tool", // default; use "automatic" for legacy final replies
+    },
   },
   agents: {
     list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
@@ -772,6 +777,8 @@ Group messages default to **require mention** (metadata mention or safe regex pa
 
 `messages.groupChat.historyLimit` sets the global default. Channels can override with `channels.<channel>.historyLimit` (or per-account). Set `0` to disable.
 
+`messages.groupChat.visibleReplies` is global for group/channel source turns; channel allowlists and mention gating still decide whether a turn is processed.
+
 #### DM history limits
 
 ```json5
diff --git a/docs/gateway/configuration-examples.md b/docs/gateway/configuration-examples.md
index febc08e3c65..d69a8cb55a5 100644
--- a/docs/gateway/configuration-examples.md
+++ b/docs/gateway/configuration-examples.md
@@ -41,6 +41,11 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
       groups: { "*": { requireMention: true } },
     },
   },
+  messages: {
+    groupChat: {
+      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
+    },
+  },
 }
 ```
 
@@ -99,13 +104,9 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
     responsePrefix: ">",
     ackReaction: "👀",
     ackReactionScope: "group-mentions",
-  },
-
-  // Routing + queue
-  routing: {
     groupChat: {
-      mentionPatterns: ["@openclaw", "openclaw"],
       historyLimit: 50,
+      visibleReplies: "message_tool", // normal final replies stay private in groups/channels
     },
     queue: {
       mode: "collect",
@@ -303,6 +304,9 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
         id: "main",
         default: true,
         // inherits defaults.skills -> github, weather
+        groupChat: {
+          mentionPatterns: ["@openclaw", "openclaw"],
+        },
         thinkingDefault: "high", // per-agent thinking override
         reasoningDefault: "on", // per-agent reasoning visibility
         fastModeDefault: false, // per-agent fast mode
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index f967031a6ed..d5f2ae049e5 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -179,10 +179,15 @@ cannot roll back unrelated user settings.
   </Accordion>
 
   <Accordion title="Set up group chat mention gating">
-    Group messages default to **require mention**. Configure patterns per agent:
+    Group messages default to **require mention**. Configure trigger patterns per agent, and keep visible room replies on the default message-tool path unless you intentionally want legacy automatic final replies:
 
     ```json5
     {
+      messages: {
+        groupChat: {
+          visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
+        },
+      },
       agents: {
         list: [
           {
@@ -203,7 +208,8 @@ cannot roll back unrelated user settings.
 
     - **Metadata mentions**: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
     - **Text patterns**: safe regex patterns in `mentionPatterns`
-    - See [full reference](/gateway/config-channels#group-chat-mention-gating) for per-channel overrides and self-chat mode.
+    - **Visible replies**: `message_tool` keeps normal final replies private; the agent must call `message(action=send)` to post visibly in the group/channel.
+    - See [full reference](/gateway/config-channels#group-chat-mention-gating) for visible reply modes, per-channel overrides, and self-chat mode.
 
   </Accordion>