OpenClaw Plugins CLI Reference

Manage Gateway plugins, hook packs, and compatible bundles.

Plugin system, A user-facing guide covering installation, activation, and issue resolution for plugins.
Manage plugins, Concise examples for installing, listing, updating, removing, and publishing.
Plugin bundles, The compatibility model for bundles.
Plugin manifest, Manifest fields and the configuration schema.
Security, Hardening measures for plugin installations.

Commands

openclaw plugins list [--enabled] [--verbose] [--json]
openclaw plugins search <query> [--limit <n>] [--json]
openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]
openclaw plugins inspect <id> [--runtime] [--json]
openclaw plugins inspect --all [--runtime] [--json]
openclaw plugins info <id>                    # alias for inspect
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]
openclaw plugins update <id-or-npm-spec> | --all [--dry-run]
openclaw plugins registry [--refresh] [--json]
openclaw plugins doctor [--json]
openclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]
openclaw plugins build [--entry <path>] [--check]
openclaw plugins validate [--entry <path>] [--json]
openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]
openclaw plugins marketplace list <source> [--json]
openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

When investigating slow installs, uninstalls, registry refreshes, or inspections, execute the command with OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. The trace outputs phase timings to stderr while keeping JSON output intact. Refer to Debugging for details.

Note

Under Nix mode (OPENCLAW_NIX_MODE=1), openclaw.json cannot be modified. Commands install, update, uninstall, enable, and disable all decline to execute. Instead, modify the Nix source for this installation (programs.openclaw.config or instances.<name>.config for nix-openclaw) and rebuild. See the agent-first Quick Start.

Note

Bundled plugins accompany OpenClaw. Certain ones activate by default, such as the bundled model providers, bundled speech providers, and the bundled browser plugin; others need plugins enable.

Native OpenClaw plugins ship openclaw.plugin.json with an inline JSON Schema (configSchema, even when empty). Compatible bundles rely on their own bundle manifests.

plugins list displays Format: openclaw or Format: bundle. Verbose list or info output additionally reveals the bundle subtype (agent (Agent Plugins), codex, claude, or cursor) and detected bundle capabilities.

Author

openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate

By default, plugins init generates a minimal TypeScript tool plugin. The plugin id serves as the first argument, while --name specifies the display name. OpenClaw derives the default output directory and package naming from the id. Tool scaffolds employ defineToolPlugin and produce package.json scripts plugin:build and plugin:validate that build and then invoke openclaw plugins build/validate.

plugins build brings in the built entry, reads its static tool metadata, writes openclaw.plugin.json, and maintains alignment with package.json's openclaw.extensions. plugins validate verifies that the generated manifest, package metadata, and current entry export remain consistent. For a machine-readable validation result, pass --json. The complete authoring workflow appears in Tool Plugins.

The scaffold writes TypeScript source but derives metadata from the built ./dist/index.js entry, making the workflow compatible with the published CLI. When the entry differs from the default package entry, use --entry <path>. In CI, apply plugins build --check to fail on stale generated metadata without altering files.

Provider scaffold

openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate

Provider scaffolds produce a generic OpenAI-compatible model provider plugin featuring API-key authentication plumbing, a npm run validate script executing clawhub package validate, ClawHub package metadata, and a manually triggered GitHub Actions workflow for future trusted publishing via GitHub OIDC. These scaffolds skip skill generation and avoid openclaw plugins build/validate; those commands belong to the tool scaffold's generated-metadata path.

Before publishing, swap the placeholder API base URL, model catalog, docs route, credential text, and README copy with actual provider information. The generated README supports first-time ClawHub publishing and trusted-publisher configuration.

Install

openclaw plugins search "calendar"                      # search ClawHub plugins
openclaw plugins install @openclaw/<package>            # trusted official catalog
openclaw plugins install <package>                       # arbitrary npm package
openclaw plugins install clawhub:<package>                # ClawHub only
openclaw plugins install npm:<package>                    # npm only
openclaw plugins install npm-pack:<path.tgz>               # local npm-pack tarball
openclaw plugins install git:github.com/<owner>/<repo>     # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <path>                            # local path or archive
openclaw plugins install -l <path>                         # link instead of copy
openclaw plugins install <plugin>@<marketplace>             # marketplace shorthand
openclaw plugins install <plugin> --marketplace <name>      # marketplace (explicit)
openclaw plugins install <package> --force                  # confirm source / overwrite existing
openclaw plugins install <package> --pin                    # pin resolved npm version
openclaw plugins install <package> --acknowledge-install-policy-warning

Maintainers testing setup-time installs can override automatic plugin install sources using guarded environment variables. Consult Plugin install overrides.

Warning

During the launch cutover, bare package names install from npm by default, unless they correspond to a bundled or official plugin id, in which case OpenClaw uses that local or official copy instead of contacting the npm registry. To deliberately fetch an external npm package, use npm:<package>. For ClawHub, use clawhub:<package>. Treat plugin installs as code execution; prefer pinned versions.

Warning

ClawHub packages, along with OpenClaw's bundled or official catalog, count as reliable install origins. Any new npm, npm-pack:, git, local path or archive, or marketplace source that you haven't vetted will prompt with a warning before proceeding. For noninteractive arbitrary installs, --force must be supplied after you've inspected and accepted the source. That same flag also lets you replace an existing install destination when necessary. Routine updates of an already-tracked install don't call for it. --force doesn't skip security.installPolicy or any other install safety measures.

plugins search searches ClawHub for installable code-plugin and bundle-plugin packages, not skills, which you'd look up with openclaw skills search. The default --limit is 20, with a hard ceiling of 100. This operation only reads the remote catalog; it never inspects local state, changes config, installs packages, or loads plugin runtimes. The output lists the ClawHub package name, family, channel, version, summary, and an install hint like openclaw plugins install clawhub:<package>.

Note

For the majority of plugins, ClawHub serves as the main channel for distribution and discovery. Npm still works as a supported fallback and a direct-install route. OpenClaw-owned @openclaw/* plugin packages are once again published on npm; check the current listing at npmjs.com/org/openclaw or the plugin inventory. Stable installations rely on latest. Fresh beta-channel installs of official plugins require the npm beta dist-tag and halt if that release is absent; to pick a different release, pass an explicit version. Doctor, onboarding, and plugin-update recovery paths can fall back to the recorded or default selector, showing a visible warning. On the extended-stable channel, official npm plugins with bare/default or latest intent map to the exact installed core version. Exact pins, explicit non-latest tags, third-party packages, and non-npm sources stay as-is.

Config includes and invalid-config repair

When your plugins section relies on a single-file $include, plugins install/update/enable/disable/uninstall writes through to that included file, leaving openclaw.json untouched. Root includes, include arrays, and includes with sibling overrides fail closed rather than flattening. Supported shapes are covered in Config includes.

If config is invalid before install, plugins install normally fails closed and directs you to run openclaw doctor --fix first. During Gateway startup and hot reload, invalid plugin config fails closed like any other invalid config; openclaw doctor --fix can quarantine the invalid plugin entry. The lone pre-existing-config exception is a narrow bundled-plugin recovery path for plugins that explicitly opt into openclaw.install.allowInvalidConfigRecovery.

When the existing host config is valid but the newly installed plugin's own config is missing, OpenClaw records the install as disabled instead of writing an invalid enabled entry. Configure plugins.entries.<id>.config, then run openclaw plugins enable <id>. If an existing plugin config entry is present but invalid, install fails without rewriting it.

--force confirmation and reinstall vs update

--force confirms a non-ClawHub source without prompting. It does not bypass security.installPolicy or remaining install safety checks. When the plugin or hook pack is already installed, it also reuses the existing target and overwrites it in place. Use it after reviewing an arbitrary npm, local, archive, git, or marketplace source, or when intentionally reinstalling the same id. For routine upgrades of an already tracked npm plugin, prefer openclaw plugins update <id-or-npm-spec>.

If you run plugins install for a plugin id that is already installed, OpenClaw stops and points you at plugins update <id-or-npm-spec> for a normal upgrade, or at plugins install <package> --force when you genuinely want to overwrite the current install from a different source. Arbitrary sources still show the interactive provenance warning; noninteractive installs must pass --force after review. Trusted ClawHub and OpenClaw-catalog sources do not need it. With --link, --force confirms the source but does not change the linked-path install mode.

--pin scope

--pin applies to npm installs only and records the resolved exact <name>@<version>. It is not supported with git: installs (pin the ref in the spec instead, e.g. git:github.com/acme/plugin@v1.2.3) or with --marketplace (marketplace installs persist marketplace source metadata instead of an npm spec).

--acknowledge-install-policy-warning

When security.installPolicy returns warn in an interactive terminal, OpenClaw prints the reason and findings, then uses the same acknowledgement copy as a suspicious ClawHub release: type: '<plugin>' to install anyway. If the fully rendered review exceeds 4,000 characters, OpenClaw fails closed before prompting; reduce or coalesce the policy output first. A matching answer re-evaluates the staged source before continuing. A declined or non-interactive direct CLI install stops before commit; after review, --acknowledge-install-policy-warning explicitly approves every warning for that command invocation. Automatic and managed install surfaces cannot use that flag themselves; rerun the equivalent direct CLI command when one exists, or change security.installPolicy to return allow for the reviewed request before retrying the managed flow. Every approved warning is re-evaluated before continuing. Neither acknowledgement nor --force overrides block or a policy failure.

If a plugin you published on ClawHub is hidden or blocked by a registry scan, use the publisher steps in ClawHub publishing. This flag does not ask ClawHub to rescan the plugin or make a blocked release public. The deprecated --dangerously-force-unsafe-install flag remains a no-op.

ClawHub Security Audit

Community ClawHub installs check the selected release's trust record before downloading. OpenClaw prints the outcome, exact audit overview, and details link. A Review outcome is informational and installation continues. If ClawHub disables download or returns a blocking moderation outcome, OpenClaw refuses the release. Official ClawHub packages and bundled OpenClaw plugin sources bypass this release-trust check.

Hook packs and npm specs

plugins install also serves as the installation mechanism for hook packs that expose openclaw.hooks within package.json. For filtered hook visibility and per-hook activation, rely on openclaw hooks; it is not meant for package installation.

Npm specs are registry-only, meaning a package name plus an optional exact version or dist-tag. Git, URL, file specs, and semver ranges get rejected. Dependency installations occur in a single managed npm project per plugin, with --ignore-scripts ensuring safety even if your shell has global npm install configurations. Managed plugin npm projects adopt the npm-compatible portions of OpenClaw's dependency overrides. pnpm parent-child selectors are ignored; npm aliases stay unless the installed npm version disallows them.

To make npm resolution explicit, use npm:<package>. Bare package specs also install directly from npm during the launch cutover, unless they correspond to an official plugin id.

Raw @openclaw/* specs matching bundled plugins point to the image-owned bundled copy before falling back to npm. As an example, openclaw plugins install @openclaw/discord@2026.5.20 --pin selects the bundled Discord plugin from the current OpenClaw build rather than setting up a managed npm override. To force the external npm package, apply openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin.

Bare specs and @latest remain on the stable track. OpenClaw date-stamped correction versions, like 2026.5.3-1, qualify as stable for this evaluation. If npm resolves either form to a prerelease, OpenClaw halts and requests explicit opt-in via a prerelease tag (@beta/@rc) or an exact prerelease version (@1.2.3-beta.4).

For npm installs lacking an exact version (npm:<package> or npm:<package>@latest), OpenClaw reviews the resolved package metadata prior to installation. When the latest stable package demands a newer OpenClaw plugin API or minimum host version, OpenClaw examines older stable versions and installs the newest compatible release. Exact versions and explicit dist-tags stay strict: an incompatible choice fails and prompts you to upgrade OpenClaw or pick a compatible version.

When a bare install spec matches an official plugin id (for instance diffs), OpenClaw installs the catalog entry directly. To install an npm package sharing that name, use an explicit scoped spec (for example @scope/diffs).

Git repositories

Use git:<repo> for direct installation from a git repository. Accepted forms include git:github.com/owner/repo, git:owner/repo, full https://, ssh://, git://, file://, and git@host:owner/repo.git clone URLs. Add @<ref> or #<ref> to check out a branch, tag, or commit before installation.

Git installs clone into a temporary directory, check out the requested ref when present, then proceed with the standard plugin directory installer, so manifest validation, operator install policy, package-manager install work, and install records behave like npm installs. Recorded git installs capture the source URL/ref plus the resolved commit, enabling openclaw plugins update to re-resolve the source later.

Reinstalling the same Git source and ref without --force refuses an existing managed checkout, even if the repository now reports a different plugin id. Use openclaw plugins update <id> for a tracked upgrade, or openclaw plugins install git:<repo>@<ref> --force to deliberately reinstall the same plugin id. --force does not shift an existing install record to a different plugin id.

After a git install, use openclaw plugins inspect <id> --runtime --json to confirm runtime registrations such as gateway methods and CLI commands. If the plugin registered a CLI root with api.registerCli, run that command directly through the OpenClaw root CLI, for example openclaw demo-plugin ping.

Marketplace shorthand

Use plugin@marketplace shorthand when the marketplace name exists in Claude's local registry cache at ~/.claude/plugins/known_marketplaces.json:

openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

Use --marketplace to pass the marketplace source explicitly:

openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace

Marketplace sources

a Claude marketplace name that is known, taken from ~/.claude/plugins/known_marketplaces.json
a local marketplace root, or a path in the form of marketplace.json
a GitHub repo shorthand like owner/repo
a GitHub repo URL such as https://github.com/owner/repo
a git URL

Remote marketplace rules

When remote marketplaces are pulled from GitHub or git, plugin entries have to remain inside the cloned marketplace repo. OpenClaw accepts relative path sources coming from that repo, while HTTP(S), absolute-path, git, GitHub, and other non-path plugin sources are rejected from remote manifests.

For local paths and archives, OpenClaw detects automatically:

native OpenClaw plugins (openclaw.plugin.json)
Agent Plugins bundles (root plugin.json that declares the Agent Plugins $schema)
Codex-compatible bundles (.codex-plugin/plugin.json)
Claude-compatible bundles (.claude-plugin/plugin.json, or the default Claude component layout when that manifest file is missing)
Cursor-compatible bundles (.cursor-plugin/plugin.json)

Managed local installs have to be plugin directories or archives. Standalone .js, .mjs, .cjs, and .ts plugin files are not copied into the managed plugin root by plugins install, nor are they loaded when placed directly in ~/.openclaw/extensions or <workspace>/.openclaw/extensions; those auto-discovered roots load plugin package or bundle directories and skip top-level script files as local helpers. List standalone files explicitly in plugins.load.paths instead.

Note

Compatible bundles install into the normal plugin root and go through the same list/info/enable/disable flow. As of now, bundle skills, bundle MCP servers, Agent Plugins skills/MCP (with the PLUGIN_ROOT/PLUGIN_DATA subprocess contract), Claude command-skills, Claude settings.json defaults, Claude .lsp.json / manifest-declared lspServers defaults, Cursor command-skills, and compatible Codex hook directories are supported; other detected bundle capabilities appear in diagnostics/info but are not yet wired into runtime execution. See Plugin bundles for the per-format mapping.

Use -l/--link to reference a local plugin directory without copying it (adds to plugins.load.paths):

openclaw plugins install -l ./my-plugin

--link is not supported with --marketplace or git: installs, and it needs a local path that already exists. For a noninteractive local link, pass --force after reviewing the source; it confirms provenance but does not copy or overwrite the linked directory.

Note

Workspace-origin plugins discovered from a workspace extensions root are not imported or executed until they are explicitly enabled. For local development, run openclaw plugins enable <plugin-id> or set plugins.entries.<plugin-id>.enabled: true; if your config uses plugins.allow, include the same plugin id there too. This fail-closed rule also applies when channel setup explicitly targets a workspace-origin plugin for setup-only loading, so local channel plugin setup code will not run while that workspace plugin remains disabled or excluded from the allowlist. Linked installs and explicit plugins.load.paths entries follow the normal policy for their resolved plugin origin. See Configure plugin policy and Configuration reference.

Use --pin on npm installs to save the resolved exact spec (name@version) in the managed plugin index while keeping the default behavior unpinned.

List

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json

--enabled (boolean), Show only enabled plugins.
--verbose (boolean), Switch from the table view to per-plugin detail lines with format/source/origin/version/activation metadata.
--json (boolean), Machine-readable inventory plus registry diagnostics and package dependency install state.

Note

plugins list reads the persisted local plugin registry first, with a manifest-only derived fallback when the registry is missing or invalid. It is useful for checking whether a plugin is installed, enabled, and visible to cold startup planning, but it is not a live runtime probe of an already-running Gateway process. After changing plugin code, enablement, hook policy, or plugins.load.paths, restart the Gateway that serves the channel before expecting new register(api) code or hooks to run. For remote/container deployments, verify you are restarting the actual openclaw gateway run child, not only a wrapper process.

plugins list --json includes each plugin's dependencyStatus from package.json dependencies and optionalDependencies. OpenClaw checks whether those package names are present along the plugin's normal Node node_modules lookup path; it does not import plugin runtime code, run a package manager, or repair missing dependencies.

If startup logs plugins.allow is empty; discovered non-bundled plugins may auto-load: ..., run openclaw plugins list --enabled --verbose or openclaw plugins inspect <id> with a listed plugin id to verify the plugin ids and copy trusted ids into plugins.allow in openclaw.json. When the warning can list every discovered plugin, it prints a ready-to-paste plugins.allow snippet that already includes those ids. If a plugin loads without install/load-path provenance, inspect that plugin id, then either pin the trusted id in plugins.allow or reinstall the plugin from a trusted source so OpenClaw records install provenance.

For bundled plugin work inside a packaged Docker image, bind-mount the plugin source directory over the matching packaged source path, such as /app/extensions/synology-chat. OpenClaw discovers that mounted source overlay before /app/dist/extensions/synology-chat; a plain copied source directory remains inert, so normal packaged installs still use compiled dist.

For runtime hook debugging:

openclaw plugins inspect <id> --runtime --json shows registered hooks and diagnostics from a module-loaded inspection pass. Runtime inspection never installs dependencies; use openclaw doctor --fix to clean legacy dependency state or recover missing downloadable plugins that are referenced by config.
openclaw gateway status --deep --require-rpc confirms the reachable Gateway URL/profile, service/process hints, config path, and RPC health.
If a hook-only plugin is absent from runtime inspection, confirm its hook startup intent: either manifest activation.onCapabilities: ["hook"] with explicit plugin enablement, or a startup-signaling plugins.entries.<id>.hooks policy such as allowConversationAccess: true. Global disable, deny, and restrictive allowlists still win.
Non-bundled conversation hooks (before_model_resolve, agent_turn_prepare, before_prompt_build, before_agent_reply, llm_input, llm_output, before_agent_run, before_agent_finalize, agent_end) require plugins.entries.<id>.hooks.allowConversationAccess=true.

Plugin index

Plugin install metadata is machine-managed state, not user config. Installs and updates write it to the shared SQLite state database under the active OpenClaw state directory. The config_machine_state value keyed by plugins.installedIndex stores durable installRecords metadata, including records for broken or missing plugin manifests, plus a manifest-derived cold registry cache used by openclaw plugins update, uninstall, diagnostics, and the cold plugin registry.

An unreadable index is not invalid data. Permission, lock, and other read errors stop fallback, migration, and refresh with the original error. Restore database access, then rerun openclaw plugins registry to inspect the state before attempting repair. Do not delete the plugins.installedIndex row unless inspection succeeds and confirms invalid install records; a failed read alone does not justify deletion.

plugins.installs is a retired authored-config surface. Runtime and update commands read only the SQLite machine-state plugin index. Run openclaw doctor --fix to import legacy config records into the index and remove the retired key before normal runtime use.

Uninstall

openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
openclaw plugins uninstall <id> --force

uninstall removes plugin records from plugins.entries, the persisted plugin index, plugin allow/deny list entries, and any plugins.load.paths entry that exactly resolves to the recorded install path. For a package with multiple child entries, any child id resolves to the package owner; uninstall removes every sibling's policy and slot/channel references, the one package install record, and the managed directory once. Linked path installs also remove an exact entry for their recorded source path. Parent directories, child paths, prefix matches, and unrelated load paths are preserved. Unless --keep-files is set, uninstall also removes the tracked managed install directory, but only when it resolves inside OpenClaw's plugin extensions root. If the plugin currently owns the memory or contextEngine slot, that slot resets to its default (memory-core for memory, legacy for context engine).

uninstall prints a preview of what will be removed. Multi-entry packages name the package owner and every affected child before prompting. Pass --force to skip the confirmation prompt (useful for scripts and non-interactive runs); without it, uninstall requires an interactive TTY. --dry-run prints the same preview and exits without prompting or changing anything.

If OpenClaw cannot prove exactly one package owner and a complete child list, lifecycle mutations fail closed without changing package files, config, or the installed index. Run openclaw plugins registry --refresh, inspect openclaw plugins doctor, and use openclaw doctor --fix for repairable legacy index state. If ownership is still ambiguous, reinstall the package before retrying update or uninstall.

Note

--keep-config is supported as a deprecated alias for --keep-files.

Update

openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update @acme/demo
openclaw plugins update openclaw-codex-app-server --acknowledge-install-policy-warning

Updates apply to tracked plugin installs in the managed plugin index and tracked hook-pack installs in shared SQLite state. They reuse the source that the user already chose when installing the plugin, so they do not require a second source acknowledgement.

Resolving plugin id vs npm spec

When you pass a plugin id, OpenClaw reuses the recorded install spec for that plugin. For a multi-entry package, a child id resolves to its package owner and updates every sibling together. If the new package version removes or renames children, OpenClaw removes the retired children's entries, allow/deny policy, exact child load paths, channel config, and memory/context slot selections while preserving retained/new children and unrelated plugins. Previously stored dist-tags such as @beta and exact pinned versions continue to be used on later update <id> runs.

The narrow exception is a trusted official package completing a catalog-declared plugin id replacement. That update starts from the catalog package selector so the renamed manifest can replace the legacy id.

During update <id> --dry-run, exact pinned npm installs stay pinned. If OpenClaw can also resolve the package's registry default line and that default line is newer than the installed pinned version, the dry run reports the pin and prints the explicit @latest package update command to follow the registry default line.

The targeted-update behavior stands apart from the broader openclaw plugins update --all maintenance route. While bulk updates continue to honor standard tracked install specs, trusted official OpenClaw plugin records can move to the current official catalog target rather than remaining fixed on an outdated exact official package. Choose targeted update <id> when your intent is to preserve a specific or tagged official spec unchanged.

For npm-based installs, you have the option to supply an explicit npm package spec that includes a dist-tag or a precise version. OpenClaw maps that package name back to the tracked plugin record, refreshes the installed plugin accordingly, and stores the new npm spec so future id-driven updates use it.

Providing the npm package name without any version or tag likewise resolves back to the tracked plugin record. This approach suits scenarios where a plugin was locked to an exact version and you now want it to follow the registry's default release line.

Beta channel updates

Targeted openclaw plugins update <id-or-npm-spec> relies on the tracked plugin spec unless you provide a replacement spec. For floating trusted official records, it employs the canonical registry-channel resolver to pick the install target without altering the stored selector. Bulk openclaw plugins update --all applies the same resolver when syncing trusted official plugin records to the official catalog target. As a result, an installed beta core keeps official plugins on the beta release line when update.channel is not set, aligning with the core updater instead of quietly converting them to stable/latest. Explicit beta, dev, and extended-stable choices maintain their current priority.

openclaw update is also aware of the active OpenClaw update channel: on the beta channel, default-line npm and ClawHub plugin records attempt @beta first. If no plugin beta release exists, they fall back to the recorded default/latest spec; npm plugins also fall back when the beta package is present but fails install validation. This fallback surfaces as a warning and does not halt the core update. Exact versions and explicit tags remain locked to that selector for targeted updates, except during the trusted plugin id replacement described above.

Version checks and integrity drift

Before performing a live npm update, OpenClaw compares the installed package version with the npm registry metadata. When the installed version and recorded artifact identity already match the resolved target, the update is skipped, avoiding any download, reinstall, or rewrite of openclaw.json.

If a stored integrity hash exists and the fetched artifact hash differs, OpenClaw flags this as npm artifact drift. The interactive openclaw plugins update command displays both the expected and actual hashes and requests confirmation before continuing. Non-interactive update helpers fail closed unless the caller provides an explicit continuation policy.

--acknowledge-install-policy-warning on update

plugins update follows the same warning acknowledgement process as install, with type: '<plugin>' to update anyway used in an interactive terminal. The policy gets re-evaluated, and block or a policy failure remains terminal.

ClawHub Security Audit on update

Community ClawHub-backed plugin updates perform the same exact-release trust verification as installs prior to downloading the replacement package. Review outcomes are shown for informational purposes and the process continues; blocked releases stay non-installable. Official ClawHub packages and bundled OpenClaw plugin sources are exempt from this release-trust check.

Inspect

openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all

Inspect reports identity, load status, source, manifest capabilities, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support without loading plugin runtime by default. JSON output includes the plugin manifest contracts, such as contracts.agentToolResultMiddleware and contracts.trustedToolPolicies, enabling operators to 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 remain in openclaw plugins install, openclaw plugins update, and openclaw doctor --fix.

Plugin-owned CLI commands are typically installed as root openclaw command groups, but plugins can also register nested commands under a core parent like 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:

Shape	Meaning
`plain-capability`	exactly one capability type (e.g. a provider-only plugin)
`hybrid-capability`	more than one capability type (e.g. text + speech + images)
`hook-only`	only hooks, no capabilities, tools, commands, services, or routes
`non-capability`	tools/commands/services but no capabilities

See Plugin shapes for more on the capability model.

Note

The --json flag outputs a machine-readable report suitable for scripting and auditing. inspect --all renders a fleet-wide table with shape, capability kinds, compatibility notices, bundle capabilities, and hook summary columns. info is an alias for inspect.

Doctor

openclaw plugins doctor
openclaw 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.

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.

Registry

openclaw plugins registry
openclaw plugins registry --refresh
openclaw 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.

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.

openclaw doctor --fix additionally fixes managed npm drift that sits next to the registry. When a bundled plugin gets shadowed by an orphaned or recovered @openclaw/* package, whether under a managed plugin npm project or the legacy flat managed npm root, doctor deletes that stale package and rebuilds the registry, so startup checks against the bundled manifest. If an authoritative install record picks one managed generation while older flat or generation directories remain, doctor marks those stale trees for pruning once the gateway restarts. Doctor also re-links the host openclaw package into managed npm plugins that declare peerDependencies.openclaw, ensuring package-local runtime imports such as openclaw/plugin-sdk/* work after updates or npm repairs.

Marketplace

openclaw plugins marketplace entries
openclaw plugins marketplace entries --offline
openclaw plugins marketplace entries --json
openclaw plugins marketplace entries --feed-profile <name>
openclaw plugins marketplace entries --feed-url <url>
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
openclaw plugins marketplace refresh
openclaw plugins marketplace refresh --feed-profile <name>
openclaw plugins marketplace refresh --feed-url <url>
openclaw plugins marketplace refresh --expected-sha256 <sha256> --json

plugins marketplace entries pulls entries from the configured OpenClaw marketplace feed. It tries the hosted feed first by default, then falls back to the latest accepted snapshot or bundled data. To read a specific configured profile, pass --feed-profile <name>; for an explicit hosted feed URL, use --feed-url <url>; and to read the latest accepted snapshot without fetching the feed, use --offline.

plugins marketplace refresh refreshes the configured hosted feed snapshot and indicates whether OpenClaw accepted hosted data, a hosted snapshot, or bundled fallback data. When a caller needs the command to fail unless a fresh hosted payload matches a pinned checksum, --expected-sha256 is the option to use.

Marketplace list accepts a local marketplace path, a marketplace.json path, a GitHub shorthand like owner/repo, a GitHub repo URL, or a git URL. --json outputs the resolved source label along with the parsed marketplace manifest and plugin entries.

Marketplace refresh loads a hosted OpenClaw marketplace feed and stores the validated response as the local hosted-feed snapshot. With no options, it relies on the configured default feed profile. To refresh a specific configured profile, use --feed-profile <name>; to refresh an explicit hosted feed URL, use --feed-url <url>; to require a matching payload checksum, use --expected-sha256 <sha256> (either sha256:<hex> or a bare 64-character hex digest); and for machine-readable output, use --json. Explicit hosted feed URLs must not contain credentials, query strings, or fragments. Unpinned refreshes can report a hosted snapshot or bundled fallback result without failing the command. Pinned refreshes fail unless they accept a fresh hosted payload, and successful hosted refreshes fail if OpenClaw cannot persist the validated snapshot.

The built-in clawhub-public profile expects payload identity clawhub-official. OpenClaw will bundle ClawHub's production public key after ClawHub generates and hands off that key. Until then, the built-in profile does not grant signed-feed install authority. Public keys must come from a trusted release or operator channel, not from a key endpoint on the feed host.

OpenClaw verifies the DSSE envelope and, when a profile declares feedId, requires the decoded payload ID to match it. The built-in clawhub-public profile always declares its identity, preventing a valid document for another feed from being replayed through that profile.

During the staged rollout, existing custom signed profiles that omit feedId retain signature verification without payload-identity binding. New custom profiles should declare feedId. The feed-profile configuration surface is landing separately with the presentation metadata needed by Control UI; its Doctor diagnostic must ask the operator to supply a missing identity and must not infer one from the feed URL. This trust binding does not restore the retired root marketplaces key.

OpenClaw Plugins CLI Reference: Commands and Usage

Commands

Author

Provider scaffold

Install

Config includes and invalid-config repair

--force confirmation and reinstall vs update

--pin scope

--acknowledge-install-policy-warning

ClawHub Security Audit

Hook packs and npm specs

Git repositories

Archives

Marketplace shorthand

List

Plugin index

Uninstall

Update

Resolving plugin id vs npm spec

Beta channel updates

Version checks and integrity drift

--acknowledge-install-policy-warning on update

ClawHub Security Audit on update

Inspect

Doctor

Registry

Marketplace

Commands

Author

Provider scaffold

Install

Config includes and invalid-config repair

--force confirmation and reinstall vs update

--pin scope

--acknowledge-install-policy-warning

ClawHub Security Audit

Hook packs and npm specs

Git repositories

Archives

Marketplace shorthand

List

Plugin index

Uninstall

Update

Resolving plugin id vs npm spec

Beta channel updates

Version checks and integrity drift

--acknowledge-install-policy-warning on update

ClawHub Security Audit on update

Inspect

Doctor

Registry

Marketplace

Related