fix(auto-reply): fallback group finals when message tool is missed

steipete · steipete · commit a6cc29008473 · 2026-05-16T14:47:30.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Group/channel replies: fall back to posting substantive final text for normal requests when a message-tool-preferred turn misses the message tool, while keeping ambient room events strict and quiet.
 - Gateway/WebChat: route image attachments through a configured vision-capable `imageModel` plan before inlining images, and carry that image-model fallback chain through runtime retries. (#82524) Thanks @frankekn.
 - WebChat: show progress while manual `/compact` is running by streaming a session operation event to subscribed Control UI clients. Fixes #82407. Thanks @Conan-Scott.
 - Codex app-server: limit canonical OpenAI Codex app-server attribution rewrites to local transcript and trajectory records, leaving runtime/tool routing on the selected OpenAI model metadata so OpenAI API-key backup profiles keep their billing path.
diff --git a/docs/channels/discord.md b/docs/channels/discord.md
@@ -250,9 +250,9 @@ Once DMs are working, you can set up your Discord server as a full workspace whe
   <Step title="Allow responses without @mention">
     By default, your agent only responds in guild channels when @mentioned. For a private server, you probably want it to respond to every message.
 
-    In guild channels, normal assistant final replies stay private by default. Visible Discord output must be sent explicitly with the `message` tool, so the agent can lurk by default and only post when it decides a channel reply is useful.
+    In guild channels, visible Discord output should use the `message` tool by default, so the agent can lurk and only post when it decides a channel reply is useful. For normal requests, OpenClaw falls back to the assistant's final text when the model misses the tool; ambient room events stay quiet unless the tool sends.
 
-    This means the selected model must reliably call tools. If Discord shows typing and the logs show token usage but no posted message, check the session log for assistant text with `didSendViaMessagingTool: false`. That means the model produced a private final answer instead of calling `message(action=send)`. Switch to a stronger tool-calling model, or use the config below to restore legacy automatic final replies.
+    This means the selected model should reliably call tools. If Discord shows typing and the logs show token usage but no posted message, check whether the turn was configured as an ambient room event or use the config below to restore legacy automatic final replies.
 
     <Tabs>
       <Tab title="Ask your agent">
diff --git a/docs/channels/groups.md b/docs/channels/groups.md
@@ -16,7 +16,7 @@ Default behavior:
 
 - Groups are restricted (`groupPolicy: "allowlist"`).
 - Replies require a mention unless you explicitly disable mention gating.
-- Normal final replies in groups/channels are private by default. Visible room output uses the `message` tool.
+- Visible replies in groups/channels prefer the `message` tool, with final-text fallback for normal requests.
 
 Translation: allowlisted senders can trigger OpenClaw by mentioning it.
 
@@ -43,15 +43,15 @@ always-on group chatter -> user request, or room event when configured
 
 For group/channel rooms, OpenClaw defaults to `messages.groupChat.visibleReplies: "message_tool"`.
 `openclaw doctor --fix` writes this default into configured-channel configs that omit it.
-That means the agent still processes the turn and can update memory/session state, but its normal final answer is not automatically posted back into the room. To speak visibly, the agent uses `message(action=send)`.
+That means the agent still processes the turn and can update memory/session state, and it should speak visibly with `message(action=send)` when it has a room reply. If the model misses that tool and returns substantive final text on a normal group/channel request, OpenClaw now falls back to posting that final text instead of leaving the room silent.
 
 This default depends on a model/runtime that reliably calls tools. If logs show
 assistant text but `didSendViaMessagingTool: false`, the model answered
-privately instead of calling the message tool. That is not a
-Discord/Slack/Telegram send failure. Use a tool-call-reliable model for
-group/channel sessions, or set
-`messages.groupChat.visibleReplies: "automatic"` to restore legacy visible
-final replies for group requests.
+through the fallback instead of calling the message tool. That is not a
+Discord/Slack/Telegram send failure, but a tool-discipline signal. Use a
+tool-call-reliable model for group/channel sessions, or set
+`messages.groupChat.visibleReplies: "automatic"` when you want all visible group
+replies to use the legacy final-reply path.
 
 If the message tool is unavailable under the active tool policy, OpenClaw falls
 back to automatic visible replies instead of silently suppressing the response.
@@ -61,7 +61,7 @@ For direct chats and any other source turn, use `messages.visibleReplies: "messa
 
 This replaces the old pattern of forcing the model to answer `NO_REPLY` for most lurk-mode turns. In tool-only mode, doing nothing visible simply means not calling the message tool.
 
-Typing indicators are still sent for direct group requests. Ambient always-on room events, when enabled, stay quiet unless the agent calls the message tool.
+Typing indicators are still sent for direct group requests. Ambient always-on room events, when enabled, stay strict and quiet unless the agent calls the message tool.
 
 To submit always-on ambient group chatter as quiet room context instead of legacy user requests:
 
diff --git a/docs/channels/slack.md b/docs/channels/slack.md
@@ -1297,7 +1297,7 @@ Primary reference: [Configuration reference - Slack](/gateway/config-channels#sl
     - channel allowlist (`channels.slack.channels`) — **keys must be channel IDs** (`C12345678`), not names (`#channel-name`). Name-based keys silently fail under `groupPolicy: "allowlist"` because channel routing is ID-first by default. To find an ID: right-click the channel in Slack → **Copy link** — the `C...` value at the end of the URL is the channel ID.
     - `requireMention`
     - per-channel `users` allowlist
-    - `messages.groupChat.visibleReplies`: if it is `"message_tool"` and logs show assistant text with no `message(action=send)` call, the turn was processed but the final answer was kept private. Set it to `"automatic"` if you want normal assistant final replies posted back to Slack channels.
+    - `messages.groupChat.visibleReplies`: if it is `"message_tool"` and logs show assistant text with no `message(action=send)` call, the model missed the preferred message-tool path. Current builds fall back to final text for normal requests; ambient room events still stay quiet. Set it to `"automatic"` if you want every normal assistant final reply posted through the legacy path.
 
 ```json5
 {
diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md
@@ -80,12 +80,12 @@ Full troubleshooting: [Telegram troubleshooting](/channels/telegram#troubleshoot
 
 ### Discord failure signatures
 
-| Symptom                                   | Fastest check                                                          | Fix                                                                                                                                                                     |
-| ----------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Bot online but no guild replies           | `openclaw channels status --probe`                                     | Allow guild/channel and verify message content intent.                                                                                                                  |
-| Group messages ignored                    | Check logs for mention gating drops                                    | Mention bot or set guild/channel `requireMention: false`.                                                                                                               |
-| Typing/token usage but no Discord message | Session log shows assistant text with `didSendViaMessagingTool: false` | The model answered privately instead of calling the message tool. Use a tool-call-reliable model, or set `messages.groupChat.visibleReplies: "automatic"` to auto-post. |
-| DM replies missing                        | `openclaw pairing list discord`                                        | Approve DM pairing or adjust DM policy.                                                                                                                                 |
+| Symptom                                   | Fastest check                                                                             | Fix                                                                                                                                                                                          |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bot online but no guild replies           | `openclaw channels status --probe`                                                        | Allow guild/channel and verify message content intent.                                                                                                                                       |
+| Group messages ignored                    | Check logs for mention gating drops                                                       | Mention bot or set guild/channel `requireMention: false`.                                                                                                                                    |
+| Typing/token usage but no Discord message | Check whether this was an ambient room event or an older build before final-text fallback | Upgrade, verify `messages.groupChat.ambientTurns` is not routing the turn as quiet room context, or set `messages.groupChat.visibleReplies: "automatic"` to use the legacy final-reply path. |
+| DM replies missing                        | `openclaw pairing list discord`                                                           | Approve DM pairing or adjust DM policy.                                                                                                                                                      |
 
 Full troubleshooting: [Discord troubleshooting](/channels/discord#troubleshooting)
 
diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md
@@ -786,14 +786,14 @@ 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. To apply the same tool-only visible-reply behavior to direct chats too, set `messages.visibleReplies: "message_tool"`; the Codex harness also uses that tool-only behavior as its unset direct-chat default.
+Visible replies are controlled separately. Group/channel rooms default to `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw still processes the turn and asks the agent to use `message(action=send)` for visible room output. For normal group/channel requests, substantive final text falls back to the source room when the model misses the message tool; ambient room events stay strict and quiet unless the tool sends. Set `"automatic"` when you want all visible group replies to use the legacy final-reply path. To apply the same tool-only visible-reply behavior to direct chats too, set `messages.visibleReplies: "message_tool"`; the Codex harness also uses that tool-only behavior as its unset direct-chat default.
 
 Tool-only visible replies require a model/runtime that reliably calls tools. If
 the session log shows assistant text with `didSendViaMessagingTool: false`, the
-model produced a private final answer instead of calling the message tool.
-Switch to a stronger tool-calling model for that channel, or set
-`messages.groupChat.visibleReplies: "automatic"` to restore legacy visible final
-replies.
+model produced final text fallback instead of calling the message tool. Switch
+to a stronger tool-calling model for that channel, or set
+`messages.groupChat.visibleReplies: "automatic"` to use legacy visible final
+replies 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.
 
diff --git a/docs/gateway/configuration-examples.md b/docs/gateway/configuration-examples.md
@@ -51,7 +51,7 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
   messages: {
     visibleReplies: "automatic",
     groupChat: {
-      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
+      visibleReplies: "message_tool", // default; falls back to final text for normal requests
     },
   },
 }
@@ -110,7 +110,7 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
     ackReactionScope: "group-mentions",
     groupChat: {
       historyLimit: 50,
-      visibleReplies: "message_tool", // normal final replies stay private in groups/channels
+      visibleReplies: "message_tool", // prefer message tool; final text falls back for normal requests
     },
     queue: {
       mode: "followup",
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
@@ -175,14 +175,14 @@ candidate contains redacted secret placeholders such as `***`.
   </Accordion>
 
   <Accordion title="Set up group chat mention gating">
-    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:
+    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 every normal group reply to use the legacy automatic final-reply path:
 
     ```json5
     {
       messages: {
         visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
         groupChat: {
-          visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
+          visibleReplies: "message_tool", // default; falls back to final text for normal requests
         },
       },
       agents: {
diff --git a/src/agents/system-prompt.test.ts b/src/agents/system-prompt.test.ts
@@ -907,12 +907,11 @@ describe("buildAgentSystemPrompt", () => {
       },
     });
 
-    expect(prompt).toContain("private by default for this source channel");
-    expect(prompt).toContain("use `message(action=send)` for visible channel output");
+    expect(prompt).toContain("use `message(action=send)` for visible source-channel output");
     expect(prompt).toContain("Attach media with message-tool attachment fields");
     expect(prompt).not.toContain("Attach media: `MEDIA:<path-or-url>`");
     expect(prompt).toContain("The target defaults to the current source channel");
-    expect(prompt).toContain("final answers are private in this mode");
+    expect(prompt).toContain("do not repeat that visible content in your final answer");
     expect(prompt).not.toContain("## Silent Replies");
     expect(prompt).not.toContain(SILENT_REPLY_TOKEN);
     expect(prompt).not.toContain(
diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts
@@ -508,7 +508,7 @@ function buildMessagingSection(params: {
   return [
     "## Messaging",
     messageToolOnly
-      ? "- Reply in current session → private by default for this source channel; use `message(action=send)` for visible channel output."
+      ? "- Reply in current session → use `message(action=send)` for visible source-channel output; normal final text may stay private or route only as a fallback."
       : "- Reply in current session → automatically routes to the source channel (Signal, Telegram, etc.)",
     "- Cross-session messaging → use sessions_send(sessionKey, message)",
     subagentOrchestrationGuidance,
@@ -526,7 +526,7 @@ function buildMessagingSection(params: {
             ? `- No current/default source channel: include \`channel\` for proactive sends; valid ids: ${params.messageChannelOptions}.`
             : "- Pass `channel` only when sending outside the current/default source channel.",
           messageToolOnly
-            ? "- If you use `message` (`action=send`) to deliver visible output, do not repeat that visible content in your final answer; final answers are private in this mode."
+            ? "- If you use `message` (`action=send`) to deliver visible output, do not repeat that visible content in your final answer."
             : suppressSilentTokenGuidance
               ? "- Do not use `message(action=send)` to deliver the current source-channel reply; reply normally so OpenClaw can route it once."
               : `- If you use \`message\` (\`action=send\`) to deliver your user-visible reply, respond with ONLY: ${SILENT_REPLY_TOKEN} (avoid duplicate replies).`,
diff --git a/src/agents/tools/message-tool.test.ts b/src/agents/tools/message-tool.test.ts
@@ -383,10 +383,10 @@ describe("message tool secret scoping", () => {
     const defaultTool = createMessageTool();
 
     expect(scopedTool.description).toContain(
-      'visible replies to the current source conversation must use action="send"',
+      'use action="send" with message for visible replies to the current source conversation',
     );
     expect(scopedTool.description).toContain("target defaults to the current source conversation");
-    expect(scopedTool.description).toContain("Normal final answers are private");
+    expect(scopedTool.description).toContain("Normal final answers may stay private");
     expect(explicitTargetTool.description).toContain("Include target when sending");
     expect(explicitTargetTool.description).not.toContain(
       "target defaults to the current source conversation",
@@ -403,7 +403,7 @@ describe("message tool secret scoping", () => {
     }).find((candidate) => candidate.name === "message");
 
     expect(tool?.description).toContain(
-      'visible replies to the current source conversation must use action="send"',
+      'use action="send" with message for visible replies to the current source conversation',
     );
   });
 
diff --git a/src/agents/tools/message-tool.ts b/src/agents/tools/message-tool.ts
@@ -772,7 +772,7 @@ function appendMessageToolVisibleReplyHint(
   const targetGuidance = requireExplicitTarget
     ? "Include target when sending."
     : "The target defaults to the current source conversation, so omit target unless sending elsewhere.";
-  return `${description} For this turn, visible replies to the current source conversation must use action="send" with message. ${targetGuidance} Normal final answers are private and are not posted.`;
+  return `${description} For this turn, use action="send" with message for visible replies to the current source conversation. ${targetGuidance} Normal final answers may stay private or route only as a fallback.`;
 }
 
 function appendMessageToolReadHint(
diff --git a/src/auto-reply/get-reply-options.types.ts b/src/auto-reply/get-reply-options.types.ts
@@ -177,8 +177,10 @@ export type GetReplyOptions = {
   onModelSelected?: (ctx: ModelSelectedContext) => void;
   /**
    * Controls whether normal assistant replies are automatically delivered to
-   * the source conversation. `message_tool_only` keeps final/block/preview
-   * output private; visible channel output must come from the message tool.
+   * the source conversation. `message_tool_only` prefers message-tool visible
+   * delivery and keeps block/preview output private; non-ambient group/channel
+   * final text may fall back to normal source delivery when no message-tool
+   * reply was produced.
    */
   sourceReplyDeliveryMode?: SourceReplyDeliveryMode;
   /** Starts delivery tracking when this turn later drains as a queued followup. */
diff --git a/src/auto-reply/reply/dispatch-from-config.test.ts b/src/auto-reply/reply/dispatch-from-config.test.ts
diff --git a/src/auto-reply/reply/dispatch-from-config.ts b/src/auto-reply/reply/dispatch-from-config.ts
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
diff --git a/src/config/types.messages.ts b/src/config/types.messages.ts

Original file line number	Diff line number	Diff line change
`@@ -1297,7 +1297,7 @@ Primary reference: [Configuration reference - Slack](/gateway/config-channels#sl`
`1297`	`1297`	- channel allowlist (`channels.slack.channels`) — keys must be channel IDs (`C12345678`), not names (`#channel-name`). Name-based keys silently fail under `groupPolicy: "allowlist"` because channel routing is ID-first by default. To find an ID: right-click the channel in Slack → Copy link — the `C...` value at the end of the URL is the channel ID.
`1298`	`1298`	- `requireMention`
`1299`	`1299`	- per-channel `users` allowlist
`1300`		- - `messages.groupChat.visibleReplies`: if it is `"message_tool"` and logs show assistant text with no `message(action=send)` call, the turn was processed but the final answer was kept private. Set it to `"automatic"` if you want normal assistant final replies posted back to Slack channels.
	`1300`	+ - `messages.groupChat.visibleReplies`: if it is `"message_tool"` and logs show assistant text with no `message(action=send)` call, the model missed the preferred message-tool path. Current builds fall back to final text for normal requests; ambient room events still stay quiet. Set it to `"automatic"` if you want every normal assistant final reply posted through the legacy path.
`1301`	`1301`
`1302`	`1302`	```json5
`1303`	`1303`	`{`