Claude ACP config option handling: generic runtime controls fail while clean/model-only path works

[kAIborg24]

This is a cross-report for the OpenClaw integration issue tracked at openclaw/openclaw#73875. Filing here as well because the behavior sits at the OpenClaw-managed acpx / Claude ACP boundary, and the fix may involve acpx capability/config-option handling or documentation.

Summary

Claude Code via ACP/acpx works for a clean prompt and for a model override, but fails when OpenClaw applies some generic runtime controls as ACP session/set_config_option calls.

The failures appear tied to config option key mismatches / unsupported option forwarding:

• timeoutSeconds is mapped to ACP config key timeout, which Claude ACP does not advertise.
• thinking is mapped to ACP config key thinking, while current Claude ACP advertises effort for reasoning effort.
• Earlier testing also identified generic keys such as approval_policy as not being advertised Claude ACP config options.

Versions observed

• OpenClaw: 2026.5.4 (325df3e)
• @openclaw/acpx: 2026.5.4
• acpx: 0.6.1
• @agentclientprotocol/claude-agent-acp: 0.32.0
• @anthropic-ai/claude-agent-sdk: 0.2.126
• Node: 24.15.0

The original OpenClaw issue was filed against an older OpenClaw stack, and the same bug class still reproduces on the current-version stack above.

Smoke test matrix

Observed through OpenClaw-managed Claude ACP sessions using acpx as the backend:

• Direct ACPX -> Claude trivial prompt: succeeds
• OpenClaw-managed Claude ACP, no override / clean prompt: succeeds on the newer stack
• model: "sonnet": succeeds
• timeoutSeconds: 180: fails with AcpRuntimeError: Internal error / ACP_TURN_FAILED
• thinking: "medium": fails with AcpRuntimeError: Internal error
• thinking: "high": fails with AcpRuntimeError: Internal error
• model: "sonnet" + thinking: "high": fails with AcpRuntimeError: Internal error

Relevant capability/config-option detail

Current Claude ACP session config options observed/documented are mode, model, and effort when supported by the active model. Current Claude Code docs describe reasoning control as effort, with levels such as low, medium, high, xhigh, and max depending on model support.

The OpenClaw issue thread also notes that published acpx 0.6.1 advertises session/set_config_option capability but does not expose a strict configOptionKeys list. That may leave OpenClaw treating the backend as permissive and forwarding generic keys that the Claude ACP adapter then rejects.

Expected behavior

acpx/OpenClaw should not send unsupported ACP config option IDs to a target adapter.

Possible desired behavior:

1. Filter session/set_config_option calls against the adapter-advertised configOptions.
2. Keep runtime-level timeout handling internal unless the adapter explicitly advertises a compatible timeout config option.
3. Map OpenClaw's generic thinking / reasoning effort control to Claude ACP's advertised effort config option when available.
4. Avoid forwarding generic controls like approval_policy unless the adapter advertises a compatible option.
5. If no compatible advertised config option exists, skip or reject the runtime control before turn execution with a clear client-side error instead of surfacing a generic internal error.

Why this matters

The basic transport path works, so Claude auth/setup does not appear to be the problem. The breakage is specifically in runtime-control/config-option compatibility. Fixing this would make Claude Code through OpenClaw/acpx usable beyond the current clean/model-only workaround.