Inspect and diagnose plugins

This page covers the read-only diagnostic commands: openclaw plugins inspect, openclaw plugins doctor, and openclaw plugins registry.

Inspect

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --all

Inspect shows identity, load status, source, manifest capabilities, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support without importing plugin runtime by default. JSON output includes the plugin manifest contracts, such as contracts.agentToolResultMiddleware and contracts.trustedToolPolicies, so operators can audit trusted-surface declarations before enabling or restarting a plugin. Add --runtime to load the plugin module and include registered hooks, tools, commands, services, gateway methods, and HTTP routes. Runtime inspection reports missing plugin dependencies directly; installs and repairs stay in openclaw plugins install, openclaw plugins update, and openclaw doctor --fix.

Default human inspection uses enabled, disabled, or error status labels, matching plugins list. It describes the metadata snapshot; it does not claim that a plugin module was imported. With --runtime, successful runtime inspection uses loaded. JSON retains the underlying registry status and separate imported field. Known-incompatible plugins remain visible with their repair guidance. Their diagnostics do not prevent inspection of other plugins, including with --runtime.

An unfinished plugin data migration also prevents runtime evaluation. The plugin stays visible with its Doctor action instead of running against unmigrated data. Stop the Gateway, run openclaw doctor --fix against the same state and config, then start the Gateway again. A reload that encounters this condition refuses the replacement before stopping the existing plugin.

For multi-entry packages, inspecting any child shows the shared package install metadata. inspect --all --json includes that same record for each child. If package ownership is missing or ambiguous, inspection omits install metadata rather than attributing an unrelated install record.

Plugin-owned CLI commands are usually installed as root openclaw command groups, but plugins may also register nested commands under a core parent such as openclaw nodes. After inspect --runtime shows a command under cliCommands, run it at the listed path; for example a plugin that registers demo-git can be verified with openclaw demo-git ping.

Each plugin is classified by what it actually registers at runtime:

See Plugin shapes for more on the capability model.

SDK import failures appear in the existing plugin error output and Doctor's plugin diagnostics. The diagnostic names the plugin, imported openclaw/plugin-sdk/* API, running core version, and build version when known. For an official plugin, run openclaw plugins update <id>. A running Gateway applies the update before the command completes; otherwise it loads the update at its next start. If the error identifies a nested SDK, the plugin bundles an incompatible OpenClaw SDK; update the plugin or contact its author.

JSON diagnostics may include code: "sdk-incompatible" and an optional sdkCompatibility object with seam, coreVersion, builtWithOpenClawVersion (when known), and nestedSdk. Existing diagnostics without these fields remain valid. Model errors point to runtime inspection without including raw loader errors.

Doctor

openclaw plugins doctoropenclaw plugins doctor --json

doctor reports plugin load errors, manifest/discovery diagnostics, compatibility notices, and stale plugin config references such as missing plugin slots. It loads plugin modules without activating plugins and does not query the running Gateway. When these local checks pass, it prints Plugin discovery, module loading, compatibility, and configuration checks passed. Run "openclaw health" to check the running Gateway, including runtime quarantines and fallbacks. The health command reads current runtime quarantine and fallback state from the Gateway. If stale config remains but the install tree is otherwise healthy, the summary says so instead of implying full plugin health.

With --json, the same discovery, compatibility, and configuration diagnostics are returned as one machine-readable object.

Doctor waits for its inspection registration resources to be released before printing the report and setting the diagnostic exit status. Cleanup failures produce a command error instead of a successful report. Running Gateway registrations are not disposed by this inspection.

If a configured plugin is present on disk but blocked by the loader's path-safety checks, config validation keeps the plugin entry and reports it as present but blocked. Fix the preceding blocked-plugin diagnostic, such as path ownership or world-writable permissions, instead of removing the plugins.entries.<id> or plugins.allow config.

For module-shape failures such as missing register/activate exports, rerun with OPENCLAW_PLUGIN_LOAD_DEBUG=1 to include a compact export-shape summary in the diagnostic output.

Doctor priorities and repair steps

The main openclaw doctor summary puts current plugin inspection and loading failures under Fix now. Run openclaw plugins inspect <id> --runtime for the named plugin, then repair its configured path, ownership, dependencies, or install according to that diagnostic. For an incompatible official plugin, run openclaw plugins update <id> and rerun Doctor. Preserve an enabled plugin's configuration while repairing its files.

Legacy compatibility notices are Recommended improvements: update or replace the affected plugin to remove its dependence on legacy APIs. A plugin version mismatch includes a confirmed update command when one is available; update before restarting the Gateway. When no compatible registry release exists, keep the current install and check for a compatible release rather than attempting an unavailable version. These local findings do not replace the running Gateway's health check.

Registry

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

The local plugin registry is OpenClaw's persisted cold read model for installed plugin identity, enablement, source metadata, and contribution ownership. Normal startup, provider owner lookup, channel setup classification, and plugin inventory can read it without importing plugin runtime modules.

When that registry is missing or stale, Gateway startup validates current plugin metadata and serves from that prepared snapshot. After readiness, maintenance refreshes the persisted registry in the shared-state worker under the plugin lifecycle lease using current config and package facts. This retains metadata for later updates without blocking request handling on a SQLite write. Refresh failures produce warnings without replacing the active runtime snapshot. Config recovery and database compatibility checks remain startup gates; updates retain those checks.

Use plugins registry to inspect whether the persisted registry is present, current, or stale. Use --refresh to rebuild it from the persisted plugin index, config policy, and manifest/package metadata. This is a repair path, not a runtime activation path.

Inspection revalidates warnings for unavailable or unreadable configured plugin load paths against the current config, including permission errors and symbolic link loops. Removing the final path removes its warning from the inspected view; a path that remains configured and unavailable or unreadable still produces a warning. Inspection does not rewrite the persisted registry. Use --refresh to update that ledger.

When persisted and derived plugin records differ, the command lists each differing plugin with both sources. JSON output returns the same rows in differences. Policy staleness reports policy-changed in refreshReasons and leaves differences empty because policy validation runs before record comparison; a policy refresh can still update enabled fields. A refresh rereads and verifies its persisted replacement before it reports success. If plugin package files keep changing during verification, stop those updates and run openclaw plugins registry --refresh again.

openclaw doctor --fix also repairs registry-adjacent managed npm drift. If an orphaned or recovered @openclaw/* package under a managed plugin npm project or the legacy flat managed npm root shadows a bundled plugin, doctor removes that stale package and rebuilds the registry so startup validates against the bundled manifest. When an authoritative install record selects one managed generation but older flat or generation directories remain, doctor retires those stale trees for pruning after the gateway restarts. Doctor also relinks the host openclaw package into managed npm plugins that declare peerDependencies.openclaw, so package-local runtime imports such as openclaw/plugin-sdk/* resolve after updates or npm repairs.