@openclaw/plugin-inspector is the offline compatibility checker for OpenClaw plugin packages and plugin fixture suites.

It answers the questions that matter before a plugin reaches users:

• can OpenClaw discover the package metadata and openclaw.plugin.json manifest?
• which hooks, registration calls, manifest contracts, and SDK imports does the plugin use?
• does the plugin still look compatible without local OpenClaw internals?
• if CI finds a breakage, which JSON, Markdown, SARIF, JUnit, and summary artifacts should downstream automation read?
• when a fixture-suite harness such as Crabpot runs many plugins, which findings are hard breakages, known warnings, live issues, deprecations, or inspector proof gaps?

The default path is static, offline, and credential-free. Runtime capture exists, but it is opt-in because it imports plugin code.

• Node.js 22 or newer.
• A plugin package root with package.json.
• openclaw.plugin.json when the plugin uses the OpenClaw manifest contract.
• No OpenClaw checkout, credentials, network service, or live provider access for default inspection.

Pass --no-openclaw when CI should not compare against a local OpenClaw checkout. If an OpenClaw checkout is supplied with --openclaw <path>, the inspector only reads public compatibility surfaces such as compat records, SDK exports, hook names, manifest fields, and registrar metadata.

Run this from a plugin package root:

npx @openclaw/plugin-inspector inspect --no-openclaw

Equivalent one-off runners:

pnpm dlx @openclaw/plugin-inspector inspect --no-openclaw
yarn dlx @openclaw/plugin-inspector inspect --no-openclaw
bunx @openclaw/plugin-inspector inspect --no-openclaw

The command writes:

• reports/plugin-inspector-report.json
• reports/plugin-inspector-report.md
• reports/plugin-inspector-issues.md

It exits non-zero when hard compatibility breakages are found. Warnings, suggestions, issue classifications, and logs stay visible in the report without necessarily failing the command.

Install the package when you want repeatable local scripts and CI:

npm install --save-dev @openclaw/plugin-inspector

Add scripts:

{
  "scripts": {
    "plugin:check": "plugin-inspector inspect --no-openclaw",
    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
  }
}

Then run:

npm run plugin:check

The initializer can write the starter config, package scripts, and GitHub Actions workflow:

npx @openclaw/plugin-inspector init --ci --scripts --dry-run
npx @openclaw/plugin-inspector init --ci --scripts

init detects packageManager and common lockfiles. Override that with --package-manager npm, --package-manager pnpm, --package-manager yarn, or --package-manager bun. Existing files are protected unless you pass --force.

Small plugin repos can keep configuration in package.json:

{
  "scripts": {
    "plugin:check": "plugin-inspector inspect --no-openclaw",
    "plugin:ci": "plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
  },
  "pluginInspector": {
    "version": 1,
    "plugin": {
      "id": "weather",
      "priority": "high",
      "seams": ["dynamic-tool"],
      "sourceRoot": "src",
      "expect": {
        "registrations": ["registerTool"]
      }
    },
    "capture": {
      "mockSdk": true
    }
  }
}

Use plugin-inspector.config.json for a standalone config file:

{
  "version": 1,
  "plugin": {
    "id": "weather",
    "priority": "high",
    "seams": ["dynamic-tool"],
    "sourceRoot": "src",
    "expect": {
      "registrations": ["registerTool"]
    }
  },
  "capture": {
    "mockSdk": true
  },
  "openclaw": {
    "defaultCheckoutPath": "../openclaw"
  }
}

Inspect the resolved config before wiring CI:

plugin-inspector config --json

Copy-ready examples live in:

• examples/plugin-inspector.config.json
• examples/package-json-plugin-inspector.json

Common options:

Run the built-in help for the exact CLI surface:

plugin-inspector --help

Runtime capture imports plugin entrypoints in an isolated subprocess and records what register(api) does. Use it when static inspection cannot prove the actual registrations made at runtime.

plugin-inspector inspect --no-openclaw --runtime --mock-sdk --allow-execute

--allow-execute is the deliberate safety switch. Without it, modes that import plugin code fail closed. The older environment guard still works for custom harnesses:

PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector inspect --no-openclaw --runtime --mock-sdk

By default, runtime capture uses generated mocks for openclaw/plugin-sdk subpaths and unresolved external packages discovered in the plugin import graph. That keeps compatibility CI offline and credential-free. It does not call live services, launch OpenClaw, run provider SDKs, or emulate service lifecycle side effects.

Use --real-sdk only when the plugin workspace already has real SDK dependencies installed and you intentionally want that path.

Runtime capture writes:

• reports/plugin-inspector-runtime-capture.json
• reports/plugin-inspector-runtime-capture.md

Capture one entrypoint directly:

plugin-inspector capture ./dist/index.js --mock-sdk --allow-execute

plugin-inspector ci writes the normal compatibility report plus CI-native summary, SARIF, and JUnit artifacts.

Minimal GitHub Actions workflow:

name: plugin-inspector

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute
      - uses: actions/upload-artifact@v5
        if: always()
        with:
          name: plugin-inspector-reports
          path: reports/plugin-inspector-*

Generated ci artifacts:

• reports/plugin-inspector-report.json
• reports/plugin-inspector-report.md
• reports/plugin-inspector-issues.md
• reports/plugin-inspector-ci-summary.json
• reports/plugin-inspector-ci-summary.md
• reports/plugin-inspector.sarif
• reports/plugin-inspector.junit.xml

CI examples:

• examples/github-actions-plugin-inspector.yml
• examples/github-actions-code-scanning.yml
• examples/gitlab-ci-plugin-inspector.yml
• examples/circleci-plugin-inspector.yml

The compatibility report is the primary contract. Preserve field names and finding codes because downstream CI and Crabpot reports may consume them.

Important report sections:

Issue classes currently flow through the reports as live issues, compat gaps, deprecation warnings, inspector gaps, upstream metadata, and fixture regressions.

plugin-inspector owns the shared CI policy and report rendering primitives. Fixture-suite harnesses such as Crabpot should call these exports instead of reimplementing scoring, summaries, Markdown, SARIF, or JUnit handling.

The root API exposes grouped helpers:

import { ci } from "@openclaw/plugin-inspector";

const policyReport = ci.buildPolicyReport({
  policy,
  compatibilityReport,
  executionResults,
  strict: false,
});

await ci.writePolicyReport(policyReport);

CI policy reports default to:

• reports/plugin-inspector-ci-policy.json
• reports/plugin-inspector-ci-policy.md

A policy must use version: 1 and define:

• allowedBlocked
• expectedWarnings
• thresholds
• fixtureSets

Policy scoring fails hard breakages, unknown blocked synthetic probes, hard ref diff regressions, failed execution results, strict live P0 issues, and strict classified blockers. Non-strict mode keeps classified blocked probes and live P0 issues visible as warnings.

CI summary helpers read the known report set from reports/ and render one machine-readable and one Markdown rollup:

• compatibility
• runtime capture
• synthetic probes
• cold import readiness
• workspace plan
• platform probes
• import-loop profile
• execution results
• runtime profile
• ref diff
• profile diff
• CI policy

Most plugin authors should use the plugin-root workflow. Use fixture suites when one repository intentionally checks many plugins or packages, as Crabpot does.

plugin-inspector report --config crabpot.config.json --out reports
plugin-inspector report --config crabpot.config.json --out reports --check
plugin-inspector ci --config crabpot.config.json --out reports --no-openclaw

Fixture-suite configs are loaded through the explicit fixture helpers. That keeps normal plugin-root configuration simple while still supporting bulk compatibility harnesses.

Prefer the CLI for normal plugin repositories. Import the public API when a test harness needs to compose workflows directly:

import { pluginRoot } from "@openclaw/plugin-inspector";

const { report, paths } = await pluginRoot.runCheck({
  pluginRoot: process.cwd(),
  openclawPath: false,
  outDir: "reports",
});

console.log(report.status, paths.jsonPath);

Stable grouped facades:

Named exports remain available for existing automation. Prefer the grouped facades for new code because they show ownership and keep downstream wrappers thin.

Repository checks are intentionally small and offline:

npm test
npm run release:contents
npm run check

npm run check runs the Node test suite and the package-contents guard. The contents guard shells through npm pack --dry-run --json and verifies the npm tarball includes package entrypoints, examples, README assets, and no private test/, scripts/, or .github/ paths.

Useful release-prep commands:

npm run release:local
npm run release:readiness
npm run release:notes
npm run release:plan
npm run release:crabpot -- --crabpot ../crabpot

release:readiness proves the local package and verifies Crabpot follow-through. It does not publish.

Keep this package dependency-light. Do not add runtime dependencies unless they remove real complexity. Default checks must stay offline and credential-free.

The package publishes from annotated v* tags through GitHub Actions. The release workflow runs the test suite, verifies the npm tarball, publishes the GitHub release, and publishes the public npm package through npm trusted publishing.

Before tagging a release:

1. Move CHANGELOG.md Unreleased notes into a versioned section.
2. Update package.json to the same version.
3. Update Crabpot's pluginInspectorRef to the release commit.
4. Run npm run release:readiness.
5. Run the Crabpot plugin-inspector smoke commands printed by npm run release:crabpot -- --crabpot ../crabpot.

After npm publish, update Crabpot's package pin and run:

npm run release:crabpot -- --crabpot ../crabpot --published

Do not publish npm packages without explicit owner approval.

There is no CONTRIBUTING.md in this repository. Until one exists, use the repo scripts above as the local contract and follow these project rules:

• preserve stable report field names and finding codes;
• prefer public OpenClaw plugin contracts over core internals;
• isolate any OpenClaw source parsing behind explicit helpers;
• keep runtime execution behind --allow-execute or PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1;
• when behavior, entrypoints, release metadata, or the npm package version change, update Crabpot's @openclaw/plugin-inspector pin/docs/smoke path and run the Crabpot plugin-inspector smoke before calling the work done.