Neura Market Logo

Plugin Install Overrides for E2E and Package Validation

Learn how plugin install overrides direct setup-time installations to specific npm packages or local tarballs. This page is intended for maintainers testing packaged plugins in E2E or validation scenarios.

Read this when

  • Testing onboarding or setup flows against a locally packed plugin
  • Verifying a plugin package before publishing it
  • Replacing an automatic plugin install with a test artifact

Plugin install overrides allow maintainers to direct setup-time plugin installations toward a particular npm package or a local npm-pack tarball, rather than the catalog, bundled, or default npm source. These are intended solely for E2E and package validation scenarios. Regular users install plugins via openclaw plugins install.

Warning

Overrides execute plugin code from whatever source you specify. Only use them within an isolated state directory or a disposable test machine.

Environment

Overrides remain inactive unless both environment variables are defined:

export OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1
export OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{
  "codex": "npm-pack:/tmp/openclaw-codex-2026.5.8.tgz",
  "openclaw-web-search": "npm:@openclaw/web-search@2026.5.8"
}'

The override map is a JSON object keyed by plugin identifier. The values support the following:

PrefixSource
npm:<registry-spec>Registry packages, specific versions, or tags
npm-pack:<path.tgz>Local tarballs generated by npm pack; relative paths are resolved from the current working directory

Behavior

When a setup-time workflow installs a plugin whose identifier appears in the map, OpenClaw uses the override source in place of the catalog, bundled, or default npm source. This behavior applies during onboarding and any other workflow that relies on the shared setup-time plugin installer.

  • Overrides still enforce the expected plugin identifier: a tarball assigned to codex must install a plugin whose manifest identifier is codex.
  • Overrides do not inherit the official trusted-source status. Even when the catalog entry normally designates an OpenClaw-owned package, an override is treated as operator-supplied test input.
  • Workspace .env files cannot activate install overrides; both environment variables appear on the blocked workspace dotenv list. Set them in the trusted shell, CI job, or remote test command that launches OpenClaw.

Package E2E

Use an isolated state directory so that package installations and their records do not interfere with your regular OpenClaw state:

npm pack extensions/codex --pack-destination /tmp

OPENCLAW_STATE_DIR="$(mktemp -d)" \
OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1 \
OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{"codex":"npm-pack:/tmp/openclaw-codex-2026.5.8.tgz"}' \
pnpm openclaw onboard --mode local

Confirm the installed package within the state directory:

find "$OPENCLAW_STATE_DIR/npm/projects" -path '*/node_modules/@openclaw/codex/package.json' -print
grep -R '"@openclaw/codex"' "$OPENCLAW_STATE_DIR/npm/projects"/*/package-lock.json

For live provider E2E, source the real API key from a trusted shell or CI secret before executing the test command. Do not output keys; report only the source and whether the key was present.