openclaw - 💡(How to fix) Fix Codex ACP gateway path can surface bare ACP_TURN_FAILED when active acpx plugin misses runtime hardening

Summary

On an OpenClaw v2026.5.18 Linux install, the gateway loaded a user-level @openclaw/acpx plugin at 2026.5.12 while the bundled OpenClaw runtime already contained newer Codex ACP hardening. The active ACP/Codex path therefore did not have the same diagnostics/retry behavior as the bundled build.

The observed failure shape was:

AcpRuntimeError: Internal error
code=ACP_TURN_FAILED

The affected Codex ACP child turns failed before producing a command/output/final artifact, so parent workflows saw a hard blocker with no useful underlying cause.

Impact

• Background ACP/Codex work can fail before the task starts.
• The visible error is too generic to distinguish app-server lifecycle, ACP adapter, transport, or model/runtime failure.
• A deployment can appear updated to a newer OpenClaw version while still running an older globally installed ACPX plugin for the active gateway path.

Expected behavior

The active ACP runtime should either:

• use the bundled runtime hardening that ships with the installed OpenClaw version, or
• ensure the user-level/global @openclaw/acpx plugin is upgraded or compatibility-checked during OpenClaw update/startup.

For transient Codex ACP failures before prompt side effects, the runtime should make a bounded retry before returning ACP_TURN_FAILED. If it still fails, the terminal error should include sanitized adapter/runtime diagnostics rather than only Internal error.

Local mitigation tested

A local installed-build mitigation was applied and validated:

• added bounded retries around transient ACP prompt failures before any prompt-side session updates/client operations;
• treated bare/generic Internal error, connection-closed, query-closed, and client-closed shapes as retryable only while no prompt side effects were observed;
• ported the Codex ACP wrapper stderr-tail diagnostic enrichment into the active user-level @openclaw/acpx runtime, with token-like values redacted;
• restarted the gateway;
• verified gateway /health returned live/ok;
• verified direct acpx codex exec smoke completed;
• verified direct AcpxRuntime class smoke completed through the active plugin runtime;
• verified no new ACP_TURN_FAILED, AcpRuntimeError, or codex app-server client is closed log entries appeared after restart during the smoke window.

Suggested durable fix

1. Add an update/startup compatibility check that detects when a user-level/global @openclaw/acpx plugin is older than the bundled runtime expectations.
2. Move the Codex ACP stderr-tail diagnostic wrapper into the maintained plugin/runtime source, not only the bundled OpenClaw build.
3. Add a bounded retry in the ACP runtime startTurn path for transient pre-side-effect prompt failures.
4. Add regression coverage for:
   • bare ACP internal error before any assistant/tool/session update;
   • connection/client closed before prompt side effects;
   • no retry after assistant output, tool call, or other side effect;
   • sanitized diagnostics when Codex ACP wrapper stderr exists.

Related

• #83959 covers Codex app-server startup retry exhaustion.
• #83863 covered progress-only/false-success completion contracts. This issue is distinct: the turn fails before producing a deliverable and the active plugin can miss the runtime hardening present in the bundled install.