ACP Bug Investigation: Protocol Mismatch Causes 'metadata is missing' Error with Local Ollama

Bug Confirmed in ACP/OpenClaw Integration

A developer has identified and documented a bug affecting the ACP (Agent Control Protocol) integration with OpenClaw when using local Ollama models. The issue prevents acpx spawn commands from functioning properly.

Environment Details

• OpenClaw: 2026.3.13
• acpx: Latest (npm -g)
• Ollama: Local (kimi-k2.5:cloud, glm-5:cloud)
• OS: macOS (Apple Silicon)
• Node: v22.19.0

The Bug

Commands that fail:

acpx spawn exec -- "test"
# or
acpx spawn sessions new --name test

Error messages received:

ACP error (ACP_SESSION_INIT_FAILED): ACP metadata is missing for agent:main:acp:...

Failed to parse JSON message: [commands] /help /commands /status...
SyntaxError: Unexpected token 'c', "[commands] ..." is not valid JSON

What Works vs. What Doesn't

Working:

• openclaw acp client --help (client starts)
• openclaw acp client (standalone mode)
• acpx config show (config loads)

Not Working:

• acpx spawn exec -- "test" (fails with "metadata is missing")
• acpx spawn sessions new --name test (fails to create session)
• Any ACP spawn command

Root Cause Analysis

The issue appears to be a protocol mismatch:

• acpx spawns the agent command (openclaw acp client)
• The client starts and outputs text (help message, session info)
• acpx expects JSON messages over the pipe
• JSON parsing fails → "metadata is missing" → spawn fails

Key log showing the problem:

[acpx] spawning agent: openclaw acp client
[client] initialize (running)
Failed to parse JSON message: [commands] /help /commands...
→ acpx expects JSON, receives text

Current Status

Workaround: None found. The issue is at the protocol level between acpx and openclaw acp client.

Alternative: Use runtime: "subagent" instead of ACP — works perfectly.

Impact: Cannot use ACP for long-running autonomous agents with local Ollama.

Priority: Medium (subagent works, but ACP would be better for complex workflows).

The developer has requested the OpenClaw team investigate why openclaw acp client outputs text instead of JSON when spawned by acpx, whether there's a missing --json flag or config option, and if this is a known issue with local Ollama setups.