From cd443d412893ec1bcc635e8804467e48e9dc8d9b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 3 Mar 2026 02:33:53 +0000
Subject: [PATCH] fix(acp): use publishable acpx install hint (#32413) (thanks
 @0xtangping)

---
 CHANGELOG.md                                  |  1 +
 .../commands-acp/shared.install-hint.test.ts  | 48 +++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 src/auto-reply/reply/commands-acp/shared.install-hint.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa5389f771c..bd0af9155b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -125,6 +125,7 @@ Docs: https://docs.openclaw.ai
 - Plugins/hardlink install compatibility: allow bundled plugin manifests and entry files to load when installed via hardlink-based package managers (`pnpm`, `bun`) while keeping hardlink rejection enabled for non-bundled plugin sources. (#32119) Fixes #28175, #28404, #29455. Thanks @markfietje.
 - Web UI/config form: support SecretInput string-or-secret-ref unions in map `additionalProperties`, so provider API key fields stay editable instead of being marked unsupported. (#31866) Thanks @ningding97.
 - Plugins/install diagnostics: reject legacy plugin package shapes without `openclaw.extensions` and return an explicit upgrade hint with troubleshooting docs for repackaging. (#32055) Thanks @liuxiaopai-ai.
+- ACP/install hint reliability: update default acpx install guidance to use publishable package name `acpx` (instead of unpublished `@openclaw/acpx`) in runtime hints and docs. (#32413) Thanks @0xtangping.
 - Plugins/install fallback safety: resolve bare install specs to bundled plugin ids before npm lookup (for example `diffs` -> bundled `@openclaw/diffs`), keep npm fallback limited to true package-not-found errors, and continue rejecting non-plugin npm packages that fail manifest validation. (#32096) Thanks @scoootscooob.
 - Browser/default profile selection: default `browser.defaultProfile` behavior now prefers `openclaw` (managed standalone CDP) when no explicit default is configured, while still auto-provisioning the `chrome` relay profile for explicit opt-in use. (#32031) Fixes #31907. Thanks @liuxiaopai-ai.
 - Doctor/local memory provider checks: stop false-positive local-provider warnings when `provider=local` and no explicit `modelPath` is set by honoring default local model fallback while still warning when gateway probe reports local embeddings not ready. (#32014) Fixes #31998. Thanks @adhishthite.
diff --git a/src/auto-reply/reply/commands-acp/shared.install-hint.test.ts b/src/auto-reply/reply/commands-acp/shared.install-hint.test.ts
new file mode 100644
index 00000000000..5a400fb0092
--- /dev/null
+++ b/src/auto-reply/reply/commands-acp/shared.install-hint.test.ts
@@ -0,0 +1,48 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../../../config/config.js";
+import { resolveAcpInstallCommandHint } from "./shared.js";
+
+describe("resolveAcpInstallCommandHint", () => {
+  const originalCwd = process.cwd();
+  let tempDir = "";
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-acp-install-hint-"));
+  });
+
+  afterEach(async () => {
+    process.chdir(originalCwd);
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns configured install command override", () => {
+    const cfg = {
+      acp: {
+        runtime: {
+          installCommand: "custom install command",
+        },
+      },
+    } as OpenClawConfig;
+    expect(resolveAcpInstallCommandHint(cfg)).toBe("custom install command");
+  });
+
+  it("uses publishable acpx npm package when local extension path is absent", () => {
+    process.chdir(tempDir);
+    const cfg = {} as OpenClawConfig;
+    expect(resolveAcpInstallCommandHint(cfg)).toBe("openclaw plugins install acpx");
+  });
+
+  it("returns generic backend message for non-acpx backends", () => {
+    const cfg = {
+      acp: {
+        backend: "custom-backend",
+      },
+    } as OpenClawConfig;
+    expect(resolveAcpInstallCommandHint(cfg)).toContain('backend "custom-backend"');
+  });
+});