openclaw - 💡(How to fix) Fix ACP sessions_spawn(runtime=acp, agentId=claude) fails after connection_close while direct acpx wrapper succeeds [1 comments, 2 participants]

Summary

questions_spawn / sessions_spawn with runtime="acp" and agentId="claude" fails in the OpenClaw ACP manager lifecycle with AcpRuntimeError: Internal error / ACP_TURN_FAILED, while direct acpx using the exact same OpenClaw-generated Claude ACP wrapper succeeds.

This suggests the failure is in OpenClaw's ACP manager / one-shot turn lifecycle, not in Claude Code auth, acpx, @agentclientprotocol/claude-agent-acp, or the generated wrapper command.

Environment

• OpenClaw: 2026.5.7 (eeef486)
• Node: v22.22.0
• Claude Code CLI: 2.1.138
• @openclaw/acpx: 2026.5.7
• acpx: 0.6.1
• @agentclientprotocol/claude-agent-acp: 0.32.0
• OS: Linux x64
• ACP config:
  • acp.enabled=true
  • acp.backend="acpx"
  • acp.defaultAgent="claude"
  • acp.dispatch.enabled=true
  • plugins.entries.acpx.enabled=true

What works

Direct acpx claude exec works:

/root/.openclaw/npm/node_modules/.bin/acpx \
  --timeout 180 \
  --format quiet \
  --cwd /root/.openclaw/workspace \
  claude exec 'Reply with exactly DIRECT_ACPX_OK and no other text.'

Observed result:

DIRECT_ACPX_OK
[acpx] tokens: input=6 output=17 cache_read=16191 cache_write=25811 total=42025
rc=0

Direct acpx using the exact OpenClaw-generated Claude ACP wrapper also works:

/root/.openclaw/npm/node_modules/.bin/acpx \
  --timeout 180 \
  --format quiet \
  --cwd /root/.openclaw/workspace \
  --agent '/usr/bin/node /root/.openclaw/acpx/claude-agent-acp-wrapper.mjs' \
  exec 'Reply with exactly WRAPPER_DIRECT_OK and no other text.'

Observed result:

WRAPPER_DIRECT_OK
[acpx] tokens: input=6 output=19 cache_read=16191 cache_write=25813 total=42029
rc=0

A local reusable wrapper using that direct path was also smoke-tested successfully:

DIRECT_WRAPPER_OK
[acpx] tokens: input=6 output=19 cache_read=16191 cache_write=25814 total=42030
rc=0

What fails

OpenClaw ACP runtime path fails:

sessions_spawn({
  runtime: "acp",
  agentId: "claude",
  mode: "run",
  task: "Debug repro only. Reply exactly: DEBUG_ACP_REPRO_OK",
  cwd: "/root/.openclaw/workspace",
  runTimeoutSeconds: 240,
  cleanup: "keep",
  sandbox: "inherit"
})

Observed result:

Background task failed: acp-debug-repro-20260510 (run 855185d7-030a-4b5d-be88-ef981fff0bc9). Internal error

Debug capture

Run id:

855185d7-030a-4b5d-be88-ef981fff0bc9

Child session key:

agent:claude:acp:484bcd47-b2e7-4499-bf4e-c33812b802f9

Stream log:

/root/.openclaw/agents/claude/sessions/0be61bbd-60cc-46b7-af64-8730915dc33d.acp-stream.jsonl

Stream lifecycle:

{"kind":"system_event","text":"Started claude session agent:claude:acp:484bcd47-b2e7-4499-bf4e-c33812b802f9. Streaming progress updates to parent session."}
{"kind":"lifecycle","phase":"start","data":{"phase":"start","startedAt":1778422354107}}
{"kind":"lifecycle","phase":"error","data":{"phase":"error","error":"Internal error","endedAt":1778422357546}}
{"kind":"system_event","text":"claude run failed: Internal error"}

The failure happens in about 3.4 seconds, despite runTimeoutSeconds=240. This is not the expected turn timeout path.

Gateway debug log includes:

acp-manager: session identity updated for agent:claude:acp:484bcd47-b2e7-4499-bf4e-c33812b802f9
  (agentSessionId <none> -> <none>,
   acpxSessionId 75b54e4c-fabc-4615-963d-c4e7e3d9be02 -> ad4670af-98b0-4771-955b-561264af3df9,
   acpxRecordId ...:oneshot:bab8fa4a-5792-447d-aed8-b5f3998e6d99 -> ...:oneshot:bab8fa4a-5792-447d-aed8-b5f3998e6d99)

AcpRuntimeError: Internal error: code=ACP_TURN_FAILED

Session state after failure shows two one-shot records for the same child session.

First record:

acpx_record_id = agent:claude:acp:484bcd47-b2e7-4499-bf4e-c33812b802f9:oneshot:bab8fa4a-5792-447d-aed8-b5f3998e6d99
acp_session_id = ad4670af-98b0-4771-955b-561264af3df9
agent_command = "/usr/bin/node" "/root/.openclaw/acpx/claude-agent-acp-wrapper.mjs"
cwd = /root/.openclaw/workspace
closed = true
closed_at = 2026-05-10T14:12:37.545Z
last_agent_disconnect_reason = connection_close
messages_len = 0

Second record:

acpx_record_id = agent:claude:acp:484bcd47-b2e7-4499-bf4e-c33812b802f9:oneshot:a49a2dec-416c-4121-9a56-34c10e7a6b92
acp_session_id = 34a70977-21be-408c-ac4e-1384d11fb00d
agent_command = "/usr/bin/node" "/root/.openclaw/acpx/claude-agent-acp-wrapper.mjs"
cwd = /root/.openclaw/workspace
closed = false
messages_len = 0

Expected behavior

Since direct acpx succeeds using the same wrapper, sessions_spawn(runtime="acp", agentId="claude") should either:

1. complete successfully, or
2. surface the underlying acpx / JSON-RPC / adapter error clearly.

It should not collapse the failure to Internal error, and it should not leave a second open one-shot record after the failed turn.

Actual behavior

• sessions_spawn(runtime="acp", agentId="claude") fails after ~3.4s with AcpRuntimeError: Internal error / ACP_TURN_FAILED.
• The first one-shot ACP session closes with last_agent_disconnect_reason=connection_close.
• A second one-shot ACP session record remains open for the same child session key.
• No assistant messages are recorded.
• Gateway debug logging still does not expose the lower-level reason for the ACP turn failure.

Suspected area

This looks like an OpenClaw ACP manager / one-shot turn lifecycle issue rather than a Claude adapter issue:

• one-shot runtime session creation succeeds;
• the OpenClaw-generated wrapper command is valid and works through direct acpx;
• direct acpx returns successfully after ~74-77s;
• OpenClaw manager fails after ~3.4s;
• failure path appears to involve connection_close, identity reconciliation, and/or fresh handle retry / cleanup behavior.

Suggested investigation areas:

1. Preserve lower-level acpx / JSON-RPC / adapter errors in consumeAcpTurnStream, awaitTurnWithTimeout, and withAcpRuntimeErrorBoundary instead of collapsing to Internal error.
2. Inspect one-shot connection_close handling. It may be treated as fatal before a terminal ACP turn event is observed.
3. Inspect fresh-handle retry / identity reconciliation behavior after a failed one-shot turn. If retry is intended, the turn should be replayed fully; otherwise the second orphan/open one-shot record should be closed or avoided.
4. Verify runTimeoutSeconds / runtime timeoutSeconds propagation. The observed failure happens far earlier than the configured timeout.

Related prior reports

This appears related to previous ACP runtime-path reports where direct acpx works but OpenClaw sessions_spawn(runtime="acp") fails or hangs, for example:

• ACP turns fail with "Internal error" after upgrade... / ACP_TURN_FAILED
• sessions_spawn(runtime="acp") hangs immediately — acpx never produces output...
• older NO_SESSION / prompt session lifecycle reports

This report adds a current 2026.5.7 repro showing that direct acpx with the same generated Claude wrapper succeeds, while the OpenClaw ACP manager path fails quickly and leaves an additional open one-shot session record.