openclaw - 💡(How to fix) Fix ACP/acpx: claude-agent-acp Internal error — timeout config option leaks past Codex-only filter in BackendDelegate.setConfigOption [1 comments, 2 participants]

Summary

On v2026.5.6, sessions_spawn(runtime:"acp", agentId:"claude") fails with AcpRuntimeError: Internal error / code=ACP_TURN_FAILED because BackendDelegate.setConfigOption forwards session/set_config_option {key:"timeout", value:"120"} to @agentclientprotocol/[email protected], which rejects it with JSON-RPC -32603 "Unknown config option: timeout".

Steps to reproduce

1. Run OpenClaw 2026.5.6 (commit c97b9f79ec), stock plugin config — plugins.entries.acpx.config.timeoutSeconds defaults to 120 and the schema enforces >= 0.001, so it cannot be unset.
2. Have any agent invoke sessions_spawn({runtime:"acp", agentId:"claude", task:"Reply with OK", runTimeoutSeconds: 60}).
3. ~/.openclaw/logs/gateway.log shows:

   [ws] ⇄ res ✗ agent errorCode=UNAVAILABLE
   errorMessage=AcpRuntimeError: Internal error
   code=ACP_TURN_FAILED

   ~/.openclaw/agents/claude/sessions/<sid>.acp-stream.jsonl ends with:

   {"kind":"lifecycle","phase":"error","data":{"phase":"error","error":"Internal error",...}}

4. Capture the harness's swallowed stderr by adding stderr-tee to ~/.openclaw/acpx/claude-agent-acp-wrapper.mjs (acpx swallows it because the OpenClaw plugin does not pass verbose: true to the runtime). Re-running the spawn produces:

   [STDERR] Error handling request {
     jsonrpc: '2.0', id: 3,
     method: 'session/set_config_option',
     params: { sessionId: '...', configId: 'timeout', value: '120' }
   } { code: -32603, message: 'Internal error',
       data: { details: 'Unknown config option: timeout' } }

5. Direct acpx claude exec "Reply with OK" succeeds in the same shell on the same machine — the ad-hoc CLI session never invokes setConfigOption with key="timeout"; only the gateway's persistent-session plugin path does.

Expected behavior

The Codex code path in the same function already filters this exact key. extensions/acpx/src/runtime.ts (commit c97b9f79ec), BackendDelegate.setConfigOption:

if (isCodexAcpCommand(command)) {
  if (key === "timeout" || key === "timeout_seconds") {
    return;
  }
  // ...
}
await delegate.setConfigOption(input);

@agentclientprotocol/[email protected] rejects the same configId with the same -32603 error as @zed-industries/codex-acp does, so the filter belongs on both code paths. Lifting it out of the Codex-only branch resolves the failure deterministically: applying the diff below to the installed bundle and running the same sessions_spawn call afterwards produces assistant_delta events, lifecycle.phase=end, and claude run completed.

Diff (against c97b9f79ec):

 async setConfigOption(input) {
   const delegate = await this.resolveDelegateForHandle(input.handle);
   const command = await this.resolveCommandForHandle(input.handle);
   const key = input.key.trim().toLowerCase();
+  if (key === "timeout" || key === "timeout_seconds") {
+    return;
+  }
   if (isCodexAcpCommand(command)) {
-    if (key === "timeout" || key === "timeout_seconds") {
-      return;
-    }
     if (key === "model" || key === "thinking" || key === "thought_level" || key === "reasoning_effort") {
       // ...
     }
   }
   await delegate.setConfigOption(input);
 }

Stream comparison on the same call:

Environment for both runs identical: OpenClaw 2026.5.6 c97b9f79ec, @openclaw/acpx 2026.5.6, acpx 0.6.1, @agentclientprotocol/claude-agent-acp 0.32.0, claude CLI OAuth (Pro/Max), macOS 14 arm64, Node v22.22.2.

Related: #53456 (Claude OAuth path closed-as-fixed; closing comment invited fresh reports against v2026.4.24+), #63702 (Codex ACP Internal error closed-as-fixed by acpx 0.6.0; parallel Claude path was not touched).

Actual behavior

sessions_spawn(runtime:"acp", agentId:"claude", task:"...") returns failure to the parent agent. The ACP child session is created (session/new succeeds), then the gateway emits:

[ws] ⇄ res ✗ agent errorCode=UNAVAILABLE
errorMessage=AcpRuntimeError: Internal error
error=AcpRuntimeError: Internal error: code=ACP_TURN_FAILED

The child session's stream file ~/.openclaw/agents/claude/sessions/<sid>.acp-stream.jsonl always ends with the same shape (1623 bytes, identical across attempts):

{"kind":"system_event","contextKey":"acp-spawn:<runId>:start","text":"Started claude session ..."}
{"kind":"lifecycle","phase":"start"}
{"kind":"lifecycle","phase":"error","data":{"phase":"error","error":"Internal error",...}}
{"kind":"system_event","contextKey":"acp-spawn:<runId>:error","text":"claude run failed: Internal error"}

No assistant_delta events, no lifecycle.phase=end. The harness subprocess exits cleanly (exit code=0); no crash. Total elapsed time before error is reported: ~14 s — the failure occurs after session/new and during/right after the first session/set_config_option call from the plugin to the adapter.

After tee'ing the harness stderr (which acpx swallows because the OpenClaw plugin doesn't set verbose: true), the underlying JSON-RPC error is:

code: -32603
message: 'Internal error'
data: { details: 'Unknown config option: timeout' }

The parent agent surfaces this to the user as Background task failed: ACP background task (run <id>). Internal error.

OpenClaw version

OpenClaw 2026.5.6 (commit c97b9f79ec, tag v2026.5.6) @openclaw/acpx 2026.5.6 acpx 0.6.1 @agentclientprotocol/claude-agent-acp 0.32.0 @zed-industries/codex-acp 0.13.0

Operating system

macOS 26.4.1 (build 25E253), arm64 (Apple Silicon) Darwin kernel 25.4.0 Node.js v22.22.2

Install method

Local source checkout, npm-linked into npm-global:

• Source repo: /Users/simeon.ortmueller/openclaw (git checkout, currently detached at tag v2026.5.6, commit c97b9f79ec).
• npm-global symlink: /Users/simeon.ortmueller/.npm-global/lib/node_modules/openclaw → /Users/simeon.ortmueller/openclaw.
• CLI: /Users/simeon.ortmueller/.npm-global/bin/openclaw → …/lib/node_modules/openclaw/openclaw.mjs.
• Gateway runs under launchd label gui/502/ai.openclaw.gateway.

ACPX plugin specifically: locally-built tarball /tmp/openclaw-acpx-2026.5.6.tgz installed via openclaw plugins install, recorded as archive source / spec @openclaw/[email protected]. Stock npm install @openclaw/acpx is currently blocked by the dangerous-code installer ("Shell command execution detected (child_process)"), which forced a local archive build. The buggy code path (BackendDelegate.setConfigOption Codex-only filter) is identical between the locally-built archive and the source tree at extensions/acpx/src/runtime.ts, commit c97b9f79ec — i.e., the bug is present in the upstream source, not introduced by the local build.

Model

For the failing run the model is not invoked — the failure occurs at the session/set_config_option JSON-RPC call between the OpenClaw acpx plugin and the @agentclientprotocol/claude-agent-acp adapter, before any model request is sent. The bug therefore reproduces independent of the resolved model.

For reference (post-patch successful run on the identical setup): the adapter resolved to claude-opus-4-7 (1M context), as reported in the verbose acpx output (Model set to Opus 4.7 (1M context)). Selection comes from the claude CLI's authenticated user (Pro/Max OAuth via ~/.claude/.credentials.json), not from any explicit agentId:"claude" model override in OpenClaw.

Provider / routing chain

Effective request path for sessions_spawn(runtime:"acp", agentId:"claude"):

parent agent (e.g. dev-botti)
  └─ tool call: sessions_spawn { runtime:"acp", agentId:"claude" }
      └─ OpenClaw gateway (ws://127.0.0.1:18789, launchd-managed)
          └─ @openclaw/acpx plugin (BackendDelegate)
              ├─ resolves agentId="claude" via createAgentRegistry overrides
              ├─ spawns wrapper script via Node:
              │     ~/.openclaw/acpx/claude-agent-acp-wrapper.mjs
              │     (which Node-spawns
              │      ~/.openclaw/extensions/acpx/node_modules/
              │      @agentclientprotocol/claude-agent-acp/dist/index.js)
              └─ ACP JSON-RPC over stdio to that adapter
                  └─ adapter would forward to @anthropic-ai/claude-agent-sdk
                      └─ Anthropic API (NEVER REACHED for the bug — failure
                         happens at session/set_config_option, before the
                         first prompt is sent)

No proxies, no Cloudflare/Vercel routers, no third-party gateways involved. The buggy hop is internal: OpenClaw acpx plugin → claude-agent-acp adapter, both running locally as child processes of the gateway.

Additional provider/model setup

Auth (Anthropic / Claude side): Pro/Max OAuth via Claude CLI. Token lives in ~/.claude/.credentials.json (macOS keychain). OpenClaw reads it as profile anthropic:claude-cli (provider claude-cli). No ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN is set in the user shell or the launchd environment of the gateway (verified by tee'ing the wrapper's process.env). The claude-agent-acp adapter discovers credentials via the standard Claude CLI lookup path; auth is not the problem (openclaw doctor reports Headless Claude auth: OK (oauth) and the adapter never returns an auth error in the failing run).

ACPX plugin config (plugins.entries.acpx.config):

{
  "permissionMode": "approve-all",
  "nonInteractivePermissions": "deny",
  "timeoutSeconds": 120
}

timeoutSeconds: 120 is the schema default; the schema enforces >= 0.001, so it cannot be unset to avoid the buggy code path via configuration alone.

Other relevant config flags: hooks.allowRequestSessionKey: true, acp.enabled: true, acp.dispatch.enabled: true, acp.backend: "acpx", acp.defaultAgent: "claude", acp.allowedAgents: ["claude", "codex"].

Wrapper env (captured via stderr-tee instrumentation, names only — values redacted): HOME, USER, PATH, SHELL, TMPDIR, LOGNAME, plus various third-party API tokens unrelated to ACP (OPENAI_API_KEY, GITHUB_TOKEN, NOTION_API_KEY, etc.) and OpenClaw runtime markers (OPENCLAW_GATEWAY_AUTH_TOKEN, OPENCLAW_GATEWAY_PORT, OPENCLAW_LAUNCHD_LABEL, OPENCLAW_NO_RESPAWN). No ANTHROPIC_API_KEY, no CLAUDE_CODE_OAUTH_TOKEN, no XDG_CONFIG_HOME override.

Logs, screenshots, evidence

Gateway error log (the failing run, run id abbcc0c3)

2026-05-06T20:11:04.353+02:00 [agents/auth-profiles] read anthropic credentials from claude cli keychain
2026-05-06T20:11:13.357+02:00 [ws] ⇄ res ✗ agent errorCode=UNAVAILABLE errorMessage=AcpRuntimeError: Internal error runId=abbcc0c3-13d3-4bad-b596-ad85075ffa80 error=AcpRuntimeError: Internal error: code=ACP_TURN_FAILED conn=3f36b026…8fbc id=54c84994…94b5

ACP child-session stream (~/.openclaw/agents/claude/sessions/884c9012-bb98-4f1c-a8ad-aaeb7990dfd7.acp-stream.jsonl, 1623 bytes)

{"ts":"2026-05-06T18:10:58.176Z","runId":"abbcc0c3-…","childSessionKey":"agent:claude:acp:01fe8e91-…","kind":"system_event","contextKey":"acp-spawn:abbcc0c3-…:start","text":"Started claude session ..."}
{"ts":"2026-05-06T18:10:59.088Z","kind":"lifecycle","phase":"start"}
{"ts":"2026-05-06T18:11:13.355Z","kind":"lifecycle","phase":"error","data":{"phase":"error","error":"Internal error",...}}
{"ts":"2026-05-06T18:11:13.355Z","kind":"system_event","contextKey":"acp-spawn:abbcc0c3-…:error","text":"claude run failed: Internal error"}

Harness stderr (key piece of evidence)

acpx swallows the harness stderr because the OpenClaw plugin does not pass verbose: true to the runtime (prompt-turn-…js:2080-2084). Re-running the same call with the wrapper temporarily instrumented to tee stdio[2] to a file produced:

[STDERR] Error handling request {
  jsonrpc: '2.0',
  id: 3,
  method: 'session/set_config_option',
  params: {
    sessionId: '5dcac813-3df3-4b0c-ba85-0bccb9733364',
    configId: 'timeout',
    value: '120'
  }
} {
  code: -32603,
  message: 'Internal error',
  data: { details: 'Unknown config option: timeout' }
}

Earlier in the same wrapper instance (also captured):

[STDERR] Error handling request {
  method: 'session/load',
  params: { sessionId: '2f8498d8-…', cwd: '...', mcpServers: [] }
} {
  code: -32002,
  message: 'Resource not found: 2f8498d8-…',
  data: { uri: '2f8498d8-…' }
}

That second error is a separate stale-session-reuse issue (the plugin tries to session/load an ID the adapter never had); it does not by itself trigger the run-failing error code, but it likely contributes to log noise. Reporting it separately if useful — not addressed in this issue.

After applying the proposed fix

Same sessions_spawn call, post-patch stream ~/.openclaw/agents/claude/sessions/8922f044-2eee-484e-93da-5a66791e5ca8.acp-stream.jsonl (2670 bytes, run id 9619160b-5b26-…):

{"kind":"system_event","contextKey":"acp-spawn:…:start","text":"Started claude session ..."}
{"kind":"lifecycle","phase":"start"}
{"kind":"assistant_delta","delta":"Die"}
{"kind":"assistant_delta","delta":" Claude-ACP-Session wurde erfolgreich gestartet."}
{"kind":"system_event","text":"claude: Die Claude-ACP-Session wurde erfolgreich gestartet."}
{"kind":"lifecycle","phase":"end"}
{"kind":"system_event","text":"claude run completed."}

I can attach the raw .acp-stream.jsonl files (before + after) and the wrapper-stderr capture if useful.

Impact and severity

Scope: Every sessions_spawn(runtime:"acp", agentId:"claude") call on v2026.5.6 fails. Reproduces deterministically; not flaky. Independent of agent identity (we observed it from dev-botti, but the failing path is in the shared plugin runtime).

No user-side workaround: plugins.entries.acpx.config.timeoutSeconds cannot be unset (schema enforces >= 0.001). Removing the value via openclaw config unset returns Config path not found because 120 is the schema default. The only working workaround is editing the installed plugin bundle (~/.openclaw/extensions/acpx/{index,register.runtime}.js) directly — not appropriate for non-developer users.

Functional impact: Claude ACP child sessions are unusable in OpenClaw. Native Claude (non-ACP) still works. Direct acpx claude exec from the shell also still works (different code path). The break is specifically the OpenClaw-plugin-orchestrated ACP flow that the sessions_spawn tool relies on.

Severity (subjective): High for any setup that relies on the ACP harness for Claude — coding-agent thread spawning, ACP-routed subagents. Not a crash, no data loss, no security implication.

Additional information

• The closing comment on #53456 (clawsweeper bot, 2026-04-26) stated: "if users still see auth failures on v2026.4.24 or newer, handle that as a fresh current-version bug with exact OpenClaw, acpx, Claude ACP adapter, Claude Code versions, and logs." This report follows that guidance.
• The closing comment on #63702 referenced acpx 0.6.0's waitForSessionUpdatesIdle as the fix. That addressed a separate timing bug; the timeout-config-option mismatch documented here is a distinct code path and was not touched by the Codex fix.
• Adjacent observation, not addressed in this issue: prepareIsolatedCodexHome in the same module creates an isolated CODEX_HOME (~/.openclaw/acpx/codex-home/) but never writes an auth.json there, while overriding CODEX_HOME env at wrapper spawn. This causes @zed-industries/codex-acp to advertise [chatgpt, codex-api-key, openai-api-key] and report no matching credentials found, blocking Codex ACP regardless of whether OpenClaw has a valid openai-codex OAuth profile. The codex-auth-bridge.test.ts tests appear to assert auth.json is not present, suggesting the bridge is intentionally a no-op rather than incomplete. Happy to file as a separate issue/feature-request once this one is triaged — unclear whether the design intent is to bridge OAuth into the isolated home or to stop isolating CODEX_HOME entirely.
• Wrapper instrumentation used to capture the harness stderr was a non-destructive tee (kept stdio.stderr=pipe, forwarded chunks to process.stderr in addition to a log file). Restored to the plugin-generated original after evidence capture.