4.1 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| CLI reference for `openclaw plugins` (list, install, uninstall, enable/disable, doctor) |
|
plugins |
openclaw plugins
Manage Gateway plugins/extensions and compatible bundles.
Related:
- Plugin system: Plugins
- Bundle compatibility: Plugin bundles
- Plugin manifest + schema: Plugin manifest
- Security hardening: Security
Commands
openclaw plugins list
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
Bundled plugins ship with OpenClaw but start disabled. Use plugins enable to
activate them.
Native OpenClaw plugins must 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 (codex, claude, or cursor) plus detected bundle
capabilities.
Install
openclaw plugins install <path-or-spec>
openclaw plugins install <npm-spec> --pin
Security note: treat plugin installs like running code. Prefer pinned versions.
Npm specs are registry-only (package name + optional exact version or
dist-tag). Git/URL/file specs and semver ranges are rejected. Dependency
installs run with --ignore-scripts for safety.
Bare specs and @latest stay on the stable track. If npm resolves either of
those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a
prerelease tag such as @beta/@rc or an exact prerelease version such as
@1.2.3-beta.4.
If a bare install spec matches a bundled plugin id (for example diffs), OpenClaw
installs the bundled plugin directly. To install an npm package with the same
name, use an explicit scoped spec (for example @scope/diffs).
Supported archives: .zip, .tgz, .tar.gz, .tar.
For local paths and archives, OpenClaw auto-detects:
- native OpenClaw plugins (
openclaw.plugin.json) - Codex-compatible bundles (
.codex-plugin/plugin.json) - Claude-compatible bundles (
.claude-plugin/plugin.jsonor the default Claude component layout) - Cursor-compatible bundles (
.cursor-plugin/plugin.json)
Compatible bundles install into the normal extensions root and participate in
the same list/info/enable/disable flow. Today, bundle skills, Claude
command-skills, Claude settings.json defaults, Cursor command-skills, and compatible Codex hook
directories are supported; other detected bundle capabilities are shown in
diagnostics/info but are not yet wired into runtime execution.
Use --link to avoid copying a local directory (adds to plugins.load.paths):
openclaw plugins install -l ./my-plugin
Use --pin on npm installs to save the resolved exact spec (name@version) in
plugins.installs while keeping the default behavior unpinned.
Uninstall
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
uninstall removes plugin records from plugins.entries, plugins.installs,
the plugin allowlist, and linked plugins.load.paths entries when applicable.
For active memory plugins, the memory slot resets to memory-core.
By default, uninstall also removes the plugin install directory under the active
state dir extensions root ($OPENCLAW_STATE_DIR/extensions/<id>). Use
--keep-files to keep files on disk.
--keep-config is supported as a deprecated alias for --keep-files.
Update
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins update <id> --dry-run
Updates only apply to plugins installed from npm (tracked in plugins.installs).
When a stored integrity hash exists and the fetched artifact hash changes,
OpenClaw prints a warning and asks for confirmation before proceeding. Use
global --yes to bypass prompts in CI/non-interactive runs.