PR #84397: fix: prompt Codex to send visible channel replies

• Repository: openclaw/openclaw
• Author: joshavant
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/84397

Description (problem / solution / changelog)

Summary

• Problem: Codex app-server message-tool-only turns could end with private final assistant text instead of sending a visible channel reply through message(action="send").
• Solution: Strengthen the message-tool-only runtime/developer guidance so visible output is explicitly tied to a message tool send before the turn ends.
• What changed: Updated Codex app-server reply instructions, auto-reply channel context, ACP delivery hints, message tool descriptions, tests, and prompt snapshots.
• What did NOT change: No default delivery-mode flip, no channel-specific workaround, and no changelog entry in the opening PR commit.

Motivation

• Closes #84129. Live Telegram/Codex repro showed the visible-reply path depends on Codex choosing message(action="send"); the fix keeps the existing delivery architecture and makes that requirement explicit at the prompt/tool boundary.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #84129
• This PR fixes a bug or regression

Real behavior proof

• Behavior addressed: Telegram direct replies using Codex app-server with sourceReplyDeliveryMode=message_tool_only now instruct Codex to send visible output through message(action="send") instead of relying on private final text.
• Real environment tested: AWS Crabbox, lease cbx_c3d13b859625, Telegram direct inbound, openai-codex provider, gpt-5.5 model.
• Exact steps or command run after this patch: Ran the live Telegram direct repro from the patched branch in Crabbox, with heartbeat disabled and a unique inbound marker, then inspected OpenClaw gateway logs and Codex trajectory events.
• Evidence after fix: Crabbox run run_a3d9d6e4da7f; marker oc84129-direct-84129-20260520T014618Z-3037; trajectory contained one tool.call for message with action="send"; gateway log showed Telegram inbound processing followed by outbound send ok with message id 269.
• Observed result after fix: Codex called message(action="send"), Telegram outbound delivery succeeded, and the run completed normally.
• What was not tested: Other live channels beyond Telegram direct; CI will cover the focused unit/snapshot tests.
• Before evidence: Earlier live run reproduced the auth/profile failure mode seen by the reporter once provider auth was missing; after auth was fixed, the relevant failure mode was narrowed to Codex choosing private final output unless prompted to use message.

Root Cause

• Root cause: Message-tool-only turns had multiple prompt layers that said normal final output was private, but the instruction to use message(action="send") for visible channel output was too weak or inconsistent for Codex app-server direct-reply turns.
• Missing detection / guardrail: Prompt snapshots and tests did not lock the stronger visible-output requirement across Codex app-server, auto-reply metadata, ACP dispatch, and message-tool descriptions.
• Contributing context: The Codex app-server final answer is private to OpenClaw/Codex for this delivery mode, so a model final answer alone cannot satisfy a visible channel reply.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/codex/src/app-server/run-attempt.test.ts, src/auto-reply/reply/*.test.ts, src/agents/tools/message-tool.test.ts, src/gateway/tool-resolution.test.ts, and test/scripts/prompt-snapshots.test.ts.
• Scenario the test should lock in: Message-tool-only delivery guidance explicitly says visible output requires message(action="send") before ending the turn, while quiet turns should avoid sending.
• Why this is the smallest reliable guardrail: The bug is prompt/tool-contract behavior, so prompt unit assertions plus committed prompt snapshots catch regressions without needing a live provider for every change.
• Existing test that already covers this (if any): Existing prompt snapshot infrastructure covers the model-bound prompt shape; this PR updates the expected content.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Codex-backed message-tool-only channel replies should more reliably appear in the source channel when a visible response is needed.

Diagram (if applicable)

Before:
[channel message] -> Codex final text -> private to OpenClaw/Codex -> no visible reply

After:
[channel message] -> Codex calls message(action="send") -> channel delivery -> visible reply

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: AWS Crabbox Linux for live proof; local macOS checkout for focused tests.
• Runtime/container: OpenClaw current branch on Crabbox; local Node/Vitest via node scripts/run-vitest.mjs.
• Model/provider: gpt-5.5 via openai-codex.
• Integration/channel (if any): Telegram direct.
• Relevant config (redacted): Gateway auth and Telegram credentials supplied through existing local/Crabbox credential paths; no secrets included here.

Steps

1. Start OpenClaw on Crabbox from the patched branch with Codex app-server and Telegram direct channel enabled.
2. Send a unique Telegram direct inbound marker.
3. Inspect Codex trajectory and gateway logs for message(action="send") and outbound Telegram delivery.

Expected

• Codex sends visible output through the message tool before ending the turn.

Actual

• Codex called message(action="send"), Telegram outbound send succeeded, and the run completed normally.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Focused local verification after rebasing onto current origin/main:

git diff --check
node scripts/run-vitest.mjs src/gateway/tool-resolution.test.ts extensions/codex/src/app-server/run-attempt.test.ts src/auto-reply/reply/groups.test.ts src/auto-reply/reply/inbound-meta.test.ts src/auto-reply/reply/dispatch-acp.test.ts src/agents/tools/message-tool.test.ts test/scripts/prompt-snapshots.test.ts

Result: 10 test files passed, 416 tests passed.

Autoreview:

AUTOREVIEW_AUTO_TESTS=0 .agents/skills/autoreview/scripts/autoreview --mode local

Result: autoreview clean: no accepted/actionable findings reported.

Human Verification (required)

• Verified scenarios: Live Telegram direct inbound with Codex app-server, focused prompt/tool tests, prompt snapshots, diff whitespace hygiene, autoreview.
• Edge cases checked: Message tool unavailable in Codex developer instructions still falls back to the active Codex delivery path; quiet/no-visible-output instructions still tell Codex not to call message(action="send").
• What you did not verify: Other live channels and a full repository check.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Stronger prompt wording could make Codex send when the right behavior is silence.
  • Mitigation: The wording explicitly preserves the no-visible-output path and tests assert that quiet turns should not call message(action="send").

Changed files

• CHANGELOG.md (modified, +1/-0)
• extensions/codex/src/app-server/run-attempt.test.ts (modified, +7/-2)
• extensions/codex/src/app-server/thread-lifecycle.ts (modified, +6/-1)
• src/agents/tools/message-tool.test.ts (modified, +6/-4)
• src/agents/tools/message-tool.ts (modified, +1/-1)
• src/auto-reply/reply/dispatch-acp.test.ts (modified, +1/-1)
• src/auto-reply/reply/dispatch-acp.ts (modified, +1/-1)
• src/auto-reply/reply/groups.test.ts (modified, +4/-4)
• src/auto-reply/reply/groups.ts (modified, +4/-4)
• src/auto-reply/reply/inbound-meta.test.ts (modified, +4/-2)
• src/auto-reply/reply/inbound-meta.ts (modified, +2/-1)
• src/gateway/tool-resolution.test.ts (modified, +1/-1)
• test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/discord-group-codex-message-tool.md (modified, +8/-8)
• test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-direct-codex-message-tool.md (modified, +9/-9)
• test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/telegram-heartbeat-codex-tool.md (modified, +8/-8)
• test/helpers/agents/happy-path-prompt-snapshots.ts (modified, +1/-1)