docs(gateway): troubleshoot group @mention silent suppression by yetval · Pull Request #77052 · openclaw/openclaw

yetval · 2026-05-04T02:44:41Z

Summary

Adds a troubleshooting block to docs/gateway/config-channels.md for the symptom in #76726: group/channel @mention triggers typing then silence with dispatch complete (queuedFinal=false, replies=0) and no error.

The default messages.groupChat.visibleReplies: "message_tool" (src/auto-reply/reply/source-reply-delivery-mode.ts:28) suppresses final assistant text unless the model calls message(action=send). DMs use a different default, which matches the reported symmetry (DMs reply, groups go silent).

The option itself is already documented at docs/gateway/config-channels.md:778 — what was missing was a symptom-keyed entry someone hits when their bot is silent.

Verification

Operator in [Bug]: Feishu group @mention triggers typing but no reply (replies=0) #76726 (aaronpancn) confirmed messages.groupChat.visibleReplies: automatic restores replies — same fix this troubleshooting entry now points to.
Docs-only change. Per AGENTS.md, docs-only edits are not changed-gate work; ran git diff --check and verified Mintlify root-relative link rules (no new links added).

Closes part of #76726 (config/docs gap; not a Feishu send-path bug).

Leaving the deeper question (warn-once when group default suppresses, or flip default) for maintainer call.

Real behavior proof

Behavior or issue addressed: Reporters hitting the group/channel @mention symptom from #76726 (typing indicator runs, gateway log shows dispatch complete (queuedFinal=false, replies=0), no message lands in the room, DMs reply normally) currently find no symptom-keyed entry in docs/gateway/config-channels.md; the underlying messages.groupChat.visibleReplies: "message_tool" default and the automatic workaround are documented elsewhere on the page but not surfaced from the failing symptom they actually search for.

Real environment tested: macOS 25.3.0, real OpenClaw checkout at /private/tmp/77052-rebase (clone of yetval/openclaw:docs/group-visible-reply-troubleshooting rebased onto upstream openclaw/main), node 22, no live channel needed since the change is docs-only and only adds prose surfaced from the same page.

Exact steps or command run after this patch:

node -e "const fs=require('fs');const s=fs.readFileSync('docs/gateway/config-channels.md','utf8');const i=s.indexOf('**Troubleshooting: group @mention triggers typing then silence (no error)**');const end=s.indexOf('\n###',i);process.stdout.write(s.slice(i, end>0?end:i+2000))"

Evidence after fix: copied live terminal output from node against the patched docs/gateway/config-channels.md (no docs build needed; the file is the published source for https://docs.openclaw.ai/gateway/config-channels) showing the new symptom-keyed troubleshooting block at the expected location, with the conditional restart guidance retained from the second commit.

**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 `messages.groupChat.visibleReplies` default is `"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. DMs use a different default, which is why direct chats still reply.

Fix: either pick a stronger tool-calling model, or set `messages.groupChat.visibleReplies: "automatic"` to restore legacy visible replies. 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:**

- **Metadata mentions**: Native platform @-mentions. Ignored in WhatsApp self-chat mode.
- **Text patterns**: Safe regex patterns in `agents.list[].groupChat.mentionPatterns`. Invalid patterns and unsafe nested repetition are ignored.
- Mention gating is enforced only when detection is possible (native mentions or at least one pattern).

```json5
{
  messages: {
    visibleReplies: "automatic", // global default for direct/source chats; Codex harness defaults unset direct chats to message_tool
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // default; use "automatic" for legacy final replies
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit sets the global default. Channels can override with channels.<channel>.historyLimit (or per-account). Set 0 to disable.

messages.visibleReplies is the global source-turn default; messages.groupChat.visibleReplies overrides it for group/channel source turns. When messages.visibleReplies is unset, a harness can provide its own direct/source default; the Codex harness defaults to message_tool. Channel allowlists and mention gating still decide whether a turn is processed.


Observed result after fix: the rendered docs source now carries a Symptom / Cause / Fix block keyed off the failing log line (`queuedFinal=false, replies=0`), so a contributor searching the troubleshooting docs for that exact symptom is routed to the `messages.groupChat.visibleReplies` default explanation and the `automatic` workaround without restarting the gateway unless file watching or config reload is disabled. The rest of the page (mention types, JSON example, channel allowlist semantics) round-trips unchanged.

What was not tested: no live Feishu / WhatsApp / Slack gateway reproduction of the underlying suppression behavior was run as part of this PR — the underlying behavior is already covered by `src/auto-reply/reply/source-reply-delivery-mode.test.ts` and confirmed by the reporter on the linked issue, and this PR only adds the symptom-keyed entry that was missing from the troubleshooting docs.

yetval · 2026-05-04T02:46:03Z

Opened #77052 — docs-only patch adding a troubleshooting block keyed to this exact symptom (typing fires, queuedFinal=false, replies=0, no error in groups, DMs fine) so the next operator finds the visibleReplies: automatic fix without having to file an issue.

clawsweeper · 2026-05-04T02:49:19Z

Codex review: passed.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

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.

PR rating
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Summary: Good normal docs-only PR with source-aligned wording and no blocking findings.

Rank-up moves:

none

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

PR egg
✨ Hatched: 🥚 common Pearl Crabkin

        /\     /\            
      _/  \___/  \_          
     /  ( o   o )  \         
    |      \_/      |        
    |   /\  ===  /\ |        
     \_/  \_____/  \_/       
        _/|_| |_|\_          
       /__| | | |__\         
          ' ' ' '            
         /_/     \_\         
       .-----------.         
      '-------------'

Rarity: 🥚 common.
Trait: guards the happy path.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Pearl Crabkin in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
How to hatch it: reach status: 👀 ready for maintainer look or status: 🚀 automerge armed; that usually means sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

Real behavior proof
Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Next step before merge
No repair lane is needed; this docs-only PR has no blocking findings and can proceed through existing automerge and required-check gates.

Security
Cleared: The diff is docs-only and adds no executable code, dependency, workflow, permission, secret, or supply-chain surface.

Review details

Best possible solution:

Merge the focused troubleshooting docs after normal automerge checks, while keeping any runtime default or warn-once change as a separate maintainer decision.

Do we have a high-confidence way to reproduce the issue?

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.

Is this the best way to solve the issue?

Yes. Adding the block to the existing gateway channel config page is the narrow maintainable fix because it points operators to existing configuration instead of changing runtime defaults.

Label justifications:

P3: This is a small docs-only troubleshooting improvement with no runtime, config migration, or upgrade behavior change.

What I checked:

PR diff scope: Provided GitHub PR context shows a single docs file changed with 7 additions and 1 deletion, adding the troubleshooting block under group chat mention gating. Public docs: docs/gateway/config-channels.md. (docs/gateway/config-channels.md:799, e60ae89b20ed)
Current docs gap: Current main documents group chat mention gating, messages.groupChat.visibleReplies, and hot reload behavior, but it does not include the symptom-keyed queuedFinal=false, replies=0 troubleshooting block this PR adds. Public docs: docs/gateway/config-channels.md. (docs/gateway/config-channels.md:786, 1fbb4e4e6a9e)
Resolver behavior: For group/channel turns, the resolver reads messages.groupChat.visibleReplies and then global messages.visibleReplies; defaultVisibleReplies is only used outside group/channel turns, matching the PR's corrected wording. (src/auto-reply/reply/source-reply-delivery-mode.ts:65, 1fbb4e4e6a9e)
Behavior coverage: Tests cover automatic defaults, global message-tool mode, group/channel overrides, and Codex direct-chat message-tool defaults, so the doc text is source-aligned. (src/auto-reply/reply/source-reply-delivery-mode.test.ts:33, 1fbb4e4e6a9e)
Dispatch suppression coverage: Dispatch tests show group/channel message_tool mode keeps final replies private without a message send and Codex direct-chat defaults can do the same when config is unset. (src/auto-reply/reply/dispatch-from-config.test.ts:5155, 1fbb4e4e6a9e)
Scoped docs rules: The docs AGENTS guide confirms Mintlify docs are hosted at docs.openclaw.ai and internal docs links must be root-relative; this PR adds no new links and stays within the existing page. Public docs: docs/AGENTS.md. (docs/AGENTS.md:1, 1fbb4e4e6a9e)

Likely related people:

steipete: Git blame in this checkout attributes the current group mention docs, resolver, and related tests to Peter Steinberger's current-main history; the trail is shallow/grafted but points to this area owner signal. (role: recent area contributor; confidence: medium; commits: d29f77bece1a; files: docs/gateway/config-channels.md, src/auto-reply/reply/source-reply-delivery-mode.ts, src/auto-reply/reply/source-reply-delivery-mode.test.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 1fbb4e4e6a9e.

yetval · 2026-05-17T20:18:06Z

@clawsweeper re-review

Addressed the P3 wording at docs/gateway/config-channels.md:806: the troubleshooting Cause line now qualifies direct-chat behavior — direct chats only reply visibly when their resolved visible-reply mode is "automatic", and harnesses that set defaultVisibleReplies: "message_tool" (e.g. Codex) suppress direct-chat finals the same way as the group default. New head: 5a4060f.

clawsweeper · 2026-05-17T20:19:41Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26001647374
Updated: 2026-05-17T20:25:35.952Z

Direct chats only reply visibly when their resolved visible-reply mode is "automatic". Harnesses that set defaultVisibleReplies to "message_tool" (e.g. Codex) suppress direct-chat finals the same way as the group default, so the prior wording was misleading.

yetval · 2026-05-18T14:59:27Z

Rebased onto current openclaw/main (ae29d14abf6f); 3-commit docs-only branch replayed cleanly with no conflicts. New head: d116e41ffe. No functional change since the last ClawSweeper pass — only the base advanced.

@clawsweeper re-review

clawsweeper · 2026-05-18T15:01:25Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26041708691
Updated: 2026-05-18T15:09:14.360Z

…ic default

Takhoffman · 2026-05-18T16:55:57Z

@clawsweeper automerge

clawsweeper · 2026-05-18T16:58:10Z

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=e60ae89b20edbc52ca35d583202f4a2da33b3984)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-05-18T17:03:54Z
Merge commit: 324a95db8b21

What merged:

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

The automerge loop is complete.

Automerge progress:

2026-05-18 16:58:09 UTC review queued e60ae89b20ed (queued)

2026-05-18 17:03:41 UTC review passed e60ae89b20ed (structured ClawSweeper verdict: pass (sha=e60ae89b20edbc52ca35d583202f4a2da33b3...)

2026-05-18 17:03:56 UTC merged e60ae89b20ed (merged by ClawSweeper automerge)

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 e60ae89b20edbc52ca35d583202f4a2da33b3984. - Required merge gates passed before the squash merge. Prepared head SHA: e60ae89b20edbc52ca35d583202f4a2da33b3984 Review: openclaw/openclaw#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>

…aw#77052) 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: openclaw#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>

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime size: XS labels May 4, 2026

yetval mentioned this pull request May 4, 2026

[Bug]: Feishu group @mention triggers typing but no reply (replies=0) #76726

Closed

openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 14, 2026

yetval force-pushed the docs/group-visible-reply-troubleshooting branch from 1cecce0 to b9a2ef9 Compare May 16, 2026 22:23

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 16, 2026

clawsweeper Bot added the P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. label May 16, 2026

yetval force-pushed the docs/group-visible-reply-troubleshooting branch from b9a2ef9 to be61e93 Compare May 17, 2026 19:28

clawsweeper Bot added the impact:message-loss Channel message delivery can be lost, duplicated, or misrouted. label May 17, 2026

yetval added 3 commits May 18, 2026 10:57

docs(gateway): troubleshoot group @mention silent suppression

b45e051

docs(gateway): make group reply fix restart conditional

e68b793

yetval force-pushed the docs/group-visible-reply-troubleshooting branch from 5a4060f to d116e41 Compare May 18, 2026 14:57

yetval added 2 commits May 18, 2026 11:16

docs(gateway): align group reply troubleshooting with current automat…

b9b94bc

…ic default

docs(gateway): scope group reply suppression cause to group config

e60ae89

clawsweeper Bot added the clawsweeper:automerge Maintainer opted this PR into bounded ClawSweeper-reviewed automerge label May 18, 2026

clawsweeper Bot added status: 🚀 automerge armed This PR is in ClawSweeper's automerge lane. and removed status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 18, 2026

clawsweeper Bot merged commit 324a95d into openclaw:main May 18, 2026
106 of 111 checks passed

yetval deleted the docs/group-visible-reply-troubleshooting branch May 18, 2026 17:06

github-actions Bot mentioned this pull request May 18, 2026

📡 Upstream Digest — 2026-05-18 17:53 UTC curtismercier/openclaw-mods#891

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

docs(gateway): troubleshoot group @mention silent suppression#77052
clawsweeper[bot] merged 5 commits into
openclaw:mainfrom
yetval:docs/group-visible-reply-troubleshooting

yetval commented May 4, 2026 •

edited

Loading

Uh oh!

yetval commented May 4, 2026

Uh oh!

clawsweeper Bot commented May 4, 2026 •

edited

Loading

Uh oh!

yetval commented May 17, 2026

Uh oh!

clawsweeper Bot commented May 17, 2026 •

edited

Loading

Uh oh!

yetval commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 •

edited

Loading

Uh oh!

Takhoffman commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

yetval commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Real behavior proof

Uh oh!

yetval commented May 4, 2026

Uh oh!

clawsweeper Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yetval commented May 17, 2026

Uh oh!

clawsweeper Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yetval commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Takhoffman commented May 18, 2026

Uh oh!

clawsweeper Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

yetval commented May 4, 2026 •

edited

Loading

clawsweeper Bot commented May 4, 2026 •

edited

Loading

clawsweeper Bot commented May 17, 2026 •

edited

Loading

clawsweeper Bot commented May 18, 2026 •

edited

Loading

clawsweeper Bot commented May 18, 2026 •

edited

Loading