ACPX runtime fails on nix-openclaw immutable store (plugin tries to write node_modules under /nix/store)

[kimptoc]

Summary (provided by Codex)

When ACPX runtime is enabled in nix-openclaw, the plugin loads but ACP sessions fail with:

sessions_spawn runtime=acp → ACP runtime backend is currently unavailable. Try again in a moment.

Gateway logs show ACPX trying to create/install plugin-local dependencies inside /nix/store, which is read-only.

Environment

• nix-openclaw on Linux (Home Manager)
• OpenClaw gateway package from nix store
• ACPX runtime plugin enabled

Actual behavior

Logs include errors like:

• acpx local binary unavailable ... running plugin-local install
• acpx runtime setup failed ... ENOENT ... mkdir '/nix/store/.../extensions/acpx/node_modules/acpx'

As a result, ACP runtime backend never becomes available.

Expected behavior

On Nix (immutable package paths), ACPX should start without attempting writes to plugin directory under /nix/store.

Repro

1. Enable ACPX runtime plugin in nix-openclaw config.
2. Rebuild/switch and restart gateway.
3. Attempt sessions_spawn runtime=acp.
4. Observe runtime unavailable + ENOENT in logs.

Suggested fix direction

• Treat extension directory as read-only in packaged builds.
• Resolve acpx binary from packaged dependency path (or configurable command) instead of plugin-local install.
• If write/install is required, use a writable runtime cache path ($XDG_STATE_HOME or similar), not plugin install dir.
• Add explicit detection/logging for immutable store paths and skip install fallback.

How it could work upstream (design): package acpx with gateway and have the ACPX plugin use that binary directly first, with plugin-local install only as a non-Nix fallback.

[kimptoc]

Quick follow-up from testing a patched version:

We confirmed two independent failure modes that can look similar from the user side.

1. Runtime/backend bootstrap issue on Nix (this issue):
   ACPX backend can fail to come up in immutable /nix/store layouts if plugin-local install/write paths are assumed.

2. Policy gate issue (separate from backend health):
   Even when ACPX logs runtime backend ready, ACP turns can still fail if:

   • acp.dispatch.enabled=false

Observed error in that case:

• ACP dispatch is disabled by policy (acp.dispatch.enabled=false)
• code: ACP_DISPATCH_DISABLED

After setting:

• acp.enabled=true
• acp.dispatch.enabled=true
• acp.backend=acpx

…the policy error disappeared, and ACP dispatch proceeded.

So backend readiness and dispatch policy are distinct gates; both need to be satisfied.

[kimptoc]

NixOS system requirement for ACP Codex runtime:

npx @zed-industries/codex-acp is a dynamically linked binary. On NixOS, ACP may fail unless nix-ld is enabled and
required runtime libs are provided.

Working configuration:

programs.nix-ld = {
  enable = true;
  libraries = with pkgs; [
    stdenv.cc.cc
    libcap
    xz
    zlib
    openssl
  ];
};

Then:

1. sudo nixos-rebuild switch
2. systemctl --user restart openclaw-gateway

Typical failure symptoms without this:

- Nix stub-ld error for dynamic executable
- missing .so errors such as:
    - libcap.so.2
    - liblzma.so.5
    - libssl.so.3 / libcrypto.so.3
    - libz.so.1

[kimptoc]

Additional Nix/headless finding:

Even when ACPX + agent command are healthy, ACP turns via OpenClaw gateway can still fail with generic ACP_TURN_FAILED
while direct acpx <agent> exec works.

In our case, stabilizing ACPX plugin runtime settings resolved this class of failure:

plugins.entries.acpx = {
  enabled = true;
  config = {
    permissionMode = "approve-all";
    nonInteractivePermissions = "fail";
    queueOwnerTtlSeconds = 300;
    timeoutSeconds = 300;
  };
};

Observed behavior before tuning:

- Gateway ACP turn: generic internal ACP_TURN_FAILED
- Direct CLI (acpx claude exec ...): works

Suggestion:

- document recommended ACPX runtime defaults for non-interactive gateway usage
- or ship safer defaults (especially queue-owner TTL) for server/headless mode
- include underlying ACPX error details in gateway logs instead of only generic wrapper errors

[cattyclaw-bot]

Update for anyone hitting this on NixOS:

Current failures like ACP_TURN_FAILED / AcpRuntimeError: Internal error with Claude ACP are not just local flake config issues.

We reproduced the underlying ACPX error directly outside OpenClaw on this setup:

• RUNTIME / QUEUE_RUNTIME_PROMPT_FAILED
• acp.data.details: "Query closed before response received"
• session metadata shows lastAgentDisconnectReason: connection_close

Upstream tracking:

• zed-industries/claude-agent-acp#362 (same error signature): Claude Code ACP Agent: prompt mode fails with "Query closed before response received" agentclientprotocol/claude-agent-acp#362
• duplicate: Claude Code ACP Agent: prompt mode fails with "Query closed before response received" agentclientprotocol/claude-agent-acp#361
• openclaw/acpx#29 (same session disconnect pattern): Claude ACP agent fails: all sessions end with 0 turns, agent disconnects after ~3s acpx#29

Practical status right now:

• acpx claude exec ... (one-shot) can work
• acpx claude prompt --session ... is currently unreliable/failing in this upstream path

So this appears to be an upstream ACPX/Claude session-lifecycle issue; nix-openclaw can document/work around it, but likely cannot fully fix it alone.

[kimptoc]

In better news, the Codex ACP agent works ok. :)

[cattyclaw-bot]

Working overlay workaround (still needed as of 2026.3.3 / acpx 0.1.15)

The root cause is still present: the upstream nix-openclaw package bundles acpx inside node_modules/.pnpm/acpx@*/ but doesn't wire it into extensions/acpx/ where the gateway's ACPX plugin expects to find the binary. On startup the plugin tries to install it locally, which fails because /nix/store is read-only.

The workaround is a Nix overlay that symlinks acpx from pnpm into the extensions directory at build time. Here's a complete working flake.nix showing where everything goes — the overlay, the package reference, and the required ACP + plugin config:

{
  description = "OpenClaw local config";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
    home-manager = {
      url = "github:nix-community/home-manager/release-25.11";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    nix-openclaw.url = "github:openclaw/nix-openclaw";
  };

  outputs = { nixpkgs, home-manager, nix-openclaw, ... }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs {
        inherit system;
        overlays = [
          # 1. The standard nix-openclaw overlay (provides openclaw-gateway)
          nix-openclaw.overlays.default

          # 2. ACPX fix overlay — symlinks acpx binary into extensions/
          #    so the plugin finds it without writing to /nix/store.
          #    See: https://github.com/openclaw/nix-openclaw/issues/73
          (final: prev: {
            openclaw-gateway-acpx-fixed = prev.openclaw-gateway.overrideAttrs (old: {
              installPhase = ''
                ${old.installPhase}
                acpx_pkg="$(find "$out/lib/openclaw/node_modules/.pnpm" \
                  -path "*/acpx@*/node_modules/acpx" -print | head -n 1)"
                if [ -n "$acpx_pkg" ]; then
                  mkdir -p "$out/lib/openclaw/extensions/acpx/node_modules/.bin"
                  if [ ! -e "$out/lib/openclaw/extensions/acpx/node_modules/acpx" ]; then
                    ln -s "$acpx_pkg" \
                      "$out/lib/openclaw/extensions/acpx/node_modules/acpx"
                  fi
                  if [ ! -e "$out/lib/openclaw/extensions/acpx/node_modules/.bin/acpx" ]; then
                    ln -s "$acpx_pkg/dist/cli.js" \
                      "$out/lib/openclaw/extensions/acpx/node_modules/.bin/acpx"
                  fi
                else
                  echo "warning: acpx not found in node_modules/.pnpm" >&2
                fi
              '';
            });
          })
        ];
      };
    in {
      homeConfigurations.youruser = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [
          nix-openclaw.homeManagerModules.openclaw
          {
            # ... your home-manager config ...

            programs.openclaw = {
              enable = true;
              # 3. Use the patched package instead of the default
              package = pkgs.openclaw-gateway-acpx-fixed;
              config = {
                # ... your other config (models, channels, etc.) ...

                # 4. Enable ACP with acpx backend
                acp = {
                  enabled = true;
                  dispatch.enabled = true;  # both gates must be true
                  backend = "acpx";
                  defaultAgent = "codex";
                  allowedAgents = [ "codex" "claude" ];
                };

                # 5. ACPX plugin settings for headless/gateway use
                plugins.entries.acpx = {
                  enabled = true;
                  config = {
                    permissionMode = "approve-all";
                    nonInteractivePermissions = "deny";  # NOT "fail" — see note below
                    queueOwnerTtlSeconds = 300;
                    timeoutSeconds = 300;
                  };
                };
              };
            };
          }
        ];
      };
    };
}

Important: nonInteractivePermissions must be "deny", not "fail".
Even with permissionMode: "approve-all" (which passes --approve-all to acpx), some agent SDKs (notably Claude's) can still hit permission prompts in edge paths. With "fail", these cause hard errors (ACP_TURN_FAILED). With "deny", they're gracefully skipped and the turn completes.

After applying:

cd /path/to/your/flake
nix run home-manager -- switch --flake .#youruser
systemctl --user restart openclaw-gateway

You should see in the gateway log (/tmp/openclaw/openclaw-gateway.log):

[plugins] acpx runtime backend registered (command: /nix/store/…/extensions/acpx/node_modules/.bin/acpx, expectedVersion: 0.1.15, pluginLocalInstall: enabled)
[plugins] acpx runtime backend ready

Also required on NixOS (as noted in earlier comments): programs.nix-ld must be enabled with the required libraries, otherwise the dynamically-linked codex binary will fail.

Upstream fixes:
The session-lifecycle issues previously reported in zed-industries/claude-agent-acp#361 and #362 ("Query closed before response received" / connection_close in prompt mode) have been fixed upstream and are resolved in the current acpx 0.1.15 + claude-agent-acp versions. Claude ACP tool use (file ops, etc.) now works reliably through the gateway. openclaw/acpx#29 remains open but may be a separate manifestation.

Verified working (2026.3.3):

• acpx codex exec "hello" — works end-to-end through gateway
• acpx claude exec "hello" — works when Anthropic API key has credit
• Claude ACP tool use (file ops via mkdir, echo) — confirmed working with the "deny" fix