CLI Plugins Reference for Gateway Management

Manage Gateway plugins, hook packs, and compatible bundles.

Plugin system, A user guide covering plugin installation, activation, and troubleshooting.
Manage plugins, Quick reference examples for installing, listing, updating, removing, and publishing.
Plugin bundles, How bundle compatibility works.
Plugin manifest, Schema and field definitions for manifests.
Security, Hardening measures for plugin installation.

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
openclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]
openclaw plugins build [--entry <path>] [--check]
openclaw plugins validate [--entry <path>]
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, inspections, removals, or registry refreshes, execute the command with OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. The trace outputs phase timing details to stderr while keeping the JSON output machine readable. Refer to Debugging for more information.

Note

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

Note

Bundled plugins come with OpenClaw. Some are active by default (for instance, bundled model providers, bundled speech providers, and the bundled browser plugin); others need plugins enable to be enabled.

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

plugins list displays either Format: openclaw or Format: bundle. Verbose list and info output also reveals the bundle subtype (codex, claude, or cursor) along with any 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 first argument specifies the plugin id; --name sets the display name. OpenClaw uses the id for the default output directory and package naming. Tool scaffolds rely on defineToolPlugin and produce package.json scripts plugin:build and plugin:validate that build and then invoke openclaw plugins build/validate.

plugins build imports the built entry, reads its static tool metadata, writes openclaw.plugin.json, and ensures package.json's openclaw.extensions stays in sync. plugins validate verifies that the generated manifest, package metadata, and current entry export still match. See Tool Plugins for the complete authoring workflow.

The scaffold writes TypeScript source but generates metadata from the compiled ./dist/index.js entry, so the workflow also works with the published CLI. Use --entry <path> when the entry is not the default package entry. Use plugins build --check in CI to fail when generated metadata is outdated without modifying 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 generate a generic OpenAI-compatible model provider plugin with API-key authentication plumbing, a npm run validate script that runs clawhub package validate, ClawHub package metadata, and a manually triggered GitHub Actions workflow for future trusted publishing through GitHub OIDC. Provider scaffolds do not produce skills and do not use openclaw plugins build/validate; those commands belong to the tool scaffold's generated-metadata path.

Before publishing, replace the placeholder API base URL, model catalog, documentation route, credential text, and README content with actual provider information. Use the generated README for 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 clawhub:<package> --acknowledge-clawhub-risk
openclaw plugins install <package> --dangerously-force-unsafe-install

Maintainers testing setup-time installations can override automatic plugin install sources using guarded environment variables. See Plugin install overrides for details.

Warning

Bare package names install from npm by default during the launch cutover, unless they match a bundled or official plugin id. In that case, OpenClaw uses the local or official copy instead of querying the npm registry. Use npm:<package> when you intentionally want an external npm package. Use clawhub:<package> for ClawHub. Treat plugin installations like running code; prefer pinned versions.

Warning

ClawHub packages and the bundled or official catalog from OpenClaw are considered trusted sources for installation. When you install from an arbitrary npm registry, npm-pack:, a git repository, a local path or archive, or a marketplace, a warning appears and asks for confirmation. For noninteractive installations from arbitrary sources, you must supply --force after verifying the source is safe. The same flag can also overwrite an existing installation target when needed. Normal updates of an already tracked installation do not require this flag. This confirmation is separate from --acknowledge-clawhub-risk, which only applies to risky ClawHub release trust warnings. --force does not bypass security.installPolicy or any other install safety checks.

With plugins search, you can query ClawHub for packages that are installable as code-plugin and bundle-plugin (but not skills; use openclaw skills search for those). The default --limit is 20, with a maximum of 100. This command only reads the remote catalog: it does not inspect local state, modify configuration, install packages, or load plugins at runtime. Results show the ClawHub package name, family, channel, version, summary, and an install hint like openclaw plugins install clawhub:<package>.

Note

Most plugins are primarily distributed and discovered through ClawHub. Npm is still supported as a fallback and a direct installation path. OpenClaw-owned @openclaw/* plugin packages are published again on npm; see the current list at npmjs.com/org/openclaw or the plugin inventory. Stable installations use latest. Beta-channel installations and updates prefer the npm beta dist-tag when it is available, falling back to latest. On the extended-stable channel, official npm plugins with a bare, default, or latest intent resolve to the exact version of the installed core. Exact pins, explicit non-latest tags, third-party packages, and sources other than npm are not rewritten.

Config includes and invalid-config repair

When your plugins section is backed by a single-file $include, plugins install/update/enable/disable/uninstall writes through to that included file and leaves openclaw.json unchanged. Root includes, include arrays, and includes that have sibling overrides fail closed instead of being flattened. For the supported shapes, see Config includes.

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

When the existing host config is valid but the newly installed plugin has no config of its own, OpenClaw records the install as disabled rather than writing an invalid enabled entry. Configure plugins.entries.<id>.config, then run openclaw plugins enable <id>. If a plugin config entry already exists but is invalid, the install fails without rewriting it.

--force confirmation and reinstall vs update

--force confirms a source that is not from ClawHub without showing a prompt. It does not bypass security.installPolicy or any other install safety checks. If the plugin or hook pack is already installed, it also reuses the existing target and overwrites it in place. Use this flag after reviewing an arbitrary npm, local, archive, git, or marketplace source, or when you intentionally want to reinstall 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 directs you to plugins update <id-or-npm-spec> for a normal upgrade, or to 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 require it. With --link, --force confirms the source but does not change the linked-path install mode.

--pin scope

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

--dangerously-force-unsafe-install

--dangerously-force-unsafe-install is deprecated and now does nothing. OpenClaw no longer runs built-in install-time blocking for dangerous code during plugin installs.

When host-specific install policy is needed, use the operator-owned security.installPolicy surface. Plugin before_install hooks are runtime lifecycle hooks for plugins, not the primary policy boundary for CLI installs.

If a plugin you published on ClawHub is hidden or blocked by a registry scan, follow the publisher steps in ClawHub publishing. --dangerously-force-unsafe-install does not ask ClawHub to rescan the plugin or make a blocked release public.

--acknowledge-clawhub-risk

Community ClawHub installs check the trust record of the selected release before downloading. If ClawHub disables download for the release, reports malicious scan findings, or puts the release in a blocking moderation state (quarantined or revoked), OpenClaw refuses it outright regardless of this flag. For non-blocking risky scan statuses or moderation states, OpenClaw shows the trust details and asks for confirmation before continuing.

Use --acknowledge-clawhub-risk only after reviewing the ClawHub warning and deciding to proceed without an interactive prompt. Pending or stale (not yet clean) scan results warn but do not require acknowledgement. Official ClawHub packages and bundled OpenClaw plugin sources skip this release-trust check entirely.

Hook packs and npm specs

plugins install is also the installation surface for hook packs that expose openclaw.hooks in package.json. Use openclaw hooks for filtered hook visibility and per-hook enablement, not for package installation.

Npm specifications are limited to registry-only formats, meaning a package name optionally paired with an exact version or dist-tag. Git, URL, file specs, and semver ranges are not accepted. Plugin dependency installations occur within a single managed npm project per plugin, using --ignore-scripts for isolation, regardless of any global npm settings configured in your shell. These managed npm projects for plugins inherit OpenClaw's package-level npm overrides, so host security pins also affect hoisted plugin dependencies.

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 identifier.

Raw @openclaw/* specs that match bundled plugins resolve to the image-owned bundled copy before falling back to npm. For instance, openclaw plugins install @openclaw/discord@2026.5.20 --pin uses the bundled Discord plugin from the current OpenClaw build instead of generating a managed npm override. To force the external npm package, use openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin.

Bare specs and @latest remain on the stable track. OpenClaw's date-stamped correction versions, like 2026.5.3-1, are considered stable for this purpose. If npm resolves either form to a prerelease, OpenClaw halts and requests explicit opt-in using 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 examines the resolved package metadata before proceeding with installation. If the latest stable package demands a newer OpenClaw plugin API or minimum host version, OpenClaw reviews older stable versions and installs the most recent compatible release. Exact versions and explicit dist-tags are enforced strictly: an incompatible selection fails and prompts you to upgrade OpenClaw or pick a compatible version.

When a bare install spec matches an official plugin identifier (for example diffs), OpenClaw installs the catalog entry directly. To install an npm package with the same name, provide an explicit scoped spec (for example @scope/diffs).

Git repositories

Use git:<repo> to install directly from a git repository. Supported formats 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 prior to installation.

Git installs clone into a temporary directory, check out the requested ref when one is provided, and then apply the standard plugin directory installer. As a result, manifest validation, operator install policy, package-manager install work, and install records all behave like npm installs. Recorded git installs include the source URL or ref along with the resolved commit, so openclaw plugins update can re-resolve the source later.

After installing from git, use openclaw plugins inspect <id> --runtime --json to verify runtime registrations such as gateway methods and CLI commands. If the plugin registered a CLI root with api.registerCli, execute 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 known-marketplace name from ~/.claude/plugins/known_marketplaces.json
a local marketplace root or marketplace.json path
a GitHub repo shorthand such as owner/repo
a GitHub repo URL such as https://github.com/owner/repo
a git URL

Remote marketplace rules

For remote marketplaces loaded from GitHub or git, plugin entries must stay inside the cloned marketplace repo. OpenClaw accepts relative path sources from that repo and rejects HTTP(S), absolute-path, git, GitHub, and other non-path plugin sources from remote manifests.

For local paths and archives, OpenClaw auto-detects:

OpenClaw plugins in their native format (openclaw.plugin.json)
Bundles that work with Codex (.codex-plugin/plugin.json)
Bundles compatible with Claude (.claude-plugin/plugin.json, or the default Claude component layout when no manifest file exists)
Bundles compatible with Cursor (.cursor-plugin/plugin.json)

Managed local installations must be plugin directories or archive files. Standalone plugin files like .js, .mjs, .cjs, and .ts 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 only load plugin package or bundle directories, skipping top-level script files treated as local helpers. Instead, list standalone files explicitly in plugins.load.paths.

Note

Compatible bundles are installed into the standard plugin root and follow the same list, info, enable, and disable workflow. Currently supported features include bundle skills, Claude command-skills, Claude settings.json defaults, Claude .lsp.json or manifest-declared lspServers defaults, Cursor command-skills, and compatible Codex hook directories. Other bundle capabilities that are detected appear in diagnostics and info output but are not yet connected to runtime execution.

Point -l or --link at a local plugin directory to reference it without copying (this adds it to plugins.load.paths):

openclaw plugins install -l ./my-plugin

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

Note

Plugins discovered from a workspace extensions root are not imported or executed until explicitly enabled. For local development, run openclaw plugins enable <plugin-id> or set plugins.entries.<plugin-id>.enabled: true. If your configuration uses plugins.allow, include the same plugin id there as well. 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), Display only enabled plugins.
--verbose (boolean), Switch from the table view to per-plugin detail lines showing format, source, origin, version, and activation metadata.
--json (boolean), Machine-readable inventory along with registry diagnostics and package dependency install state.

Note

plugins list reads the persisted local plugin registry first, falling back to a manifest-only derived result when the registry is missing or invalid. This 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 or 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 confirm 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 or 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 displays registered hooks and diagnostics from an inspection pass that loaded modules. Runtime inspection never installs dependencies; use openclaw doctor --fix to clear outdated dependency state or recover missing downloadable plugins that a config references.
openclaw gateway status --deep --require-rpc verifies the reachable Gateway URL/profile, service/process hints, config path, and RPC health.
Conversation hooks that are not bundled (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) need plugins.entries.<id>.hooks.allowConversationAccess=true.

Plugin index

Plugin install metadata is machine-managed state, not user configuration. Installs and updates write this data to the shared SQLite state database inside the active OpenClaw state directory. The installed_plugin_index row stores durable installRecords metadata, including records for broken or missing plugin manifests, plus a manifest-derived cold registry cache that openclaw plugins update, uninstall, diagnostics, and the cold plugin registry use.

plugins.installs is a retired authored-config surface. Runtime and update commands read only the SQLite installed-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 linked plugins.load.paths entries when applicable. Unless --keep-files is set, uninstall also deletes the tracked managed install directory, but only when that directory 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 shows a preview of what will be removed, then prompts Uninstall plugin "<id>"? before making changes. Pass --force to bypass 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 making any changes.

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-clawhub-risk
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

Updates apply to tracked plugin installs in the managed plugin index and tracked hook-pack installs in shared SQLite state. They reuse the source the user already chose when installing the plugin, so no second source acknowledgement is needed.

Resolving plugin id vs npm spec

When you pass a plugin id, OpenClaw reuses the recorded install spec for that plugin. That means previously stored dist-tags such as @beta and exact pinned versions continue to be used on later update <id> runs.

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.

That targeted-update rule differs from the bulk openclaw plugins update --all maintenance path. Bulk updates still respect ordinary tracked install specs, but trusted official OpenClaw plugin records can sync to the current official catalog target instead of staying on a stale exact official package. Use targeted update <id> when you intentionally want to keep an exact or tagged official spec untouched.

For npm installs, you can also pass an explicit npm package spec with a dist-tag or exact version. OpenClaw resolves that package name back to the tracked plugin record, updates that installed plugin, and records the new npm spec for future id-based updates.

Passing the npm package name without a version or tag also resolves back to the tracked plugin record. Use this when a plugin was pinned to an exact version and you want to move it back to the registry's default release line.

Beta channel updates

Targeted openclaw plugins update <id-or-npm-spec> reuses the tracked plugin spec unless you pass a new spec. Bulk openclaw plugins update --all uses the configured update.channel when it syncs trusted official plugin records to the official catalog target, so beta-channel installs can stay on the beta release line instead of being silently normalized to stable/latest.

openclaw update also knows the active OpenClaw update channel: on the beta channel, default-line npm and ClawHub plugin records try @beta first. They fall back to the recorded default/latest spec if no plugin beta release exists; npm plugins also fall back when the beta package exists but fails install validation. That fallback is reported as a warning and does not fail the core update. Exact versions and explicit tags stay pinned to that selector for targeted updates.

Version checks and integrity drift

Before a live npm update, OpenClaw checks the installed package version against the npm registry metadata. If the installed version and recorded artifact identity already match the resolved target, the update is skipped without downloading, reinstalling, or rewriting openclaw.json.

When a stored integrity hash exists and the fetched artifact hash changes, OpenClaw treats that as npm artifact drift. The interactive openclaw plugins update command prints the expected and actual hashes and asks for confirmation before proceeding. Non-interactive update helpers fail closed unless the caller supplies an explicit continuation policy.

--dangerously-force-unsafe-install on update

--dangerously-force-unsafe-install is also accepted on plugins update for compatibility, but it is deprecated and no longer changes plugin update behavior. Operator security.installPolicy can still block updates; plugin before_install hooks only apply in processes where plugin hooks are loaded.

--acknowledge-clawhub-risk on update

Community ClawHub-backed plugin updates run the same exact-release trust check as installs before downloading the replacement package. Use --acknowledge-clawhub-risk for reviewed automation that should continue when the selected ClawHub release has a risky trust warning. Official ClawHub packages and bundled OpenClaw plugin sources bypass this release-trust prompt.

Inspect

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

The inspect command displays identity, load status, source, manifest capabilities, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support without loading the plugin runtime by default. When JSON output is used, the plugin manifest contracts like contracts.agentToolResultMiddleware and contracts.trustedToolPolicies are included, letting operators audit trusted-surface declarations before enabling or restarting a plugin. To load the plugin module and include registered hooks, tools, commands, services, gateway methods, and HTTP routes, add --runtime. Missing plugin dependencies are reported directly by runtime inspection; installs and repairs remain in openclaw plugins install, openclaw plugins update, and openclaw doctor --fix.

Plugin-owned CLI commands typically install as root openclaw command groups, though plugins may also register nested commands under a core parent like openclaw nodes. After inspect --runtime displays a command under cliCommands, execute it at the listed path; for instance, a plugin registering demo-git can be verified with openclaw demo-git ping.

Each plugin is categorized 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

For more on the capability model, see Plugin shapes.

Note

A machine-readable report suitable for scripting and auditing is produced by the --json flag. A fleet-wide table with shape, capability kinds, compatibility notices, bundle capabilities, and hook summary columns is rendered by inspect --all. info serves as an alias for inspect.

Doctor

openclaw plugins doctor

Plugin load errors, manifest/discovery diagnostics, compatibility notices, and stale plugin config references such as missing plugin slots are reported by doctor. When the install tree and plugin config are clean, it prints No plugin issues detected.. If stale config remains but the install tree is otherwise healthy, the summary states that rather than implying full plugin health.

When a configured plugin exists on disk but is blocked by the loader's path-safety checks, config validation retains 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 like 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

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

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

Managed npm drift adjacent to the registry is also repaired by openclaw doctor --fix. 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.

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

Entries from the configured OpenClaw marketplace feed are listed by plugins marketplace entries. By default it attempts the hosted feed and falls back to the latest accepted snapshot or bundled data. To read a specific configured profile, use --feed-profile <name>. To read an explicit hosted feed URL, use --feed-url <url>. To read the latest accepted snapshot without fetching the feed, use --offline.

The configured hosted feed snapshot is refreshed by plugins marketplace refresh, which reports whether OpenClaw accepted hosted data, a hosted snapshot, or bundled fallback data. Use --expected-sha256 when a caller needs the command to fail unless a fresh hosted payload matches a pinned checksum.

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. The resolved source label plus the parsed marketplace manifest and plugin entries are printed by --json.

Marketplace refresh loads a hosted OpenClaw marketplace feed and persists the validated response as the local hosted-feed snapshot. Without options, it uses 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 (sha256:<hex> or a bare 64-character hex digest), use --expected-sha256 <sha256>. For machine-readable output, use --json. Explicit hosted feed URLs must not include 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.

Payload identity clawhub-official is expected by the built-in clawhub-public profile. 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 validates the DSSE envelope, and if a profile includes feedId, it checks that the decoded payload ID matches that identity. The built-in clawhub-public profile always specifies its identity, which stops a valid document meant for a different feed from being reused through that profile.

During the staged rollout, existing custom signed profiles that leave out feedId keep signature verification but lack payload identity enforcement. New custom profiles ought to include feedId. The feed profile configuration interface is being delivered separately, along with the presentation metadata that Control UI requires. Its Doctor diagnostic must request that the operator provide a missing identity and must not deduce one from the feed URL. This trust binding does not bring back the retired root marketplaces key.

CLI Plugins Reference: Manage Gateway Plugins, Hook Packs, and Bundles

Commands

Author

Provider scaffold

Install

Config includes and invalid-config repair

--force confirmation and reinstall vs update

--pin scope

--dangerously-force-unsafe-install

--acknowledge-clawhub-risk

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

--dangerously-force-unsafe-install on update

--acknowledge-clawhub-risk 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

--dangerously-force-unsafe-install

--acknowledge-clawhub-risk

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

--dangerously-force-unsafe-install on update

--acknowledge-clawhub-risk on update

Inspect

Doctor

Registry

Marketplace

Related