Skip to main content
Common plugin management commands. For the full command contract, flags, source-selection rules, and edge cases, see openclaw plugins. Typical workflow: find a package, install it from ClawHub, npm, git, or a local path, let the managed Gateway auto-restart (or restart it manually), then verify the plugin’s runtime registrations.

​
List and search plugins

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search "calendar"
--json for scripts: 
openclaw plugins list --json \
  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
plugins list is a cold inventory check: what OpenClaw can discover from config, manifests, and the persisted plugin registry. It does not prove an already-running Gateway imported the plugin runtime. JSON output includes registry diagnostics and each plugin’s dependencyStatus (whether declared dependencies/optionalDependencies resolve on disk). plugins search queries ClawHub for installable plugin packages and prints an install hint (openclaw plugins install clawhub:<package>) per result.

​
Enable and disable plugins

openclaw plugins enable <plugin-id>
openclaw plugins disable <plugin-id>
Toggles a plugin’s config entry without touching installed files. Some bundled plugins (bundled model/speech providers, the bundled browser plugin) are enabled by default; others require enable after install.

​
Install plugins

# Search ClawHub for plugin packages.
openclaw plugins search "calendar"

# Install from ClawHub.
openclaw plugins install clawhub:<package>
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta

# Install from npm.
openclaw plugins install npm:<package>
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex

# Install from a local npm-pack artifact.
openclaw plugins install npm-pack:<path.tgz>

# Install from git or a local development checkout.
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
Bare package specs install from npm during the launch cutover, unless the name matches a bundled or official plugin id, in which case OpenClaw uses that local/official copy instead. Use clawhub:, npm:, git:, or npm-pack: for deterministic source selection. Use --force only to overwrite an existing install target from a different source. For routine upgrades of a tracked npm, ClawHub, or hook-pack install, use openclaw plugins update instead; --force is not supported with --link.

​
Restart and inspect

A running managed Gateway with config reload enabled restarts automatically after installing, updating, or uninstalling plugin code. If the Gateway is unmanaged or reload is disabled, restart it yourself before checking live runtime surfaces: 
openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
inspect --runtime loads the plugin module and proves it registered runtime surfaces (tools, hooks, services, Gateway methods, HTTP routes, plugin-owned CLI commands). Plain inspect and list are cold manifest/config/registry checks only.

​
Update plugins

openclaw plugins update <plugin-id>
openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
openclaw plugins update <plugin-id> --dry-run
Passing a plugin id reuses its tracked install spec: stored dist-tags (@beta) and exact pinned versions carry over to later update <plugin-id> runs. openclaw plugins update --all is the bulk maintenance path. It still respects ordinary tracked install specs, but trusted official OpenClaw plugin records sync to the current official catalog target instead of staying pinned to a stale exact official package; when update.channel is beta, that sync prefers the beta release line. Use a targeted update <plugin-id> to keep an exact or tagged official spec untouched. For npm installs, pass an explicit package spec to switch the tracked record: 
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
The second command moves a plugin back to the registry’s default release line when it was previously pinned to an exact version or tag. See openclaw plugins for the exact fallback and pinning rules.

​
Uninstall plugins

openclaw plugins uninstall <plugin-id> --dry-run
openclaw plugins uninstall <plugin-id>
openclaw plugins uninstall <plugin-id> --keep-files
Uninstall removes the plugin’s config entry, persisted plugin index record, allow/deny list entries, and linked plugins.load.paths entries when applicable. The managed install directory is removed unless you pass --keep-files. A running managed Gateway restarts automatically when the uninstall changes plugin source. In Nix mode (OPENCLAW_NIX_MODE=1), plugin install, update, uninstall, enable, and disable are all disabled; manage those choices in the Nix source for the install instead.

​
Choose a source

SourceUse whenExample
ClawHubYou want OpenClaw-native discovery, scan summaries, versions, and hintsopenclaw plugins install clawhub:<package>
gitYou want a branch, tag, or commit from a repositoryopenclaw plugins install git:github.com/<owner>/<repo>@<ref>
local pathYou are developing or testing a plugin on the same machineopenclaw plugins install --link ./my-plugin
marketplaceYou are installing a Claude-compatible marketplace pluginopenclaw plugins install <plugin> --marketplace <source>
npm packYou are proving a local package artifact through npm install semanticsopenclaw plugins install npm-pack:<path.tgz>
npmjs.comYou already ship JavaScript packages or need npm dist-tags/private registryopenclaw plugins install npm:@acme/openclaw-plugin
Managed local path installs must be plugin directories or archives. Put standalone plugin files in plugins.load.paths instead of installing them with plugins install.

​
Publish plugins

ClawHub is the primary public discovery surface for OpenClaw plugins. Publish there when you want users to find plugin metadata, version history, registry scan results, and install hints before they install. 
npm i -g clawhub
clawhub login
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0
Native npm plugins must ship a plugin manifest (openclaw.plugin.json) plus package.json metadata before publishing:
package.json
{
  "name": "@acme/openclaw-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

npm publish --access public
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
Use these pages for the full publishing contract instead of treating this page as the publishing reference:
  • ClawHub publishing explains owners, scopes, releases, review, package validation, and package transfer.
  • Building plugins shows the full plugin package shape (including openclaw.plugin.json) and first publish workflow.
  • Plugin manifest defines native plugin manifest fields.
If the same package is available on both ClawHub and npm, use the explicit clawhub: or npm: prefix to force one source.