Exact npm version pinning already lives in `npmSpec`, for example

`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Pair that with

`expectedIntegrity` when you want update flows to fail closed if the fetched

npm artifact no longer matches the pinned release. Interactive onboarding only

offers npm install choices from trusted catalog metadata when `npmSpec` is an

exact version and `expectedIntegrity` is present; otherwise it falls back to a

local source or skip.

npm artifact no longer matches the pinned release. Interactive onboarding

offers trusted registry npm specs, including bare package names and dist-tags.

When `expectedIntegrity` is present, install/update flows enforce it; when it

is omitted, the registry resolution is recorded without an integrity pin.

Channel plugins should provide `openclaw.setupEntry` when status, channel list,

or SecretRef scans need to identify configured accounts without loading the full

surfaces. If your plugin exposes provider auth choices or channel setup/catalog

metadata before runtime loads, onboarding can show that choice, prompt for npm

vs local install, install or enable the plugin, then continue the selected

flow. Npm onboarding choices require trusted catalog metadata with an exact

`npmSpec` version and `expectedIntegrity`; unpinned package names and dist-tags

are not offered for automatic onboarding installs. Keep the "what to show"

metadata in `openclaw.plugin.json` and the "how to install it" metadata in

`package.json`.

flow. Npm onboarding choices require trusted catalog metadata with a registry

`npmSpec`; exact versions and `expectedIntegrity` are optional pins. If

`expectedIntegrity` is present, install/update flows enforce it. Keep the "what

to show" metadata in `openclaw.plugin.json` and the "how to install it"

metadata in `package.json`.

If `minHostVersion` is set, install and manifest-registry loading both enforce

it. Older hosts skip the plugin; invalid version strings are rejected.

{

"entries": [

{

"name": "@wecom/wecom-openclaw-plugin",

"description": "OpenClaw WeCom channel plugin by the Tencent WeCom team.",

"source": "external",

"kind": "channel",

"openclaw": {

"channel": {

"id": "wecom",

"label": "WeCom",

"selectionLabel": "WeCom (Enterprise WeChat)",

"detailLabel": "WeCom",

"docsPath": "/plugins/community#wecom",

"docsLabel": "wecom",

"blurb": "Enterprise WeChat bot and conversation channel.",

"aliases": ["qywx", "wework", "enterprise-wechat"],

"order": 45

},

"install": {

"npmSpec": "@wecom/wecom-openclaw-plugin",

"defaultChoice": "npm"

}

}

}

]

}

import fs from "node:fs";

import path from "node:path";

import { pathToFileURL } from "node:url";

import officialExternalChannelCatalog from "./lib/official-external-channel-catalog.json" with { type: "json" };

import { isRecord, trimString } from "./lib/record-shared.mjs";

import { writeTextFileIfChanged } from "./runtime-postbuild-shared.mjs";

return null;

}

const defaultChoice = trimString(install.defaultChoice);

const minHostVersion = trimString(install.minHostVersion);

const expectedIntegrity = trimString(install.expectedIntegrity);

return {

npmSpec,

...(defaultChoice === "npm" || defaultChoice === "local" ? { defaultChoice } : {}),

...(minHostVersion ? { minHostVersion } : {}),

...(expectedIntegrity ? { expectedIntegrity } : {}),

...(install.allowInvalidConfigRecovery === true ? { allowInvalidConfigRecovery: true } : {}),

};

}

export function buildOfficialChannelCatalog(params = {}) {

const repoRoot = params.cwd ?? params.repoRoot ?? process.cwd();

const extensionsRoot = path.join(repoRoot, "extensions");

const entries = [];

const entries = Array.isArray(officialExternalChannelCatalog.entries)

? [...officialExternalChannelCatalog.entries]

: [];

if (!fs.existsSync(extensionsRoot)) {

return { entries };

}

import fs from "node:fs";

import path from "node:path";

import officialExternalChannelCatalog from "../../../scripts/lib/official-external-channel-catalog.json" with { type: "json" };

import { MANIFEST_KEY } from "../../compat/legacy-names.js";

import { resolveOpenClawPackageRootSync } from "../../infra/openclaw-root.js";

import { listChannelCatalogEntries } from "../../plugins/channel-catalog-registry.js";

}

function loadOfficialCatalogEntries(options: CatalogOptions): ChannelPluginCatalogEntry[] {

return loadCatalogEntriesFromPaths(resolveOfficialCatalogPaths(options))

const builtInEntries = parseCatalogEntries(officialExternalChannelCatalog);

const fileEntries = loadCatalogEntriesFromPaths(resolveOfficialCatalogPaths(options));

return [...builtInEntries, ...fileEntries]

.map((entry) => buildExternalCatalogEntry(entry))

.filter((entry): entry is ChannelPluginCatalogEntry => Boolean(entry));

}

externalNpmSpec: "@vendor/whatsapp-fork",

externalLabel: "WhatsApp Fork",

});

describeChannelCatalogEntryContract({

channelId: "wecom",

npmSpec: "@wecom/wecom-openclaw-plugin",

alias: "wework",

});

withTimeout.mockImplementation(async <T>(promise: Promise<T>) => await promise);

});

it("passes pinned npm specs and expected integrity to npm installs with progress", async () => {

it("passes npm specs and optional expected integrity to npm installs with progress", async () => {

installPluginFromNpmSpec.mockImplementation(async (params) => {

params.logger?.info?.("Downloading demo-plugin…");

return {

);

});

it("does not offer npm installs without an exact version and integrity pin", async () => {

it("offers registry npm specs without requiring an exact version or integrity pin", async () => {

let captured:

| {

options: Array<{ value: "npm" | "local" | "skip"; label: string; hint?: string }>;

runtime: {} as never,

});

expect(captured?.options).toEqual([{ value: "skip", label: "Skip for now" }]);

expect(captured?.initialValue).toBe("skip");

expect(captured?.options).toEqual([

{ value: "npm", label: "Download from npm (@demo/plugin)" },

{ value: "skip", label: "Skip for now" },

]);

expect(captured?.initialValue).toBe("npm");

expect(installPluginFromNpmSpec).not.toHaveBeenCalled();

});

);

}

function resolvePinnedNpmSpecForOnboarding(install: PluginPackageInstall): string | null {

function resolveNpmSpecForOnboarding(install: PluginPackageInstall): string | null {

const npmSpec = install.npmSpec?.trim();

const expectedIntegrity = install.expectedIntegrity?.trim();

if (!npmSpec || !expectedIntegrity) {

if (!npmSpec) {

return null;

}

const parsed = parseRegistryNpmSpec(npmSpec);

return parsed?.selectorKind === "exact-version" ? npmSpec : null;

return parsed ? npmSpec : null;

}

function resolveInstallDefaultChoice(params: {

defaultChoice: InstallChoice;

prompter: WizardPrompter;

}): Promise<InstallChoice> {

const npmSpec = resolvePinnedNpmSpecForOnboarding(params.entry.install);

const npmSpec = resolveNpmSpecForOnboarding(params.entry.install);

const safeLabel = sanitizeTerminalText(params.entry.label);

const safeNpmSpec = npmSpec ? sanitizeTerminalText(npmSpec) : null;

const safeLocalPath = params.localPath ? sanitizeTerminalText(params.localPath) : null;

workspaceDir,

allowLocal,

});

const npmSpec = resolvePinnedNpmSpecForOnboarding(entry.install);

const npmSpec = resolveNpmSpecForOnboarding(entry.install);

const defaultChoice = resolveInstallDefaultChoice({

cfg: next,

entry,

});

});

it("exposes trusted registry npm specs without requiring an exact version or integrity pin", () => {

discoverOpenClawPlugins.mockReturnValue({

candidates: [

{

idHint: "vllm",

origin: "config",

rootDir: "/Users/test/.openclaw/extensions/vllm",

source: "/Users/test/.openclaw/extensions/vllm/index.js",

packageName: "@openclaw/vllm",

packageDir: "/Users/test/.openclaw/extensions/vllm",

packageManifest: {

install: {

npmSpec: "@openclaw/vllm",

},

},

},

],

diagnostics: [],

});

loadPluginManifest.mockReturnValue({

ok: true,

manifestPath: "/Users/test/.openclaw/extensions/vllm/openclaw.plugin.json",

manifest: {

id: "vllm",

configSchema: {

type: "object",

},

},

});

resolveManifestProviderAuthChoices.mockReturnValue([

{

pluginId: "vllm",

providerId: "vllm",

methodId: "server",

choiceId: "vllm",

choiceLabel: "vLLM",

},

]);

expect(resolveProviderInstallCatalogEntry("vllm")).toEqual({

pluginId: "vllm",

providerId: "vllm",

methodId: "server",

choiceId: "vllm",

choiceLabel: "vLLM",

label: "vLLM",

origin: "config",

install: {

npmSpec: "@openclaw/vllm",

defaultChoice: "npm",

},

});

});

it("does not expose npm install specs from untrusted package metadata", () => {

discoverOpenClawPlugins.mockReturnValue({

candidates: [

return manifest.ok ? manifest : null;

}

function resolveTrustedPinnedNpmSpec(params: {

function resolveTrustedNpmSpec(params: {

origin: PluginOrigin;

install?: PluginPackageInstall;

}): string | undefined {

if (params.origin !== "bundled" && params.origin !== "config") {

return undefined;

}

const npmSpec = params.install?.npmSpec?.trim();

const expectedIntegrity = params.install?.expectedIntegrity?.trim();

if (!npmSpec || !expectedIntegrity) {

if (!npmSpec) {

return undefined;

}

const parsed = parseRegistryNpmSpec(npmSpec);

return parsed?.selectorKind === "exact-version" ? npmSpec : undefined;

return parsed ? npmSpec : undefined;

}

function resolveInstallInfo(params: {

packageDir?: string;

workspaceDir?: string;

}): PluginPackageInstall | null {

const npmSpec = resolveTrustedPinnedNpmSpec({

const npmSpec = resolveTrustedNpmSpec({

origin: params.origin,

install: params.install,

});