Use this file to discover all available pages before exploring further.

Plugins

Manage Gateway plugins, hook packs, and compatible bundles.

Plugin system

End-user guide for installing, enabling, and troubleshooting plugins.

Plugin bundles

Bundle compatibility model.

Plugin manifest

Manifest fields and config schema.

Security

Security hardening for plugin installs.

Commands


bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins deps
openclaw plugins deps --repair
openclaw plugins deps --prune
openclaw plugins deps --json
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json

For slow install, inspect, uninstall, or registry-refresh investigation, run the command with

text

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1

. The trace writes phase timings to stderr and keeps JSON output parseable. See Debugging.

note

Bundled plugins ship with OpenClaw. Some are enabled by default (for example bundled model providers, bundled speech providers, and the bundled browser plugin); others require `plugins enable`.

Native OpenClaw plugins must ship

text

openclaw.plugin.json

with an inline JSON Schema (

text

configSchema

, even if empty). Compatible bundles use their own bundle manifests instead.

text

plugins list

shows

text

Format: openclaw

text

Format: bundle

. Verbose list/info output also shows the bundle subtype (

text

codex

text

claude

, or

text

cursor

) plus detected bundle capabilities.

Install


bash
openclaw plugins install <package>                      # ClawHub first, then npm
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install npm:<package>                  # npm only
openclaw plugins install <package> --force              # overwrite existing install
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

warning

Bare package names are checked against ClawHub first, then npm. Treat plugin installs like running code. Prefer pinned versions.

note

ClawHub is the primary distribution and discovery surface for most plugins. Npm remains a supported fallback and direct-install path. During the migration to ClawHub, OpenClaw still ships some OpenClaw-owned `@openclaw/*` plugin packages on npm; those package versions can lag the bundled source between plugin release trains. If npm reports an OpenClaw-owned plugin package as deprecated, that published version is an old external artifact; use the plugin bundled with current OpenClaw or a local checkout until a newer npm package is published.

ClawHub installs use an explicit

text

clawhub:<package>

locator:


bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

OpenClaw now also prefers ClawHub for bare npm-safe plugin specs. It only falls back to npm if ClawHub does not have that package or version:


bash
openclaw plugins install openclaw-codex-app-server

Use

text

npm:

to force npm-only resolution, for example when ClawHub is unreachable or you know the package exists only on npm:


bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1

OpenClaw downloads the package archive from ClawHub, checks the advertised plugin API / minimum gateway compatibility, then installs it through the normal archive path. Recorded installs keep their ClawHub source metadata for later updates. Unversioned ClawHub installs keep an unversioned recorded spec so

text

openclaw plugins update

can follow newer ClawHub releases; explicit version or tag selectors such as

text

clawhub:pkg@1.2.3

and

text

clawhub:pkg@beta

remain pinned to that selector.

Marketplace shorthand

Use

text

plugin@marketplace

shorthand when the marketplace name exists in Claude's local registry cache at

text

~/.claude/plugins/known_marketplaces.json


bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

Use

text

--marketplace

when you want to pass the marketplace source explicitly:


bash
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

* 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 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:

native OpenClaw plugins (
text
openclaw.plugin.json
)
Codex-compatible bundles (
text
.codex-plugin/plugin.json
)
Claude-compatible bundles (
text
.claude-plugin/plugin.json
or the default Claude component layout)
Cursor-compatible bundles (
text
.cursor-plugin/plugin.json
)

note

Compatible bundles install into the normal plugin root and participate in the same list/info/enable/disable flow. Today, bundle skills, Claude command-skills, Claude `settings.json` defaults, Claude `.lsp.json` / manifest-declared `lspServers` 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.

List


bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json

Show only enabled plugins. Switch from the table view to per-plugin detail lines with source/origin/version/activation metadata. Machine-readable inventory plus registry diagnostics.

note

`plugins list` reads the persisted local plugin registry first, with a manifest-only derived fallback when the registry is missing or invalid. It 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/container deployments, verify you are restarting the actual `openclaw gateway run` child, not only a wrapper process.

For bundled plugin work inside a packaged Docker image, bind-mount the plugin source directory over the matching packaged source path, such as

text

/app/extensions/synology-chat

. OpenClaw will discover that mounted source overlay before

text

/app/dist/extensions/synology-chat

; a plain copied source directory remains inert so normal packaged installs still use compiled dist.

For runtime hook debugging:

text
openclaw plugins inspect <id> --json
shows registered hooks and diagnostics from a module-loaded inspection pass.
text
openclaw gateway status --deep --require-rpc
confirms the reachable Gateway, service/process hints, config path, and RPC health.
Non-bundled conversation hooks (
text
llm_input
,
text
llm_output
,
text
before_agent_finalize
,
text
agent_end
) require
text
plugins.entries.<id>.hooks.allowConversationAccess=true
.

Use

text

--link

to avoid copying a local directory (adds to

text

plugins.load.paths


bash
openclaw plugins install -l ./my-plugin

note

`--force` is not supported with `--link` because linked installs reuse the source path instead of copying over a managed install target.

Use

text

--pin

on npm installs to save the resolved exact spec (

text

name@version

) in the managed plugin index while keeping the default behavior unpinned.

Plugin index

Plugin install metadata is machine-managed state, not user config. Installs and updates write it to

text

plugins/installs.json

under the active OpenClaw state directory. Its top-level

text

installRecords

map is the durable source of install metadata, including records for broken or missing plugin manifests. The

text

plugins

array is the manifest-derived cold registry cache. The file includes a do-not-edit warning and is used by

text

openclaw plugins update

, uninstall, diagnostics, and the cold plugin registry.

When OpenClaw sees shipped legacy

text

plugins.installs

records in config, it moves them into the plugin index and removes the config key; if either write fails, the config records are kept so the install metadata is not lost.

Runtime deps


bash
openclaw plugins deps
openclaw plugins deps --repair
openclaw plugins deps --prune
openclaw plugins deps --json

text

plugins deps

inspects the packaged runtime dependency stage for OpenClaw-owned bundled plugins selected by plugin config, enabled/configured channels, configured model providers, or bundled manifest defaults. It is not the install/update path for third-party npm or ClawHub plugins.

Use

text

--repair

when a packaged install reports missing bundled runtime dependencies during Gateway startup or

text

plugins doctor

. Repair installs only missing enabled bundled-plugin deps with lifecycle scripts disabled. Use

text

--prune

to remove stale unknown external runtime-dependency roots left behind by older packaged layouts.

Uninstall


bash
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files

text

uninstall

removes plugin records from

text

plugins.entries

, the persisted plugin index, plugin allow/deny list entries, and linked

text

plugins.load.paths

entries when applicable. Unless

text

--keep-files

is set, uninstall also removes the tracked managed install directory when it is inside OpenClaw's plugin extensions root. For active memory plugins, the memory slot resets to

text

memory-core

note

`--keep-config` is supported as a deprecated alias for `--keep-files`.

Update


bash
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@beta
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

text

hooks.internal.installs

Inspect


bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json

Deep introspection for a single plugin. Shows identity, load status, source, registered capabilities, hooks, tools, commands, services, gateway methods, HTTP routes, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support.

Each plugin is classified by what it actually registers at runtime:

plain-capability — one capability type (e.g. a provider-only plugin)
hybrid-capability — multiple capability types (e.g. text + speech + images)
hook-only — only hooks, no capabilities or surfaces
non-capability — tools/commands/services but no capabilities

See Plugin shapes for more on the capability model.

note

The `--json` flag outputs a machine-readable report suitable for scripting and auditing. `inspect --all` renders a fleet-wide table with shape, capability kinds, compatibility notices, bundle capabilities, and hook summary columns. `info` is an alias for `inspect`.

Doctor


bash
openclaw plugins doctor

text

doctor

reports plugin load errors, manifest/discovery diagnostics, and compatibility notices. When everything is clean it prints

text

No plugin issues detected.

For module-shape failures such as missing

text

register

text

activate

exports, rerun with

text

OPENCLAW_PLUGIN_LOAD_DEBUG=1

to include a compact export-shape summary in the diagnostic output.

Registry


bash
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

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

Use

text

plugins registry

to inspect whether the persisted registry is present, current, or stale. Use

text

--refresh

to rebuild it from the persisted plugin index, config policy, and manifest/package metadata. This is a repair path, not a runtime activation path.

warning

`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` is a deprecated break-glass compatibility switch for registry read failures. Prefer `plugins registry --refresh` or `openclaw doctor --fix`; the env fallback is only for emergency startup recovery while the migration rolls out.

Marketplace


bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

Marketplace list accepts a local marketplace path, a

text

marketplace.json

path, a GitHub shorthand like

text

owner/repo

, a GitHub repo URL, or a git URL.

text

--json

prints the resolved source label plus the parsed marketplace manifest and plugin entries.

OpenClaw Docs

Plugins

Plugin system

Plugin bundles

Plugin manifest

Security

Commands

note

Install

warning

note

Marketplace shorthand

note

List

note

note

Plugin index

Runtime deps

Uninstall

note

Update

Inspect

note

Doctor

Registry

warning

Marketplace

Related