openclaw - 💡(How to fix) Fix sessions_spawn(runtime: "acp", agentId: "claude") returns ACP_TURN_FAILED reliably [1 comments, 2 participants]

Affected version

[email protected] with @agentclientprotocol/[email protected].

Severity

Medium. Intended-public agent-spawn path is broken, forces fallback to direct CLI invocation.

Symptoms

• sessions_spawn returns status: "accepted" immediately with a child session key.
• Internal completion event fires within ~1 second: failed: AcpRuntimeError: Internal error, 0 tokens, no useful detail in client-facing error.
• Gateway log shows: agent errorCode=UNAVAILABLE errorMessage=AcpRuntimeError: Internal error code=ACP_TURN_FAILED.
• Reproduces every time across multiple sessions on 2026-05-05.

Verified working in isolation

• The Claude ACP bridge (@agentclientprotocol/[email protected]) responds correctly to JSON-RPC initialize when invoked directly via ~/.openclaw/acpx/claude-agent-acp-wrapper.mjs. Returns full agent capabilities.
• claude -p (the underlying Claude Code CLI) works correctly when invoked in background.
• Auth is working (ANTHROPIC_API_KEY accepted).

Failure is in OpenClaw's ACP runtime → bridge handshake, not in any of: wrapper, bridge, Claude Code, or auth.

Workaround

• Invoke claude -p "$prompt" --output-format json --add-dir <workspace> --permission-mode acceptEdits --model claude-opus-4-7 > /tmp/output.log 2>&1 & in the background.
• Bypasses sessions_spawn entirely.
• Cost: no live progress visibility, no announce delivery, manual log parsing on completion.

What upstream needs to fix

1. Surface a more specific error than "Internal error" when ACP_TURN_FAILED fires.
2. If the failure is a timeout, expose the timeout boundary.
3. If it's a credential mismatch, name the credential.
4. Provide an openclaw doctor check that exercises the ACP runtime end-to-end, not just plugin presence.

Repro

sessions_spawn runtime="acp" agentId="claude" mode="run" task="Say hello"
# Returns 1-second failure with ACP_TURN_FAILED