---
summary: "CLI reference for `openclaw plugins` (init, build, validate, list, install, reload, marketplace, uninstall, enable/disable, doctor)"
read_when:
  - You want to install or manage Gateway plugins or compatible bundles
  - You want to scaffold or validate a simple tool plugin
  - You want to debug plugin load failures
title: "Plugins CLI"
sidebarTitle: "Plugins"
---

# `openclaw plugins`

Manage Gateway plugins, hook packs, and compatible bundles.

<CardGroup cols={2}>
  <Card title="Plugin system" href="/tools/plugin">
    End-user guide for installing, enabling, and troubleshooting plugins.
  </Card>
  <Card title="Manage plugins" href="/plugins/manage-plugins">
    Quick examples for install, list, update, uninstall, and publishing.
  </Card>
  <Card title="Plugin bundles" href="/plugins/bundles">
    Bundle compatibility model.
  </Card>
  <Card title="Plugin manifest" href="/plugins/manifest">
    Manifest fields and config schema.
  </Card>
  <Card title="Security" href="/gateway/security">
    Security hardening for plugin installs.
  </Card>
</CardGroup>

## Commands

```bash
openclaw plugins list [--enabled] [--verbose] [--json]
openclaw plugins search <query> [--limit <n>] [--json]
openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--no-enable] [--accept-capabilities] [--acknowledge-install-policy-warning] [--marketplace <source>]
openclaw plugins inspect <id> [--runtime] [--json]
openclaw plugins inspect --all [--runtime] [--json]
openclaw plugins info <id>                    # alias for inspect
openclaw plugins enable <ids...> [--accept-capabilities]
openclaw plugins disable <ids...>
openclaw plugins reload <ids...> [--wait] [--accept-capabilities] [--json]
openclaw plugins uninstall <ids...> [--dry-run] [--keep-files] [--force]
openclaw plugins update <ids-or-npm-specs...> | --all [--dry-run]
openclaw plugins registry [--refresh] [--json]
openclaw plugins doctor [--json]
openclaw plugins init <id> [--name <name>] [--type tool|provider|feature] [--directory <path>]
openclaw plugins build [--root <path>] [--entry <path>] [--check]
openclaw plugins validate [--root <path>] [--entry <path>] [--json]
openclaw plugins pack [--root <path>] [--out <file.tgz>] [--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]
```

For slow install, inspect, uninstall, or registry-refresh investigation, run the
command with `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. The trace writes phase timings
to stderr and keeps JSON output parseable. See [Debugging](/help/debugging#plugin-lifecycle-trace).

<Note>
In Nix mode (`OPENCLAW_NIX_MODE=1`), `openclaw.json` is immutable. `install`, `update`, `uninstall`, `enable`, and `disable` all refuse to run. Manage those choices in the Nix source for this install (`programs.openclaw.config` or `instances.<name>.config` for nix-openclaw), then rebuild. Reload remains available when no new capability consent needs to be recorded; it preserves config and installation state. See the agent-first [Quick Start](https://github.com/openclaw/nix-openclaw#quick-start).
</Note>

<Note>
Bundled plugins ship with OpenClaw. A little over half are enabled by default — mostly model and speech providers, plus a few others such as the bundled browser plugin. Other bundled plugins need explicit enablement or relevant configuration. Enabled does not mean currently in use. Provider use depends on configuration and requests. Providers that require authentication need credentials; keyless providers such as Microsoft speech do not. An enabled entry in `plugins list` does not mean the plugin is doing work.

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

`plugins list` shows `Format: openclaw` or `Format: bundle`. Verbose list/info output also shows the bundle subtype (`agent (Agent Plugins)`, `codex`, `claude`, or `cursor`) plus detected bundle capabilities.
</Note>

## Plugins pages

This page is an index. `openclaw plugins` is documented on six pages, one per
reader job. Open the page that matches your task.

| Page                                                              | Read it when                                                                     |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [Author plugins](/cli/plugins/authoring)                          | You are scaffolding, building, validating, or packing a plugin project.          |
| [Install plugins](/cli/plugins/install)                           | You are installing from ClawHub, npm, git, a path, an archive, or a marketplace. |
| [List installed plugins](/cli/plugins/list)                       | You want the installed inventory, discovery diagnostics, or the plugin index.    |
| [Uninstall and update plugins](/cli/plugins/uninstall-and-update) | You are removing or reloading a plugin, or updating its version and source.      |
| [Inspect and diagnose plugins](/cli/plugins/inspect-and-diagnose) | You need plugin identity, runtime registrations, load errors, or registry state. |
| [Marketplace feeds](/cli/plugins/marketplace)                     | You are browsing, listing, or refreshing a marketplace or hosted signed feed.    |

## Where each section moved

Every section anchor from the previous single-page version keeps its id here,
so an existing link such as `/cli/plugins#registry` still resolves. Each entry
points at the page that now holds the content.

- <a id="author" />[Author](/cli/plugins/authoring#author)
- <a id="feature-scaffold-and-artifacts" />[Feature scaffold and artifacts](/cli/plugins/authoring#feature-scaffold-and-artifacts)
- <a id="provider-scaffold" />[Provider scaffold](/cli/plugins/authoring#provider-scaffold)
- <a id="install" />[Install](/cli/plugins/install#install)
- <a id="config-includes-and-invalid-config-repair" />[Config includes and invalid-config repair](/cli/plugins/install#config-includes-and-invalid-config-repair)
- <a id="force-confirmation-and-reinstall-vs-update" />[`--force` confirmation and reinstall vs update](/cli/plugins/install#force-confirmation-and-reinstall-vs-update)
- <a id="pin-scope" />[`--pin` scope](/cli/plugins/install#pin-scope)
- <a id="acknowledge-install-policy-warning" />[`--acknowledge-install-policy-warning`](/cli/plugins/install#acknowledge-install-policy-warning)
- <a id="clawhub-security-audit" />[ClawHub Security Audit](/cli/plugins/install#clawhub-security-audit)
- <a id="hook-packs-and-npm-specs" />[Hook packs and npm specs](/cli/plugins/install#hook-packs-and-npm-specs)
- <a id="git-repositories" />[Git repositories](/cli/plugins/install#git-repositories)
- <a id="archives" />[Archives](/cli/plugins/install#archives)
- <a id="marketplace-shorthand" />[Marketplace shorthand](/cli/plugins/install#marketplace-shorthand)
- <a id="marketplace-sources" />[Marketplace sources](/cli/plugins/install#marketplace-sources)
- <a id="remote-marketplace-rules" />[Remote marketplace rules](/cli/plugins/install#remote-marketplace-rules)
- <a id="list" />[List](/cli/plugins/list#list)
- <a id="param-enabled" />[`--enabled`](/cli/plugins/list#param-enabled)
- <a id="param-verbose" />[`--verbose`](/cli/plugins/list#param-verbose)
- <a id="param-json" />[`--json`](/cli/plugins/list#param-json)
- <a id="plugin-index" />[Plugin index](/cli/plugins/list#plugin-index)
- <a id="reload" />[Reload](/cli/plugins/uninstall-and-update#reload)
- <a id="uninstall" />[Uninstall](/cli/plugins/uninstall-and-update#uninstall)
- <a id="update" />[Update](/cli/plugins/uninstall-and-update#update)
- <a id="resolving-plugin-id-vs-npm-spec" />[Resolving plugin id vs npm spec](/cli/plugins/uninstall-and-update#resolving-plugin-id-vs-npm-spec)
- <a id="beta-channel-updates" />[Beta channel updates](/cli/plugins/uninstall-and-update#beta-channel-updates)
- <a id="existing-plugin-source-choices" />[Existing plugin source choices](/cli/plugins/uninstall-and-update#existing-plugin-source-choices)
- <a id="version-checks-and-integrity-drift" />[Version checks and integrity drift](/cli/plugins/uninstall-and-update#version-checks-and-integrity-drift)
- <a id="acknowledge-install-policy-warning-on-update" />[`--acknowledge-install-policy-warning` on update](/cli/plugins/uninstall-and-update#acknowledge-install-policy-warning-on-update)
- <a id="clawhub-security-audit-on-update" />[ClawHub Security Audit on update](/cli/plugins/uninstall-and-update#clawhub-security-audit-on-update)
- <a id="inspect" />[Inspect](/cli/plugins/inspect-and-diagnose#inspect)
- <a id="doctor" />[Doctor](/cli/plugins/inspect-and-diagnose#doctor)
- <a id="registry" />[Registry](/cli/plugins/inspect-and-diagnose#registry)
- <a id="marketplace" />[Marketplace](/cli/plugins/marketplace#marketplace)

## Related

- [Building plugins](/plugins/building-plugins)
- [CLI reference](/cli)
- [ClawHub](/clawhub)
- [ClawHub CLI](/clawhub/cli) - standalone registry commands
- [ClawHub publishing](/clawhub/publishing) - owners, scopes, and release review