openclaw - 💡(How to fix) Fix acpx: `sessions_spawn timeoutSeconds` mistranslated to a config option the claude-agent-acp backend rejects

Repo: openclaw/openclaw Component: @openclaw/acpx (ACP harness) Found: 2026-05-11 while bringing up Claude Code via ACP on macOS.

Summary

When sessions_spawn is called with runtime: "acp", agentId: "claude", and timeoutSeconds: N, the runtime forwards that as a JSON-RPC session/set_config_option(configId: "timeout") call to the claude-agent-acp backend. @agentclientprotocol/[email protected] does not understand a config option with that id and rejects the request, which unwinds the connection and surfaces as ACP_TURN_FAILED to the caller. (The real reason is hidden by the lossy toAcpRuntimeError wrapping — see companion bug report.)

End-user impact: callers must omit timeoutSeconds for the claude runtime. There is no documented warning that this option is unsupported on this harness; the failure is opaque and hard to attribute without reading the raw stream log.

Reproduction

await sessions_spawn({
  runtime: "acp",
  agentId: "claude",
  task: "echo hi",
  timeoutSeconds: 60,   // ← this is what breaks
});
// → ACP_TURN_FAILED: Internal error

Drop timeoutSeconds and the spawn succeeds.

Suggested fix

Either:

1. Drop timeoutSeconds from the outbound config-option translation for the claude runtime (the backend doesn't support it), and enforce the timeout in-process on the OpenClaw side instead.
2. Surface a typed unsupported-option error from the runtime when the backend rejects a config option, so the caller can omit the option and retry — instead of unwinding the whole session.

Option 1 matches operator expectations better. Option 2 is a more general fix that would benefit other ACP backends with different config-option support.

Workaround until fixed

Omit timeoutSeconds when spawning the claude ACP runtime. (Document in MEMORY.md so the next agent operator doesn't trip on it.)

Environment

• OpenClaw 2026.5.7
• macOS 15 (arm64), Node 24.15.0
• @openclaw/acpx from npm ~/.openclaw/npm/node_modules/@openclaw/acpx/
• @agentclientprotocol/[email protected]