fix(messages): keep Codex direct replies automatic

steipete · steipete · commit 1699ebb49c60 · 2026-05-18T11:57:53.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -38,6 +38,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Messages/Codex: keep direct Codex-backed chats on the same automatic final-reply default as other source chats unless `messages.visibleReplies: "message_tool"` is explicitly configured.
 - Codex app-server: preserve network access for sandboxed Codex code-mode turns when the OpenClaw sandbox allows outbound egress. Fixes #83347. Thanks @YusukeIt0.
 - QA-Lab: keep the OTLP smoke decoder independent of removed OpenTelemetry generated-root internals.
 - Messages: default group/channel visible replies to automatic final delivery again, keeping `message_tool` opt-in for ambient/shared rooms and tool-reliable models.
diff --git a/docs/channels/groups.md b/docs/channels/groups.md
@@ -51,7 +51,7 @@ 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.
 
-For direct chats and any other source event, use `messages.visibleReplies: "message_tool"` to apply the same tool-only visible-reply behavior globally. Harnesses can also choose this as their unset default; the Codex harness does this for Codex-mode direct chats. `messages.groupChat.visibleReplies` remains the more specific override for group/channel rooms.
+For direct chats and any other source event, use `messages.visibleReplies: "message_tool"` to apply the same tool-only visible-reply behavior globally. When unset, direct/source chats use automatic final delivery across runtimes, including Codex. `messages.groupChat.visibleReplies` remains the more specific override for group/channel rooms.
 
 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.
 
diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md
@@ -787,7 +787,7 @@ 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. Normal group/channel requests default to `messages.groupChat.visibleReplies: "automatic"`: final assistant text posts through the legacy visible reply path. Set `"message_tool"` when a shared room should only post visible output after the agent calls `message(action=send)`. If the model returns final text without calling the message tool, that final text stays private and the gateway verbose log records suppressed payload metadata. 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. Normal direct, group, and channel requests default to automatic final delivery: final assistant text posts through the legacy visible reply path. Set `"message_tool"` when a chat should only post visible output after the agent calls `message(action=send)`. If the model returns final text without calling the message tool, that final text stays private and the gateway verbose log records suppressed payload metadata.
 
 Tool-only visible replies require a model/runtime that reliably calls tools, and are recommended for shared ambient rooms on latest-generation models such as GPT 5.5. If
 the session log shows assistant text with `didSendViaMessagingTool: false`, the
@@ -810,7 +810,7 @@ The gateway hot-reloads `messages` config after the file is saved. Restart only
 ```json5
 {
   messages: {
-    visibleReplies: "automatic", // global default for direct/source chats; Codex harness defaults unset direct chats to message_tool
+    visibleReplies: "automatic", // global default for direct/source chats
     groupChat: {
       historyLimit: 50,
       unmentionedInbound: "room_event", // always-on unmentioned room chatter becomes quiet context
@@ -827,7 +827,7 @@ The gateway hot-reloads `messages` config after the file is saved. Restart only
 
 `messages.groupChat.unmentionedInbound: "room_event"` submits unmentioned always-on group/channel messages as quiet room context on supported channels. Mentioned messages, commands, and direct messages remain user requests. See [Ambient room events](/channels/ambient-room-events) for complete Discord, Slack, and Telegram examples.
 
-`messages.visibleReplies` is the global source-event default; `messages.groupChat.visibleReplies` overrides it for group/channel source events. 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 an event is processed.
+`messages.visibleReplies` is the global source-event default; `messages.groupChat.visibleReplies` overrides it for group/channel source events. When `messages.visibleReplies` is unset, direct/source chats use automatic final delivery across runtimes. Channel allowlists and mention gating still decide whether an event is processed.
 
 #### DM history limits
 
diff --git a/docs/plugins/codex-harness-runtime.md b/docs/plugins/codex-harness-runtime.md
@@ -33,12 +33,12 @@ newly selected model.
 
 ## Visible replies and heartbeats
 
-When a source chat turn runs through the Codex harness, visible replies default
-to the OpenClaw `message` tool if the deployment has not explicitly configured
-`messages.visibleReplies`. The agent can still finish its Codex turn privately;
-it only posts to the channel when it calls `message(action="send")`. Set
-`messages.visibleReplies: "automatic"` to keep direct-chat final replies on the
-legacy automatic delivery path.
+When a source chat turn runs through the Codex harness, visible replies follow
+the same source-delivery defaults as other runtimes. Direct chats, normal group
+requests, and normal channel requests automatically post final assistant text
+unless config opts into tool-only delivery. Set `messages.visibleReplies:
+"message_tool"` when direct/source chats should post visible output only after
+the agent calls `message(action="send")`.
 
 Codex heartbeat turns also get `heartbeat_respond` in the searchable OpenClaw
 tool catalog by default, so the agent can record whether the wake should stay
diff --git a/extensions/codex/harness.ts b/extensions/codex/harness.ts
@@ -23,9 +23,6 @@ export function createCodexAppServerAgentHarness(options?: {
   return {
     id: options?.id ?? "codex",
     label: options?.label ?? "Codex agent harness",
-    deliveryDefaults: {
-      sourceVisibleReplies: "message_tool",
-    },
     supports: (ctx) => {
       const provider = ctx.provider.trim().toLowerCase();
       if (providerIds.has(provider)) {
diff --git a/extensions/codex/index.test.ts b/extensions/codex/index.test.ts
@@ -72,9 +72,7 @@ describe("codex plugin", () => {
     expect(providerRegistration.label).toBe("Codex");
     expect(agentHarnessRegistration.id).toBe("codex");
     expect(agentHarnessRegistration.label).toBe("Codex agent harness");
-    expect(agentHarnessRegistration.deliveryDefaults).toEqual({
-      sourceVisibleReplies: "message_tool",
-    });
+    expect(agentHarnessRegistration.deliveryDefaults).toBeUndefined();
     expect(typeof agentHarnessRegistration.dispose).toBe("function");
     expect(mediaProviderRegistration?.id).toBe("codex");
     expect(mediaProviderRegistration?.capabilities).toEqual(["image"]);
@@ -121,7 +119,7 @@ describe("codex plugin", () => {
   it("only claims the codex provider by default", () => {
     const harness = createCodexAppServerAgentHarness();
 
-    expect(harness.deliveryDefaults?.sourceVisibleReplies).toBe("message_tool");
+    expect("deliveryDefaults" in harness).toBe(false);
     expect(
       harness.supports({ provider: "codex", modelId: "gpt-5.4", requestedRuntime: "auto" })
         .supported,
diff --git a/src/agents/harness/types.ts b/src/agents/harness/types.ts
@@ -59,8 +59,8 @@ export type AgentHarnessResultClassification =
 
 export type AgentHarnessDeliveryDefaults = {
   /**
-   * Preferred default for visible source replies when user config has not
-   * explicitly selected automatic or message-tool delivery.
+   * @deprecated Prefer `messages.visibleReplies` / `messages.groupChat.visibleReplies`
+   * config. Kept for existing harness plugins.
    */
   sourceVisibleReplies?: "automatic" | "message_tool";
 };
diff --git a/src/auto-reply/reply/dispatch-from-config.test.ts b/src/auto-reply/reply/dispatch-from-config.test.ts
@@ -5249,12 +5249,11 @@ describe("sendPolicy deny — suppress delivery, not processing (#53328)", () =>
     expect(firstFinalReplyPayload(dispatcher)?.text).toBe("visible direct reply");
   });
 
-  it("uses harness defaults for direct source delivery when config is unset", async () => {
+  it("keeps Codex direct source delivery automatic when config is unset", async () => {
     setNoAbort();
     registerAgentHarness({
       id: "codex",
       label: "Codex",
-      deliveryDefaults: { sourceVisibleReplies: "message_tool" },
       supports: () => ({ supported: true, priority: 100 }),
       runAttempt: vi.fn(async () => ({}) as never),
     });
@@ -5266,7 +5265,7 @@ describe("sendPolicy deny — suppress delivery, not processing (#53328)", () =>
     };
     const dispatcher = createDispatcher();
     const replyResolver = vi.fn(async (_ctx: MsgContext, opts?: GetReplyOptions) => {
-      expect(opts?.sourceReplyDeliveryMode).toBe("message_tool_only");
+      expect(opts?.sourceReplyDeliveryMode).toBe("automatic");
       return { text: "final reply" } satisfies ReplyPayload;
     });
 
@@ -5281,6 +5280,44 @@ describe("sendPolicy deny — suppress delivery, not processing (#53328)", () =>
       replyResolver,
     });
 
+    expect(replyResolver).toHaveBeenCalledTimes(1);
+    expect(result.queuedFinal).toBe(true);
+    expect(firstFinalReplyPayload(dispatcher)?.text).toBe("final reply");
+  });
+
+  it("preserves non-Codex harness direct source delivery defaults", async () => {
+    setNoAbort();
+    registerAgentHarness({
+      id: "custom",
+      label: "Custom",
+      deliveryDefaults: { sourceVisibleReplies: "message_tool" },
+      supports: () => ({ supported: true, priority: 200 }),
+      runAttempt: vi.fn(async () => ({}) as never),
+    });
+    sessionStoreMocks.currentEntry = {
+      sessionId: "s1",
+      updatedAt: 0,
+      agentHarnessId: "custom",
+      sendPolicy: "allow",
+    };
+    const dispatcher = createDispatcher();
+    const replyResolver = vi.fn(async (_ctx: MsgContext, opts?: GetReplyOptions) => {
+      expect(opts?.sourceReplyDeliveryMode).toBe("message_tool_only");
+      return { text: "private final reply" } satisfies ReplyPayload;
+    });
+
+    const result = await dispatchReplyFromConfig({
+      ctx: buildTestCtx({
+        ChatType: "direct",
+        CommandSource: undefined,
+        Provider: "custom",
+        SessionKey: "agent:main:main",
+      }),
+      cfg: emptyConfig,
+      dispatcher,
+      replyResolver,
+    });
+
     expect(replyResolver).toHaveBeenCalledTimes(1);
     expect(result.queuedFinal).toBe(false);
     expect(dispatcher.sendFinalReply).not.toHaveBeenCalled();
diff --git a/test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/README.md b/test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/README.md
@@ -5,7 +5,7 @@
 These fixtures capture the default OpenAI/Codex happy path for prompt review:
 
 - OpenAI model through the Codex harness and Codex app-server runtime.
-- `messages.visibleReplies: "message_tool"`, which is the Codex-harness default for visible source replies.
+- `messages.visibleReplies: "message_tool"` opt-in coverage for tool-only visible source replies.
 - Telegram direct chat, Discord group chat, and a heartbeat turn with `heartbeat_respond` available through searchable dynamic tools.
 
 The Markdown files show selected app-server thread/turn params plus a reconstructed model-bound prompt layer stack: Codex `gpt-5.5` model instructions from a pinned Codex model catalog fixture, Codex permission developer instructions for the happy-path yolo profile, simulated OpenClaw workspace bootstrap config instructions, OpenClaw developer instructions, user turn input, and references to the complete dynamic tool catalog.
diff --git a/test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md b/test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md
@@ -4,8 +4,8 @@
 
 ## Scope
 
-- Default happy path: OpenAI model through the Codex harness/runtime, Telegram direct conversation, and message-tool-only visible replies.
-- A quiet turn is represented by not calling `message(action=send)`; the normal final assistant text is private to OpenClaw/Codex.
+- Opt-in message-tool path: OpenAI model through the Codex harness/runtime, Telegram direct conversation, and message-tool-only visible replies.
+- This scenario forces tool-only delivery; the default Codex direct path uses automatic final replies.
 - This captures the OpenClaw-owned Codex app-server inputs and reconstructs the stable Codex model/permission layers from committed Codex prompt fixtures.
 - This also simulates workspace bootstrap files forwarded through Codex `config.instructions`: `SOUL.md`, `TOOLS.md`, and `HEARTBEAT.md`.
 
diff --git a/test/helpers/agents/happy-path-prompt-snapshots.ts b/test/helpers/agents/happy-path-prompt-snapshots.ts
@@ -436,8 +436,8 @@ function createScenarios(): PromptScenario[] {
       id: "telegram-direct-codex-message-tool",
       title: "Telegram Direct Codex Message Tool Turn",
       notes: [
-        "Default happy path: OpenAI model through the Codex harness/runtime, Telegram direct conversation, and message-tool-only visible replies.",
-        "A quiet turn is represented by not calling `message(action=send)`; the normal final assistant text is private to OpenClaw/Codex.",
+        "Opt-in message-tool path: OpenAI model through the Codex harness/runtime, Telegram direct conversation, and message-tool-only visible replies.",
+        "This scenario forces tool-only delivery; the default Codex direct path uses automatic final replies.",
       ],
       trigger: "user",
       ctx: telegramDirectCtx,
@@ -755,7 +755,7 @@ function renderReadme(scenarios: PromptScenario[]): string {
     "These fixtures capture the default OpenAI/Codex happy path for prompt review:",
     "",
     "- OpenAI model through the Codex harness and Codex app-server runtime.",
-    '- `messages.visibleReplies: "message_tool"`, which is the Codex-harness default for visible source replies.',
+    '- `messages.visibleReplies: "message_tool"` opt-in coverage for tool-only visible source replies.',
     "- Telegram direct chat, Discord group chat, and a heartbeat turn with `heartbeat_respond` available through searchable dynamic tools.",
     "",
     "The Markdown files show selected app-server thread/turn params plus a reconstructed model-bound prompt layer stack: Codex `gpt-5.5` model instructions from a pinned Codex model catalog fixture, Codex permission developer instructions for the happy-path yolo profile, simulated OpenClaw workspace bootstrap config instructions, OpenClaw developer instructions, user turn input, and references to the complete dynamic tool catalog.",
