Summary

sessions_spawn(runtime: "acp", agentId: "claude") consistently fails immediately with a redacted AcpRuntimeError: Internal error / ACP_TURN_FAILED, consuming 0 tokens and producing no claude / acpx / claude-agent-acp subprocess. Direct claude --print and direct claude-agent-acp ACP handshake both work; the failure appears to be in the OpenClaw → acpx → claude-agent-acp → claude-cli bridge, or in OpenClaw's session/bootstrap coordination around it.

Steps to reproduce

1. Start OpenClaw 2026.5.7 gateway with default configuration plus the bundled acpx plugin (claude allowlisted as ACP agent).
2. Trigger sessions_spawn(runtime: "acp", agentId: "claude", task: "say ping", cwd: "/Users/jarvinder/clawd").
3. Observe the gateway log line [ws] ⇄ res ✗ agent errorCode=UNAVAILABLE errorMessage=AcpRuntimeError: Internal error … code=ACP_TURN_FAILED within 1 second.
4. Confirm via ps -ef during the failure window that no claude, claude-agent-acp, or acpx subprocess was spawned.

Reproduced consistently across 6+ spawn attempts with varied task content (10 chars to 30 KB), runtime budgets (60s to 14400s), and cwd directories.

Expected behavior

A successful ACP turn against Claude Code: claude subprocess spawns, ACP initialize + prompt round-trips complete, the prompt response is returned, tokens are consumed.

Direct invocation works correctly:

• claude --print "Say ping" → returns ping, ~3 second wall time
• node ~/.openclaw/npm/node_modules/@agentclientprotocol/claude-agent-acp/dist/index.js responds to JSON-RPC initialize with {protocolVersion:1, agentCapabilities:..., agentInfo:{name:"@agentclientprotocol/claude-agent-acp", version:"0.32.0"}, ...}

The OpenClaw-mediated bridge should produce equivalent end-to-end behavior.

Actual behavior

Spawn fails in <1 second with errorCode=UNAVAILABLE / errorMessage=AcpRuntimeError: Internal error / code=ACP_TURN_FAILED. Zero tokens consumed (tokens 0 (in 0 / out 0)). No claude/acpx subprocess spawned.

The error originates somewhere that does NOT pass through toAcpRuntimeError in errors-N-1tSJ3j.js (verified by patching that function to log full error details to /tmp/openclaw-acp-debug.log — the file remained empty during the failure window).

Notably, when acpx and @agentclientprotocol/claude-agent-acp were both manually upgraded to [email protected] + [email protected] (with the @openclaw/[email protected] wrapper package.json patched to pin the new versions to survive restart), the failure mode CHANGED to:

errorCode=UNAVAILABLE
errorMessage=AcpRuntimeError: ACP metadata is missing for agent:claude:acp:e6deb87a-…. Recreate this ACP session with /acp spawn and rebind the thread.
code=ACP_SESSION_INIT_FAILED

This suggests the original failure is sensitive to the bundled ACP runtime stack and may involve session metadata or bootstrap coordination between the gateway and the bundled adapters. Note that openclaw acp CLI does not expose a spawn subcommand, so the recommended remediation is not directly reachable.

OpenClaw version

2026.5.7 (commit eeef486) — also reproduced on 2026.5.6 with identical failure.

Operating system

macOS 25.4.0 (Darwin arm64) — Mac mini

Install method

npm global (/usr/local/lib/node_modules/openclaw), launchctl-managed gateway (ai.openclaw.gateway LaunchAgent)

Model

anthropic/claude-opus-4-7 (default agent model in OpenClaw config; agentId=claude ACP harness target)

Provider / routing chain

openclaw gateway → embedded acpx plugin → @openclaw/[email protected] → [email protected] → @agentclientprotocol/[email protected] → claude-cli (@anthropic-ai/[email protected]) → Anthropic API

Additional provider/model setup details

• Anthropic auth via ANTHROPIC_API_KEY environment variable (not claude.ai Pro keychain auth)
• Env var verified propagated to the gateway process via ps eww $(pgrep -f openclaw.*gateway) — ANTHROPIC_API_KEY=sk-ant-… present in the gateway process environment
• claude auth status reports {loggedIn:true, authMethod:"api_key", apiKeySource:"ANTHROPIC_API_KEY"}
• claude auth logout was used to clear prior claude.ai Pro keychain auth before switching to API key
• Bundled adapter resolution: ~/.openclaw/npm/node_modules/@agentclientprotocol/[email protected] and ~/.openclaw/npm/node_modules/[email protected]
• @openclaw/[email protected] wrapper at ~/.openclaw/npm/node_modules/@openclaw/acpx/package.json pins claude-agent-acp: 0.32.0 and acpx: 0.6.1 explicitly

Logs, screenshots, and evidence

2026-05-10T11:45:39.417+12:00 [ws] ⇄ res ✗ agent
  errorCode=UNAVAILABLE
  errorMessage=AcpRuntimeError: Internal error
  runId=c767393f-24ba-498a-abab-4ca6d485d41c
  error=AcpRuntimeError: Internal error: code=ACP_TURN_FAILED
  conn=96ae02f7…c2e6
  id=35868501…8287

(no other log lines from acpx, claude-agent-acp, or claude during the 5-second failure window)
(ps -ef snapshots taken every 1s during the window: zero claude/acpx/claude-agent-acp processes)

# Version matrix tested
| OpenClaw | acpx   | claude-agent-acp | Result                                              |
| -------- | ------ | ---------------- | --------------------------------------------------- |
| 2026.5.6 | 0.6.1  | 0.32.0           | ACP_TURN_FAILED / Internal error                    |
| 2026.5.7 | 0.6.1  | 0.32.0           | ACP_TURN_FAILED / Internal error (unchanged)        |
| 2026.5.7 | 0.6.1  | 0.33.1           | ACP_TURN_FAILED / Internal error (unchanged)        |
| 2026.5.7 | 0.7.0  | 0.33.1           | ACP_SESSION_INIT_FAILED / ACP metadata is missing   |  ← changed

# Diagnostic patch (rolled back) - toAcpRuntimeError instrumentation result
#   Patched errors-N-1tSJ3j.js toAcpRuntimeError() with try/catch logging
#   block capturing params.error.{name, message, code, stack, JSON via
#   getOwnPropertyNames, String coercion} to /tmp/openclaw-acp-debug.log.
#   Restarted gateway. Triggered spawn. /tmp/openclaw-acp-debug.log remained
#   empty (0 bytes) for the entire failure window. Conclusion: the error path
#   does NOT pass through toAcpRuntimeError. Original errors-N-1tSJ3j.js
#   restored byte-for-byte from backup before further testing.

# Theories eliminated with evidence:
#   1. figma-mcp interference         - removed from acpx config, failure unchanged
#   2. Pro keychain auth              - switched to ANTHROPIC_API_KEY, failure unchanged
#   3. --append-system-prompt-file    - flag supported by claude-cli 2.1.138 (verified)
#   4. Raw mode / PTY                 - no "Raw mode is not supported" in any log
#   5. toAcpRuntimeError redaction    - patched + verified empty log (above)
#   6. OpenClaw 2026.5.6 -> 2026.5.7  - upgraded, failure unchanged
#   7. claude-agent-acp 0.32.0 -> 0.33.1 alone - failure unchanged
#   8. acpx 0.6.1 -> 0.7.0 + claude-agent-acp 0.33.1 together - failure CHANGED to ACP_SESSION_INIT_FAILED

# Verified working in isolation:
#   - claude --print "Say ping" returns "ping" with API key auth
#   - claude-agent-acp dist/index.js direct ACP initialize handshake works
#   - openclaw acp client (interactive ACP client) launches and creates a session
#   - claude doctor returns clean
#   - All other plugins (telegram, whatsapp, bluebubbles, browser, memory-core) healthy

Impact and severity

• Affected: any user invoking sessions_spawn(runtime: "acp", agentId: "claude") to drive Claude Code as a sub-agent build runtime
• Severity: Blocks workflow. The Claude Code ACP path is the canonical route for delegating long-running build tasks; the failure forces fallback to manual claude invocation in a terminal session, which removes OpenClaw's session-binding, transcript persistence, completion announcement, and structured progress reporting
• Frequency: Always — observed in 6+ consecutive attempts across version combinations
• Consequence: Long-running build sessions cannot be delegated programmatically through OpenClaw; user must keep an interactive terminal alive and copy results back manually

Additional information

Final state was restored to clean OpenClaw-pinned versions (@agentclientprotocol/[email protected], [email protected], original @openclaw/acpx/package.json md5 79bf3c902e7ae85811617fb6f18bebec) with gateway restart confirmed before filing this report. No diagnostic patches or version overrides remain on disk.

Hypothesis (unconfirmed): the "Internal error" message corresponds to JSON-RPC error code -32603 emitted by @agentclientprotocol/sdk's RequestError constructor (return new RequestError(-32603, \Internal error${additionalMessage ? `: ${additionalMessage}` : ""}`, data);). This is consistent with a thrown exception inside the spawned ACP runtime that the SDK converts to a JSON-RPC InternalError response, which OpenClaw then wraps as AcpRuntimeError`. Without readable/unminified source or a debug flag for the gateway's spawn coordination path, the throwing exception's location could not be isolated.

The "ACP metadata is missing" error from the bundled-dep upgrade test points at session bootstrap as a plausible failure location.

Asks of the maintainers (in order of usefulness):

1. Where in the gateway / session bootstrap code path is this failure emitted or wrapped? Pointers to the spawn coordination code path would let us continue diagnosis.
2. Is there a supported debug flag (e.g. OPENCLAW_DEBUG_ACP=1) to expose the original exception? Current redaction means even toAcpRuntimeError instrumentation doesn't capture the cause.
3. Is @openclaw/[email protected] expected to work with newer bundled [email protected] and [email protected]? The combined upgrade produces a different failure mode that suggests bootstrap mismatch.
4. Is the "ACP metadata is missing" error expected after manual runtime upgrades, or does it indicate a session bootstrap mismatch in OpenClaw's gateway code? The message points users to /acp spawn which doesn't appear to be reachable from the standard openclaw acp CLI.
5. Is ANTHROPIC_API_KEY env var auth officially supported for the Claude ACP bridge path? Documentation we found references claude.ai Pro auth and keychain; we are using API key via env var because Pro keychain auth is not currently working on macOS for [email protected].