openclaw - ✅(Solved) Fix [Bug] 2026.3.22 npm install: ACPX metadata present, ACPX plugin missing, and install resolves to skill [4 pull requests, 6 comments, 6 participants]

evmlionel · 2026-03-23T12:31:02Z

[openclaw] After upgrading a global npm install from 2026.3.14 to 2026.3.22 , an existing ACP setup using acpx could no longer be configured cleanly. In this e… After upgrading a global npm install from `2026.3.14` to `2026.3.22`, an existing ACP setup using `acpx` could no longer be configured cleanly. In this environment, the installed `2026.3.22` package still contains ACPX manifest metadata, but ACPX is not discoverable as a plugin and is not installable through either the bare or scoped plugin install paths. Existing config that references `acpx` then fails validation. This looks like a mismatch between the published package contents and the ACPX plugin/install surface, not just local config drift. # PR #52404: ACP: fully rename acpx plugin - Repository: openclaw/openclaw - Author: osolmaz - State: closed | merged: True - Link: https://github.com/openclaw/openclaw/pull/52404 ## Description (problem / solution / changelog) ## Summary - Problem: ACP used `acpx` for the runtime CLI, plugin id, docs, and package naming in a way that mixed runtime identity with plugin identity. - Why it matters: contributors and operators were conflating the `acpx` CLI with the OpenClaw plugin package and config key. - What changed: fully aligned the plugin to `acpx-plugin` across package name, plugin id, backend id, config/docs/examples, tests, and the extension directory name. - What did NOT change (scope boundary): the underlying runtime command remains `acpx`. ## Change Type (select all) - [x] Refactor required for the fix - [x] Docs ## Scope (select all touched areas) - [x] Gateway / orchestration - [x] Skills / tool execution - [x] Memory / storage - [x] Integrations - [x] API / contracts - [x] UI / DX ## Linked Issue/PR - Closes # - Related # ## User-visible / Behavior Changes - The ACP runtime plugin is now `@openclaw/acpx-plugin`. - The plugin/backend/config id is now `acpx-plugin`. - Local source installs now use `extensions/acpx-plugin`. - The underlying `acpx` CLI/binary name is unchanged. ## Security Impact (required) - New permissions/capabilities? (`Yes/No`) No - Secrets/tokens handling changed? (`Yes/No`) No - New/changed network calls? (`Yes/No`) No - Command/tool execution surface changed? (`Yes/No`) No - Data access scope changed? (`Yes/No`) No - If any `Yes`, explain risk + mitigation: ## Repro + Verification ### Environment - OS: macOS - Runtime/container: Node 22 + pnpm - Model/provider: n/a - Integration/channel (if any): ACP runtime plugin - Relevant config (redacted): ACP enabled with `acpx-plugin` backend ### Steps 1. Rename the ACP plugin package, plugin id, backend id, docs, and extension path from `acpx` to `acpx-plugin`. 2. Update ACP/runtime/config/install resolution and test fixtures to match the new id. 3. Build and run focused ACP/plugin verification. ### Expected - ACP/plugin discovery, auto-enable, session metadata, install hints, and docs consistently use `acpx-plugin`. - The runtime still invokes the `acpx` CLI. ### Actual - Matches expected after the rename. ## Evidence - [x] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) ## Human Verification (required) What you personally verified (not just CI), and how: - Verified scenarios: focused ACP/plugin tests passed; final branch tip passed `pnpm build`. - Edge cases checked: install hints for local path vs scoped package, session/backend identifier text, bundled metadata copy paths, runtime/backend registry lookups. - What you did **not** verify: live ACP runtime against a real external harness. ## Review Conversations - [x] I replied to or resolved every bot review conversation I addressed in this PR. - [x] I left unresolved only the conversations that still need reviewer or maintainer judgment. ## Compatibility / Migration - Backward compatible? (`Yes/No`) No - Config/env changes? (`Yes/No`) Yes - Migration needed? (`Yes/No`) Yes - If yes, exact upgrade steps: - Rename ACP backend/config references from `acpx` to `acpx-plugin`. - Rename plugin entry keys from `plugins.entries.acpx` to `plugins.entries.acpx-plugin`. - Use `@openclaw/acpx-plugin` or `./extensions/acpx-plugin` for installs. ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: revert this PR or restore the prior `acpx` plugin id/package/path set. - Files/config to restore: ACP plugin metadata under `extensions/acpx-plugin`, ACP config/backend references, install hints/docs. - Known bad symptoms reviewers should watch for: ACP backend not found, auto-enable missing the plugin, docs/install commands referencing the old id. ## Risks and Mitigations - Risk: some config or tests may still assume the old `acpx` plugin id or extension path. - Mitigation: updated ACP/plugin tests, docs, install hints, auto-enable logic, bundled metadata tests, and verified with `pnpm build`. ## Changed files - `AGENTS.md` (modified, +1/-0) - `docs/tools/acp-agents.md` (modified, +2/-2) - `extensi

openclaw2026-03-23 12:31:02

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#52831•Fetched 2026-04-08 01:18:44

View on GitHub

Comments

Participants

Timeline

Reactions

Author

Participants

Timeline (top)

commented ×6subscribed ×3closed ×2locked ×1

After upgrading a global npm install from 2026.3.14 to 2026.3.22, an existing ACP setup using acpx could no longer be configured cleanly.

In this environment, the installed 2026.3.22 package still contains ACPX manifest metadata, but ACPX is not discoverable as a plugin and is not installable through either the bare or scoped plugin install paths. Existing config that references acpx then fails validation.

This looks like a mismatch between the published package contents and the ACPX plugin/install surface, not just local config drift.

Error Message

npm i -g openclaw@latest --no-fund --no-audit --loglevel=error 3. If the ACPX install or naming changed, the config error points to the correct migration path.

Root Cause

After upgrading a global npm install from 2026.3.14 to 2026.3.22, an existing ACP setup using acpx could no longer be configured cleanly.

This looks like a mismatch between the published package contents and the ACPX plugin/install surface, not just local config drift.

Code Example

openclaw update --yes --json

---

npm i -g openclaw@latest --no-fund --no-audit --loglevel=error

---

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "codex"
  },
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true
      }
    },
    "allow": ["acpx"]
  }
}

---

openclaw plugins list
openclaw plugins inspect acpx
openclaw plugins install acpx
openclaw plugins install @openclaw/acpx
openclaw status

---

Plugin not found: acpx

---

Resolving clawhub:acpx…
   "acpx" is a skill. Use "openclaw skills install acpx" instead.

---

Resolving clawhub:@openclaw/acpx…
   Downloading @openclaw/acpx…
   Package not found on npm: @openclaw/acpx. See https://docs.openclaw.ai/tools/plugin for installable plugins.
   Also not a valid hook pack: Package not found on npm: @openclaw/acpx. See https://docs.openclaw.ai/tools/plugin for installable plugins.

---

Invalid config at ~/.openclaw/openclaw.json:
   - plugins.allow: plugin not found: acpx

---

node -e 'const fs=require("fs"); const p="<OPENCLAW_ROOT>/dist/manifest-registry-D5E7Gxgl.js"; const s=fs.readFileSync(p,"utf8"); console.log(/packageName: "@openclaw\\/acpx"/.test(s), /dirName: "acpx"/.test(s));'

---

true true

---

node -e 'const fs=require("fs"); const path=require("path"); const root="<OPENCLAW_ROOT>/dist/extensions"; console.log(fs.existsSync(path.join(root,"acpx")), fs.readdirSync(root).includes("acpx"));'

---

false false

RAW_BUFFERClick to expand / collapse

Bug type

Regression (worked before, now fails)

Summary

After upgrading a global npm install from 2026.3.14 to 2026.3.22, an existing ACP setup using acpx could no longer be configured cleanly.

This looks like a mismatch between the published package contents and the ACPX plugin/install surface, not just local config drift.

Environment

OpenClaw: 2026.3.22
Previous version: 2026.3.14
OS: Ubuntu 25.10
Node: 24.14.0
Install method: global npm install

Upgrade path used:

openclaw update --yes --json

which ran:

npm i -g openclaw@latest --no-fund --no-audit --loglevel=error

Existing config before upgrade

This ACP config was accepted on 2026.3.14:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "codex"
  },
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true
      }
    },
    "allow": ["acpx"]
  }
}

Repro

After upgrading to 2026.3.22, run:

openclaw plugins list
openclaw plugins inspect acpx
openclaw plugins install acpx
openclaw plugins install @openclaw/acpx
openclaw status

Expected

One of these should work cleanly:

acpx is still bundled or discoverable, and the old config continues to work.
acpx is no longer bundled, but there is a supported install path that succeeds.
If the ACPX install or naming changed, the config error points to the correct migration path.

Actual

acpx does not appear in openclaw plugins list.
openclaw plugins inspect acpx says:
```
Plugin not found: acpx
```

openclaw plugins install acpx resolves to a skill instead of a plugin:

Resolving clawhub:acpx…
"acpx" is a skill. Use "openclaw skills install acpx" instead.

openclaw plugins install @openclaw/acpx also fails:

Resolving clawhub:@openclaw/acpx…
Downloading @openclaw/acpx…
Package not found on npm: @openclaw/acpx. See https://docs.openclaw.ai/tools/plugin for installable plugins.
Also not a valid hook pack: Package not found on npm: @openclaw/acpx. See https://docs.openclaw.ai/tools/plugin for installable plugins.

If the old ACPX config is left in place, config validation fails:

Invalid config at ~/.openclaw/openclaw.json:
- plugins.allow: plugin not found: acpx

Evidence

The installed package still appears to know about ACPX in metadata:

node -e 'const fs=require("fs"); const p="<OPENCLAW_ROOT>/dist/manifest-registry-D5E7Gxgl.js"; const s=fs.readFileSync(p,"utf8"); console.log(/packageName: "@openclaw\\/acpx"/.test(s), /dirName: "acpx"/.test(s));'

Output:

true true

But the ACPX extension directory is missing from the installed package:

node -e 'const fs=require("fs"); const path=require("path"); const root="<OPENCLAW_ROOT>/dist/extensions"; console.log(fs.existsSync(path.join(root,"acpx")), fs.readdirSync(root).includes("acpx"));'

Output:

false false

So in this environment the package looks internally inconsistent:

ACPX metadata present
ACPX extension files absent
ACPX not discoverable via openclaw plugins list
ACPX not installable via openclaw plugins install acpx
ACPX not installable via openclaw plugins install @openclaw/acpx

Why this looks release-related

I checked the v2026.3.22 release notes and recent ACPX PRs:

Release: https://github.com/openclaw/openclaw/releases/tag/v2026.3.22
ACP rename to acpx-plugin: https://github.com/openclaw/openclaw/pull/52404
ACP rename reverted back to acpx before release: https://github.com/openclaw/openclaw/pull/52456
Missing built-in extension entry handling fix: https://github.com/openclaw/openclaw/pull/52491
ACPX pin alignment: https://github.com/openclaw/openclaw/pull/52730

Given that #52456 reverted the naming change before the 2026.3.22 release commit, this does not look like a normal acpx -> acpx-plugin migration case.

Possibly related packaging regressions in the same release line:

#52808 missing dist/control-ui/ in 2026.3.22: https://github.com/openclaw/openclaw/issues/52808
#52813 plugin disappearance on 2026.3.22: https://github.com/openclaw/openclaw/issues/52813

Current workaround

To restore a clean running setup locally, I had to:

disable ACP
remove stale plugins.entries.acpx config
remove "acpx" from plugins.allow

That restores a healthy gateway, but ACP/Codex is unavailable.

Questions

Is ACPX supposed to be bundled or discoverable in the published 2026.3.22 npm package?
If yes, is the published package missing the ACPX extension files?
If no, what is the supported install path for ACPX on 2026.3.22?
Why does openclaw plugins install acpx resolve to a skill instead of the ACP plugin?
Should existing config that references:
- acp.backend = "acpx"
- plugins.entries.acpx
- plugins.allow: ["acpx"] fail with a clearer migration or install hint?

Impact

Breaks existing ACP setups on upgrade
Prevents clean ACP/Codex setup after upgrade
Can invalidate config if old ACPX references remain
Forces users onto non-ACP fallbacks even when ACP previously worked

extent analysis

Fix Plan

To resolve the issue with ACPX not being discoverable or installable after upgrading to 2026.3.22, follow these steps:

Check the ACPX plugin installation:
- Verify if the ACPX plugin is correctly installed and configured.
- If not, try installing it using the correct installation path.
Update the configuration:
- Remove the stale plugins.entries.acpx config.
- Remove "acpx" from plugins.allow.
- Update acp.backend to use the correct plugin name if it has changed.
Verify the ACPX extension files:
- Check if the ACPX extension files are present in the installed package.
- If not, try reinstalling the package or checking for any packaging regressions.

Example configuration updates:

{
  "acp": {
    "enabled": true,
    "backend": "acpx-plugin", // Update the backend to the correct plugin name
    "defaultAgent": "codex"
  },
  "plugins": {
    "entries": {
      // Remove the stale acpx config
      // "acpx": {
      //   "enabled": true
      // }
    },
    "allow": [
      // Remove "acpx" from the allow list
      // "acpx"
    ]
  }
}

Verification

To verify that the fix worked:

Run openclaw plugins list to check if the ACPX plugin is discoverable.
Run openclaw plugins inspect acpx to check if the ACPX plugin is correctly installed.
Run openclaw status to check if the configuration is valid and the ACPX plugin is enabled.

Extra Tips

Always check the release notes and recent PRs for any changes or regressions that may affect the ACPX plugin.
Verify the packaging and installation of the ACPX plugin to ensure it is correctly installed and configured.
Update the configuration to use the correct plugin name and remove any stale config references.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#dependency error #configuration error #environment variable #network issue #logging issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

openclaw - ✅(Solved) Fix [Bug] 2026.3.22 npm install: ACPX metadata present, ACPX plugin missing, and install resolves to skill [4 pull requests, 6 comments, 6 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fix / Workaround

Current workaround

PR fix notes

PR #52404: ACP: fully rename acpx plugin

Description (problem / solution / changelog)

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Changed files

PR #52456: ACP: revert acpx-plugin package naming

Description (problem / solution / changelog)

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Changed files

PR #52491: fix(plugins): distinguish missing entry file from path-escape security violation

Description (problem / solution / changelog)

Problem

Root cause

User impact

Fix

How to verify

Tests

Changed files

PR #52730: ACPX: align pinned runtime version

Description (problem / solution / changelog)

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Changed files

Code Example

Bug type