openclaw - 💡(How to fix) Fix ACPX gateway startup should not depend on live npx adapter resolution [1 comments, 2 participants]

Summary

OpenClaw ACPX became unstable when the ACP adapter command depended on live npx package resolution at gateway runtime. Pinning the ACP adapters locally and pointing OpenClaw at local wrapper scripts fixed gateway startup and allowed both Codex ACP and Claude ACP sessions to pass.

I am filing this as an upstream robustness issue rather than a local npm bug: ACPX should not require live npm registry/DNS/cache behavior during gateway startup or managed ACP session launch.

Environment

• OpenClaw: 2026.4.25 (aa36ee6)
• Install mode: global npm/pnpm package, not git checkout
• OS: macOS 26.4.1, Apple Silicon M4
• Node: v22.22.2
• npm/npx: 10.9.7
• Gateway: LaunchAgent, local loopback gateway
• ACPX plugin: bundled OpenClaw extension

Symptoms Observed

With ACPX configured to use a live adapter command such as:

npx -y @agentclientprotocol/[email protected]

gateway startup became fragile:

• openclaw status --deep initially showed gateway reachable, but enabling ACPX caused slow/unreliable health checks during startup.
• WebSocket health probes timed out / closed with 1006-style symptoms.
• Gateway CPU stayed high for an extended period.
• npm view @agentclientprotocol/[email protected] version hung locally and had to be killed.
• Later, npm view @zed-industries/codex-acp version also hung in the same environment until run outside the restricted/sandboxed path.

The practical failure mode was: ACPX/gateway behavior depended on npm registry/DNS/cache behavior in the live service runtime.

Workaround That Fixed It

I removed live npx from the hot path and pinned both adapters locally.

Claude ACP

Installed locally:

~/.openclaw/acpx/claude-agent-acp-local

Wrapper:

~/.openclaw/acpx/claude-agent-acp-wrapper.mjs

The wrapper launches the local package entrypoint directly:

./claude-agent-acp-local/node_modules/@agentclientprotocol/claude-agent-acp/dist/index.js

and sets:

CLAUDE_MODEL=claude-opus-4-6
CLAUDE_CODE_EXECUTABLE=/opt/homebrew/bin/claude

Codex ACP

The cached @zed-industries/[email protected] initialized but rejected gpt-5.5:

The 'gpt-5.5' model requires a newer version of Codex. Please upgrade to the latest app or CLI and try again.

I installed and pinned:

@zed-industries/[email protected]

under:

~/.openclaw/acpx/codex-acp-local

and updated:

~/.openclaw/acpx/codex-acp-wrapper.mjs

to launch the local native adapter binary directly:

~/.openclaw/acpx/codex-acp-local/node_modules/@zed-industries/codex-acp-darwin-arm64/bin/codex-acp

The wrapper also strips OpenClaw ACP client compatibility args (acp, --verbose) before passing through to codex-acp.

Verification After Local Pinning

After replacing live npx with local pinned wrappers:

• Gateway restarted successfully with ACPX enabled.
• Gateway log showed:

gateway ready (8 plugins: acpx, anthropic, browser, device-pair, memory-core, phone-control, talk-voice, telegram; 8.4s)
embedded acpx runtime backend registered

• openclaw plugins inspect acpx reported:

Status: loaded
Origin: bundled
Version: 2026.4.25
Services:
acpx-runtime

• openclaw health passed.
• openclaw channels status passed.
• Gateway CPU settled back to idle.

ACP session tests

Codex ACP GPT-5.5 test:

openclaw acp client \
  --cwd ~/.openclaw/workspace \
  --server ~/.openclaw/acpx/codex-acp-wrapper.mjs \
  --verbose \
  --server-verbose

Prompt:

Please respond with exactly: ACP_CODEX_OK

Result:

ACP_CODEX_OK

Claude ACP test:

openclaw acp client \
  --cwd ~/.openclaw/workspace \
  --server ~/.openclaw/acpx/claude-agent-acp-wrapper.mjs \
  --verbose \
  --server-verbose

Prompt:

Please respond with exactly: ACP_CLAUDE_OK

Result:

ACP_CLAUDE_OK

Expected Behavior

OpenClaw/ACPX should provide a first-class way to pin/cache/install ACP adapters locally so the gateway does not depend on live npx package resolution during startup or session launch.

Possible acceptable behaviors:

1. ACPX installs adapter dependencies into a plugin-local directory during setup/update.
2. ACPX can auto-install/cache adapters once, then launch local binaries thereafter.
3. openclaw doctor / openclaw acp doctor can validate adapter presence, auth, model compatibility, and network reachability in the same environment used by the gateway.
4. If live npx is used, failures should surface as explicit npm/DNS/registry errors rather than gateway timeouts or high CPU symptoms.

Related Issues

This looks related to, but not exactly the same as:

• #40006 - global npm install does not install ACPX extension subdependencies
• #32380 - ACPX plugin install fallback references an unpublished package
• #44810 - Codex ACP stalls when gateway child environment lacks network/proxy access
• #44198 - manual ACPX/Codex works, OpenClaw ACP integration reports dead runtime
• #60585 - ACP runtime sessions fail with acpx exited with code 1
• #60672 - direct ACPX Codex initializes while OpenClaw spawn exits

Impact

For a long-running OpenClaw gateway, live npx is too fragile as a runtime dependency. It makes ACPX behavior depend on npm registry availability, DNS, cache state, and the launchd/service environment. Local pinning resolved the issue completely in this setup.