openclaw - 💡(How to fix) Fix Claude ACP sessions fail via OpenClaw sessions_spawn with ACP_TURN_FAILED while direct ACPX works [2 comments, 2 participants]

Summary

OpenClaw ACP spawning with runtime: "acp" and agentId: "claude" fails reproducibly with:

AcpRuntimeError: Internal error: code=ACP_TURN_FAILED

The same Claude ACP setup works when invoked directly through ACPX CLI, and also works through the ACPX Runtime API directly. This suggests the issue is likely in OpenClaw's ACP spawn / turn handling path rather than Claude Code, the Claude ACP wrapper, ACPX itself, or the project cwd.

Environment

• OpenClaw: 2026.5.5 (b1abf9d)
• Node.js: 24.14.1
• OS: Linux x64
• Gateway: systemd user service
• ACP backend: acpx
• @openclaw/acpx: 2026.5.4
• acpx: 0.6.1
• Claude ACP package from @openclaw/acpx dependencies: @agentclientprotocol/[email protected]
• Target cwd: /home/zoe/projects/zoe-memory
• ACP config:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude",
    "allowedAgents": ["claude"]
  },
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "permissionMode": "approve-all"
        }
      }
    }
  }
}

Expected behavior

A minimal OpenClaw ACP spawn should complete and return the Claude response, similar to direct ACPX CLI / Runtime API execution.

Example expected output:

OPENCLAW_ACP_NOTOOL_OK

or for a cwd/file smoke test:

OPENCLAW_ACP_MODEL_OK cwd=zoe-memory files=yes

Actual behavior

OpenClaw sessions_spawn(runtime: "acp", agentId: "claude") starts the ACP session, but the turn fails shortly after with:

AcpRuntimeError: Internal error: code=ACP_TURN_FAILED

Observed OpenClaw log line:

agent errorCode=UNAVAILABLE errorMessage=AcpRuntimeError: Internal error
error=AcpRuntimeError: Internal error: code=ACP_TURN_FAILED

The ACP session state file indicates session initialization succeeds:

• schema: acpx.session.v1
• cwd: correct target cwd
• agent command: Claude ACP wrapper
• protocol initialized
• Claude capabilities present
• current_model_id: "opus" when explicitly overridden
• messages remain empty
• session closes with last_agent_disconnect_reason: "connection_close"

Reproduction

1. Direct ACPX CLI succeeds

node ~/.openclaw/npm/node_modules/acpx/dist/cli.js \
  --cwd /home/zoe/projects/zoe-memory \
  --approve-all \
  --timeout 90 \
  --format text \
  claude exec 'Read-only smoke test. Reply exactly: ACPX_DIRECT_OK. Do not modify files.'

Observed result:

[client] initialize (running)
[client] session/new (running)
ACPX_DIRECT_OK
[done] end_turn

2. Direct ACPX CLI with explicit Claude model succeeds

node ~/.openclaw/npm/node_modules/acpx/dist/cli.js \
  --cwd /home/zoe/projects/zoe-memory \
  --approve-all \
  --timeout 90 \
  --format text \
  --model opus \
  claude exec 'Read-only smoke test. Reply exactly: ACPX_DIRECT_OPUS_OK. Do not modify files.'

Observed result:

ACPX_DIRECT_OPUS_OK
[done] end_turn

3. Direct ACPX Runtime API succeeds

Using createAcpRuntime(...) directly from acpx/dist/runtime.js with the same cwd and Claude wrapper also succeeds.

Observed event stream includes:

RUNTIME_RUNTURN_OK

and terminal event:

{"type":"done","stopReason":"end_turn"}

4. OpenClaw ACP spawn fails

OpenClaw tool/runtime call equivalent:

sessions_spawn({
  runtime: "acp",
  agentId: "claude",
  cwd: "/home/zoe/projects/zoe-memory",
  model: "opus",
  task: "Read-only ACP runtime no-tool smoke test. Reply exactly: OPENCLAW_ACP_NOTOOL_OK. Do not inspect files, do not call tools, do not modify files.",
  mode: "run"
})

Observed result:

failed: AcpRuntimeError: Internal error

Log:

AcpRuntimeError: Internal error: code=ACP_TURN_FAILED

This also fails with a cwd/file smoke prompt, so it does not appear to be caused by tool execution or file access.

Additional observation

When no model override is supplied, OpenClaw appears to pass the current OpenClaw model override through to Claude ACP. In my setup that was gpt-5.5, which Claude ACP rejects:

There's an issue with the selected model (gpt-5.5). It may not exist or you may not have access to it.

However, even when explicitly using model: "opus" for the OpenClaw ACP spawn, the OpenClaw path still fails with ACP_TURN_FAILED, while direct ACPX CLI/API with opus succeeds.

So there may be two related issues:

1. OpenClaw ACP spawn may pass non-Claude model IDs to Claude ACP unless explicitly overridden.
2. Even with a valid Claude model (opus), OpenClaw ACP spawn/turn handling still fails.

Impact

ACP/Claude can be used directly via ACPX, but cannot currently be used reliably through OpenClaw sessions_spawn(runtime: "acp"). This blocks using Claude ACP as an OpenClaw-managed coding subagent.

Notes

This was tested read-only. No file modifications, installs, commits, or service restarts were required for the reproduction.