docs(gateway): troubleshoot group @mention silent suppression (#77052)

yetval · clawsweeper[bot] · Takhoffman · web-flow · commit 324a95db8b21 · 2026-05-18T17:03:53.000Z
Summary: - Adds a symptom-keyed troubleshooting block to `docs/gateway/config-channels.md` for group/channel @mentions that log `queuedFinal=false, replies=0` and explains the `visibleReplies` remedies. - Reproducibility: yes. for the docs gap and source behavior: current main lacks the exact symptom-keyed troubleshooting entry, and the resolver/tests show when message-tool mode suppresses automatic final delivery. Automerge notes: - PR branch already contained follow-up commit before automerge: docs(gateway): make group reply fix restart conditional - PR branch already contained follow-up commit before automerge: docs(gateway): qualify direct-chat reply default in troubleshooting - PR branch already contained follow-up commit before automerge: docs(gateway): align group reply troubleshooting with current automat… - PR branch already contained follow-up commit before automerge: docs(gateway): scope group reply suppression cause to group config Validation: - ClawSweeper review passed for head e60ae89. - Required merge gates passed before the squash merge. Prepared head SHA: e60ae89 Review: #77052 (comment) Co-authored-by: yetval <yetvald@gmail.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: takhoffman Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>
diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md
@@ -799,7 +799,13 @@ for every group/channel request.
 
 If the message tool is unavailable under the active tool policy, OpenClaw falls back to automatic visible replies instead of silently suppressing the response. `openclaw doctor` warns about this mismatch.
 
-The gateway hot-reloads `messages` config after the file is saved. Restart only when file watching or config reload is disabled in the deployment.
+**Troubleshooting: group @mention triggers typing then silence (no error)**
+
+Symptom: a group/channel @mention shows the typing indicator and the gateway log reports `dispatch complete (queuedFinal=false, replies=0)`, but no message lands in the room. DMs to the same agent reply normally.
+
+Cause: the group/channel visible-reply mode resolves to `"message_tool"`, so OpenClaw runs the turn but suppresses the final assistant text unless the agent calls `message(action=send)`. There is no error because suppression is the configured behavior. Normal group and channel turns default to `"automatic"`, so this symptom only appears when `messages.groupChat.visibleReplies` (or global `messages.visibleReplies`) is explicitly set to `"message_tool"`. Harness `defaultVisibleReplies` does not apply here — the group/channel resolver ignores it; it only affects direct/source chats (the Codex harness suppresses direct-chat finals that way).
+
+Fix: either pick a stronger tool-calling model, remove the explicit `"message_tool"` override to fall back to the `"automatic"` default, or set `messages.groupChat.visibleReplies: "automatic"` to force visible replies for every group/channel request. The gateway hot-reloads `messages` config after the file is saved; only restart the gateway when file watching or config reload is disabled in the deployment.
 
 **Mention types:**
 
