Manage OpenClaw Plugins: UI and CLI Guide

The Control UI handles the standard flow of finding, installing, enabling, and disabling plugins. For updating, uninstalling, detailed configuration, and controlling install sources, you need the CLI. The complete command contract, flag reference, source-selection rules, and edge cases are documented in openclaw plugins.

A typical CLI session goes like this: locate a package, pull it from ClawHub, npm, git, or a local directory, let the managed Gateway restart on its own (or trigger a manual restart), then confirm the plugin's runtime registrations.

Use the Control UI

Head to Plugins in the Control UI, or navigate with /settings/plugins relative to the configured Control UI base path. With a base path of /openclaw, the URL becomes /openclaw/settings/plugins. Two tabs are available:

• Installed presents the complete local inventory, grouped by category (channels, model providers, memory, tools). Clicking a row opens a detail view; the overflow (…) menu toggles the plugin on or off and, for externally installed plugins, exposes Remove. This tab also shows configured MCP servers with the same menu-driven enable, disable, and remove options, editing mcp.servers in the Gateway configuration.
• Discover acts as the store: featured plugins bundled with OpenClaw, official external plugins, and a curated connector shelf. Connector cards either spin up a hosted MCP server with a single click (GitHub, Notion, Linear, Sentry, Home Assistant) or drop you into a prefilled ClawHub search. Typing in the search box queries ClawHub live and adds a From ClawHub section showing download counts and source-verification badges.

Plugins shipped with OpenClaw skip the package install step. Their menu action is Enable or Disable. Workboard, for instance, comes bundled and starts disabled, so pick Enable to activate it. Bundled plugins support disabling but never removal.

Catalog and search access hinge on operator.read. Install, enable, disable, remove, and MCP server changes demand operator.admin. A ClawHub install runs through the Gateway, preserving its trust, integrity, and plugin-install policy checks. When an administrator enables an installed plugin, that explicit trust gets recorded by appending the selected plugin to an existing restrictive plugins.allow list. An explicit plugins.deny entry takes precedence and must be deleted before the plugin can be enabled.

Plugin code installation or removal forces a Gateway restart. Enablement changes skip the restart when the installed plugin and current Gateway runtime permit it; otherwise the UI flags that a restart is mandatory. OAuth-backed MCP connectors still require a one-time openclaw mcp login <name> from the CLI after being added.

The Control UI cannot install from arbitrary npm, git, or local-path sources, cannot update plugins, and does not expose rich plugin configuration. For those operations, fall back to the CLI workflows below.

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 performs a cold inventory check: what OpenClaw can discover from config, manifests, and the persisted plugin registry. It does not verify that an already-running Gateway loaded the plugin runtime. JSON output carries registry diagnostics and each plugin's dependencyStatus (whether declared dependencies/optionalDependencies resolve on disk).

plugins search searches 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>

Flips a plugin's config entry without altering installed files. Some bundled plugins (bundled model/speech providers, the bundled browser plugin) start enabled; others need 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 falls back to that local/official copy. For deterministic source selection, use clawhub:, npm:, git:, or npm-pack:. OpenClaw's bundled and official catalog packages are trusted alongside ClawHub packages. New arbitrary npm, git, local path/archive, npm-pack:, or marketplace sources require --force in noninteractive installs after you review and trust the source.

--force confirms a non-ClawHub source without prompting and overwrites an existing install target when needed. For routine upgrades of a tracked npm, ClawHub, or hook-pack install, use openclaw plugins update instead. With --link, --force only confirms the source; the linked directory is not copied or overwritten.

If a newly installed plugin needs configuration that is missing, OpenClaw records the install but keeps the plugin disabled. Configure plugins.entries.<id>.config, then run openclaw plugins enable <id>. If an existing config entry is present but invalid, install fails without rewriting it.

A plugin package can expose multiple child entries. Installation tracks that package once, enables each ready child entry, and preserves any child that you explicitly disabled. Runtime policy remains child-addressable through plugins.entries.<child-id>, allow/deny lists, channel config, exact child load paths, and the memory and contextEngine slots.

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. For a multi-entry package, any child id resolves to the one tracked package install, so all siblings update together. Removed or renamed children have their stale entries, allow/deny policy, exact load paths, channel config, and memory/context slot selections reconciled before the new package/index state commits; retained/new children and unrelated plugins are preserved.

If OpenClaw cannot prove exactly one package owner and a complete child list, update and uninstall 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 the ambiguity remains, reinstall the package before retrying.

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. The canonical channel resolver uses both update.channel and the installed core version, so an installed beta core with no configured channel keeps official plugins on the beta release line. Use a targeted update <plugin-id> to keep an exact or tagged official spec untouched.

For npm installs, supply an explicit package spec to change which record is being tracked:

openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin

When a plugin had been locked to a specific version or tag, the second command returns it to the registry's default release line.

Refer to openclaw plugins for the precise 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

Uninstalling deletes the package's persisted install record along with every owned child entry from plugin config, allow/deny lists, memory/context slots, exact linked plugins.load.paths, and channel config entries where relevant. Any child id can be used to address a multi-entry package; the preview shows the package owner and all siblings slated for removal. The managed install directory is removed once unless --keep-files is passed. If the uninstall alters the plugin source, a running managed Gateway restarts on its own.

When an installed Claw references the plugin, preview and uninstall output the affected Claw package names. A standard plugin uninstall can still go through and may break those Claws; run openclaw claws status first to check ownership. Removing a Claw frees its plugin reference but leaves the process-wide plugin intact by default.

In Nix mode (OPENCLAW_NIX_MODE=1), plugin install, update, uninstall, enable, and disable are all turned off; handle those decisions in the Nix source for the install instead.

Choose a source

Managed local path installs must be plugin directories or archives. Place standalone plugin files in plugins.load.paths rather than installing them with plugins install.

Publish plugins

ClawHub serves as the main public discovery surface for OpenClaw plugins. Publish there when you want users to see plugin metadata, version history, registry scan results, and install hints before installation.

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 include a plugin manifest (openclaw.plugin.json) plus package.json metadata prior to publishing:

{
  "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

For the complete publishing contract, consult these pages instead of using this one as the publishing reference:

• ClawHub publishing covers owners, scopes, releases, review, package validation, and package transfer.
• Building plugins details the full plugin package shape (including openclaw.plugin.json) and the first publish workflow.
• Plugin manifest defines the fields for native plugin manifests.

If the same package exists on both ClawHub and npm, use the explicit clawhub: or npm: prefix to force a particular source.

Related

• Plugins - install, configure, restart, and troubleshoot
• openclaw plugins - full CLI reference
• Community plugins - public discovery and ClawHub publishing
• ClawHub - registry CLI operations
• Building plugins - create a plugin package
• Plugin manifest - manifest and package metadata