| `openclaw.compat.pluginApi` | Minimum OpenClaw plugin API range required by this package, using a semver floor like `>=2026.5.27`. |

| `openclaw.install.expectedIntegrity` | Expected npm dist integrity string such as `sha512-...`; install and update flows verify the fetched artifact against it. |

| `openclaw.install.allowInvalidConfigRecovery` | Allows a narrow bundled-plugin reinstall recovery path when config is invalid. |

| `openclaw.install.requiredPlatformPackages` | npm package aliases that must materialize when their lockfile platform constraints match the current host. |

| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Lets setup-runtime channel surfaces load before listen, then defers the full configured channel plugin until post-listen activation. |

Manifest metadata decides which provider/channel/setup choices appear in

newer-but-valid values skip external plugins on older hosts. Bundled source

plugins are assumed to be co-versioned with the host checkout.

`openclaw.install.requiredPlatformPackages` is for npm packages that expose

required native binaries through optional, platform-specific aliases. List the

bare npm package name for every supported platform alias. During npm install,

OpenClaw verifies only the declared alias whose lockfile constraints match the

current host. If npm reports success but omits that alias, OpenClaw retries once

with a fresh cache and rolls back the install if the alias is still missing.

`openclaw.compat.pluginApi` is enforced during package install for non-bundled

plugin sources. Use it for the OpenClaw plugin SDK/runtime API floor that the

package was built against. It can be stricter than `minHostVersion` when a

| `minHostVersion` | `string` | Minimum supported OpenClaw version in the form `>=x.y.z` or `>=x.y.z-prerelease`. |

| `expectedIntegrity` | `string` | Expected npm dist integrity string, usually `sha512-...`, for pinned installs. |

| `allowInvalidConfigRecovery` | `boolean` | Lets bundled-plugin reinstall flows recover from specific stale-config failures. |

| `requiredPlatformPackages` | `string[]` | Required platform-specific npm aliases verified during npm install. |

<AccordionGroup>

<Accordion title="Onboarding behavior">

"install": {

"npmSpec": "@openclaw/codex",

"defaultChoice": "npm",

"minHostVersion": ">=2026.5.1-beta.1"

"minHostVersion": ">=2026.5.1-beta.1",

"requiredPlatformPackages": [

"@openai/codex-linux-x64",

"@openai/codex-linux-arm64",

"@openai/codex-darwin-x64",

"@openai/codex-darwin-arm64",

"@openai/codex-win32-x64",

"@openai/codex-win32-arm64"

]

},

"compat": {

"pluginApi": ">=2026.6.2"

type CodexPackageManifest = {

dependencies?: Record<string, string>;

devDependencies?: Record<string, string>;

openclaw?: {

install?: {

requiredPlatformPackages?: string[];

};

};

};

describe("codex package manifest", () => {

expect(packageJson.dependencies?.["@openai/codex"]).toBe(

MANAGED_CODEX_APP_SERVER_PACKAGE_VERSION,

);

expect(packageJson.openclaw?.install?.requiredPlatformPackages).toEqual([

"@openai/codex-linux-x64",

"@openai/codex-linux-arm64",

"@openai/codex-darwin-x64",

"@openai/codex-darwin-arm64",

"@openai/codex-win32-x64",

"@openai/codex-win32-arm64",

]);

});

});

import { createSuiteTempRootTracker } from "../test-helpers/temp-dir.js";

import { captureEnv } from "../test-utils/env.js";

import {

listMissingRequiredPlatformPackages,

repairManagedNpmRootOpenClawPeer,

removeManagedNpmRootDependency,

readManagedNpmRootInstalledDependency,

}

describe("managed npm root", () => {

it("finds explicitly required optional packages for the current platform", async () => {

const npmRoot = await makeTempRoot();

const matchingPackage = "@vendor/tool-platform";

const scriptedPackage = "@vendor/tool-scripted";

const foreignPackage = "@vendor/tool-foreign";

const unconstrainedPackage = "@vendor/tool-optional";

const unlistedPackage = "@vendor/tool-unlisted";

await fs.writeFile(

path.join(npmRoot, "package-lock.json"),

`${JSON.stringify({

lockfileVersion: 3,

packages: {

"": {},

[`node_modules/${matchingPackage}`]: {

optional: true,

os: [process.platform],

cpu: [process.arch],

},

[`node_modules/${scriptedPackage}`]: {

optional: true,

hasInstallScript: true,

os: [process.platform],

cpu: [process.arch],

},

[`node_modules/${foreignPackage}`]: {

optional: true,

os: [`not-${process.platform}`],

cpu: [process.arch],

},

[`node_modules/${unconstrainedPackage}`]: {

optional: true,

},

[`node_modules/${unlistedPackage}`]: {

optional: true,

os: [process.platform],

cpu: [process.arch],

},

},

})}\n`,

);

await expect(

listMissingRequiredPlatformPackages({

npmRoot,

requiredPackageNames: [

matchingPackage,

scriptedPackage,

foreignPackage,

unconstrainedPackage,

],

}),

).resolves.toEqual(

[matchingPackage, scriptedPackage]

.map((name) => ({

name,

packagePath: path.join(npmRoot, "node_modules", ...name.split("/")),

}))

.toSorted((left, right) => left.packagePath.localeCompare(right.packagePath)),

);

});

it("keeps existing plugin dependencies when adding another managed plugin", async () => {

const npmRoot = await makeTempRoot();

await fs.writeFile(

);

}

function readLockPackageName(location: string, value: unknown): string | undefined {

if (isRecord(value)) {

const packageName = readOptionalString(value.name);

if (packageName) {

return packageName;

}

}

function hasNpmPlatformConstraint(value: Record<string, unknown>): boolean {

return value.os !== undefined || value.cpu !== undefined || value.libc !== undefined;

}

function readLockPackageLocationName(location: string): string | undefined {

const parts = location.split("/");

for (let index = parts.length - 1; index >= 0; index -= 1) {

if (parts[index] !== "node_modules") {

return undefined;

}

function readLockPackageName(location: string, value: unknown): string | undefined {

if (isRecord(value)) {

const packageName = readOptionalString(value.name);

if (packageName) {

return packageName;

}

}

return readLockPackageLocationName(location);

}

function resolveManagedNpmLockPackagePath(params: {

npmRoot: string;

location: string;

}): string | undefined {

const npmRoot = path.resolve(params.npmRoot);

const packagePath = path.resolve(npmRoot, ...params.location.split("/"));

const relativePath = path.relative(npmRoot, packagePath);

if (

!relativePath ||

relativePath === ".." ||

relativePath.startsWith(`..${path.sep}`) ||

path.isAbsolute(relativePath)

) {

return undefined;

}

return packagePath;

}

function isTopLevelLockPackageLocation(location: string): boolean {

return location.split("/").filter((part) => part === "node_modules").length === 1;

}

export type MissingRequiredPlatformPackage = {

name: string;

packagePath: string;

};

/** Lists explicitly required current-platform packages that npm recorded but did not materialize. */

export async function listMissingRequiredPlatformPackages(params: {

npmRoot: string;

requiredPackageNames: ReadonlySet<string> | readonly string[];

}): Promise<MissingRequiredPlatformPackage[]> {

const requiredPackageNames = new Set(params.requiredPackageNames);

if (requiredPackageNames.size === 0) {

return [];

}

const lockPath = path.join(params.npmRoot, "package-lock.json");

const parsed = await readJson<unknown>(lockPath);

if (!isRecord(parsed) || !isRecord(parsed.packages)) {

return [];

}

const missing: MissingRequiredPlatformPackage[] = [];

for (const [location, value] of Object.entries(parsed.packages)) {

if (

!isRecord(value) ||

value.optional !== true ||

!hasNpmPlatformConstraint(value) ||

isUnsupportedOptionalLockPackage(value)

) {

continue;

}

const name = readLockPackageLocationName(location);

const packagePath = resolveManagedNpmLockPackagePath({ npmRoot: params.npmRoot, location });

if (!name || !requiredPackageNames.has(name) || !isSafePackageName(name) || !packagePath) {

continue;

}

if (!(await pathExists(packagePath))) {

missing.push({ name, packagePath });

}

}

return missing.toSorted((left, right) => left.packagePath.localeCompare(right.packagePath));

}

function findLockPackageVersion(params: {

lockfile: ManagedNpmRootLockfile;

packageName: string;