Plugins

Manage Gateway plugins, hook packs, and compatible bundles.

Plugin system

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

Manage plugins

Quick examples for install, list, update, uninstall, and publishing.

Plugin bundles

Bundle compatibility model.

Plugin manifest

Manifest fields and config schema.

Security

Security hardening for plugin installs.

Commands

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
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 doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace entries
openclaw plugins marketplace entries --offline
openclaw plugins marketplace entries --json
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
openclaw plugins marketplace refresh
openclaw plugins marketplace refresh --feed-profile clawhub-public --json
openclaw plugins marketplace refresh --feed-url https://clawhub.ai/v1/feeds/plugins --expected-sha256 <sha256>
openclaw plugins init my-tool --name "My Tool"
openclaw plugins init my-provider --name "My Provider" --type provider
openclaw plugins init my-provider --name "My Provider" --type provider --directory ./my-provider
openclaw plugins build --entry ./dist/index.js
openclaw plugins build --entry ./dist/index.js --check
openclaw plugins validate --entry ./dist/index.js

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.

Author

openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate

plugins init creates a minimal TypeScript tool plugin by default. The first argument is the plugin id; pass --name for the display name. OpenClaw uses the id for the default output directory and package naming. Tool scaffolds use defineToolPlugin. plugins build imports the built entry, reads its static tool metadata, writes openclaw.plugin.json, and keeps package.json openclaw.extensions aligned. plugins validate checks that the generated manifest, package metadata, and current entry export still agree. See Tool Plugins for the full tool-authoring workflow.

The scaffold writes TypeScript source but generates metadata from the built ./dist/index.js entry so the workflow also works with the published CLI. Use `—entry

when the entry is not the default package entry. Useplugins build —check` in CI to fail when generated metadata is stale without rewriting files.

Provider Scaffold

openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate

Provider scaffolds create a generic text/model provider plugin with OpenAI-compatible API-key plumbing, a built-in npm run validate script for clawhub package validate, ClawHub package metadata, and a manually dispatched GitHub workflow for future trusted publishing through GitHub Actions OIDC. Provider scaffolds do not generate skills and do not use openclaw plugins build or openclaw plugins validate; those commands are for the tool scaffold’s generated metadata path.

Before publishing, replace the placeholder API base URL, model catalog, docs route, credential text, and README copy with real provider details. Use the generated README for first-time ClawHub publishing and trusted publisher setup.

Install

openclaw plugins search "calendar"                   # search ClawHub plugins
openclaw plugins install

                  # source auto-detection

openclaw plugins install clawhub:

          # ClawHub only

openclaw plugins install npm:

              # npm only

openclaw plugins install npm-pack:

        # local npm pack through npm install semantics

openclaw plugins install git:github.com/

git repo

openclaw plugins install git:github.com/

openclaw plugins install

—force # overwrite existing install openclaw plugins install

—pin # pin version openclaw plugins install clawhub:

—acknowledge-clawhub-risk openclaw plugins install

—dangerously-force-unsafe-install openclaw plugins install

                     # local path

openclaw plugins install

     # marketplace

openclaw plugins install

—marketplace

marketplace (explicit)

openclaw plugins install

—marketplace https://github.com/

Maintainers testing setup-time installs can override automatic plugin install
sources with guarded environment variables. See
[Plugin install overrides](/en/plugins/install-overrides).

plugins search queries ClawHub for installable plugin packages and prints install-ready package names. It searches code-plugin and bundle-plugin packages, not skills. Use openclaw skills search for ClawHub skills.

Config includes and invalid-config repair

If your plugins section is backed by a single-file $include, plugins install/update/enable/disable/uninstall write through to that included file and leave openclaw.json untouched. Root includes, include arrays, and includes with sibling overrides fail closed instead of flattening. See Config includes for the supported shapes.

If config is invalid during install, plugins install normally fails closed and tells you to run openclaw doctor --fix first. During Gateway startup and hot reload, invalid plugin config fails closed like any other invalid config; openclaw doctor --fix can quarantine the invalid plugin entry. The only documented install-time exception is a narrow bundled-plugin recovery path for plugins that explicitly opt into openclaw.install.allowInvalidConfigRecovery.

--force and reinstall vs update

--force reuses the existing install target and overwrites an already-installed plugin or hook pack in place. Use it when you are intentionally reinstalling the same id from a new local path, archive, ClawHub package, or npm artifact. For routine upgrades of an already tracked npm plugin, prefer `openclaw plugins update

If you run `plugins install` for a plugin id that is already installed, OpenClaw stops and points you at `plugins update

for a normal upgrade, or atplugins install

—force` when you genuinely want to overwrite the current install from a different source.

--pin scope

--pin applies to npm installs only. It is not supported with git: installs; use an explicit git ref such as git:github.com/acme/[email protected] when you want a pinned source. It is not supported with --marketplace, because marketplace installs persist marketplace source metadata instead of an npm spec.

--dangerously-force-unsafe-install

--dangerously-force-unsafe-install is deprecated and is now a no-op. OpenClaw no longer runs built-in install-time dangerous-code blocking for plugin installs.

Use the shared operator-owned security.installPolicy surface when host-specific install policy is required. Plugin before_install hooks are plugin-runtime lifecycle hooks and are not the primary policy boundary for CLI installs.

If a plugin you published on ClawHub is hidden or blocked by a registry scan, use the publisher steps in ClawHub publishing. --dangerously-force-unsafe-install does not ask ClawHub to rescan the plugin or make a blocked release public.

--acknowledge-clawhub-risk

Community ClawHub installs check the selected release trust record before downloading the package. If ClawHub disables download for the release, reports malicious scan findings, or puts the release in a blocking moderation state such as quarantine, OpenClaw refuses the release. For non-blocking risky scan statuses, risky moderation states, or registry reasons, OpenClaw shows the trust details and asks for confirmation before continuing.

Use --acknowledge-clawhub-risk only after reviewing the ClawHub warning and deciding to continue without an interactive prompt. Pending or stale clean trust records warn but do not require acknowledgement. Official ClawHub packages and bundled OpenClaw plugin sources bypass this release-trust prompt.

Hook packs and npm specs

plugins install is also the install surface for hook packs that expose openclaw.hooks in package.json. Use openclaw hooks for filtered hook visibility and per-hook enablement, not package installation.

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 in one managed npm project per plugin with --ignore-scripts for safety, even when your shell has global npm install settings. Managed plugin npm projects inherit OpenClaw’s package-level npm overrides, so host security pins apply to hoisted plugin dependencies too.

Use `npm:

` when you want to make npm resolution explicit. Bare package specs also install directly from npm during the launch cutover unless they match an official plugin id.

Raw `@openclaw/*` package specs that match bundled plugins resolve to the image-owned bundled copy before npm fallback. For example, `openclaw plugins install @openclaw/[email protected] --pin` uses the bundled Discord plugin from the current OpenClaw build instead of creating a managed npm override. To force the external npm package, use `openclaw plugins install npm:@openclaw/[email protected] --pin`.

Bare specs and `@latest` stay on the stable track. OpenClaw date-stamped correction versions such as `2026.5.3-1` are stable releases for this check. 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`.

For npm installs without an exact version (`npm:

ornpm:

@latest), OpenClaw checks the resolved package metadata before install. If the latest stable package requires a newer OpenClaw plugin API or minimum host version, OpenClaw inspects older stable versions and installs the newest compatible release instead. Exact versions and explicit dist-tags such as @beta` remain strict: if the selected package is incompatible, the command fails and asks you to upgrade OpenClaw or choose a compatible version.

If a bare install spec matches an official plugin id (for example `diffs`), OpenClaw installs the catalog entry directly. To install an npm package with the same name, use an explicit scoped spec (for example `@scope/diffs`).

Git repositories

Use `git:

to install directly from a git repository. Supported forms includegit:github.com/owner/repo, git:owner/repo, full https://, ssh://, git://, file://, and git@host:owner/repo.gitclone URLs. Add@

or#

` to check out a branch, tag, or commit before install.

Git installs clone into a temporary directory, check out the requested ref when present, then use the normal plugin directory installer. That means manifest validation, operator install policy, package-manager install work, and install records behave like npm installs. Recorded git installs include the source URL/ref plus the resolved commit so `openclaw plugins update` can re-resolve the source later.

After installing from git, use `openclaw plugins inspect

—runtime —jsonto verify runtime registrations such as gateway methods and CLI commands. If the plugin registered a CLI root withapi.registerCli, execute that command directly through the OpenClaw root CLI, for example openclaw demo-plugin ping`.

Marketplace shorthand

Use plugin@marketplace shorthand when the marketplace name exists in Claude’s local registry cache at ~/.claude/plugins/known_marketplaces.json:

openclaw plugins marketplace list

openclaw plugins install

Use `--marketplace` when you want to pass the marketplace source explicitly:

```bash
openclaw plugins install

—marketplace

openclaw plugins install

—marketplace

openclaw plugins install

—marketplace https://github.com/

openclaw plugins install

—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 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.json or the default Claude component layout)
Cursor-compatible bundles (.cursor-plugin/plugin.json)

Managed local installs must be plugin directories or archives. Standalone .js, .mjs, .cjs, and .ts plugin files are not copied into the managed plugin root by plugins install; list them explicitly in plugins.load.paths instead.

List

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search

openclaw plugins search

—limit 20 openclaw plugins search

—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 and package dependency install state.

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.

plugins list --json includes each plugin’s dependencyStatus from package.json dependencies and optionalDependencies. OpenClaw checks whether those package names are present along the plugin’s normal Node node_modules lookup path; it does not import plugin runtime code, run a package manager, or repair missing dependencies.

If startup logs plugins.allow is empty; discovered non-bundled plugins may auto-load: ..., run openclaw plugins list --enabled --verbose or `openclaw plugins inspect

with a listed plugin id to confirm the plugin ids and copy trusted ids intoplugins.allowinopenclaw.json. When the warning can list every discovered plugin, it prints a ready-to-paste plugins.allowsnippet that already includes those ids. If a plugin loads without install/load-path provenance, inspect that plugin id, then either pin the trusted id inplugins.allow` or reinstall the plugin from a trusted source so OpenClaw records install provenance.

plugins search is a remote ClawHub catalog lookup. It does not inspect local state, mutate config, install packages, or load plugin runtime code. Search results include the ClawHub package name, family, channel, version, summary, and an install hint such as `openclaw plugins install clawhub:

For bundled plugin work inside a packaged Docker image, bind-mount the plugin source directory over the matching packaged source path, such as /app/extensions/synology-chat. OpenClaw will discover that mounted source overlay before /app/dist/extensions/synology-chat; a plain copied source directory remains inert so normal packaged installs still use compiled dist.

For runtime hook debugging:

`openclaw plugins inspect

—runtime —jsonshows registered hooks and diagnostics from a module-loaded inspection pass. Runtime inspection never installs dependencies; useopenclaw doctor —fix` to clean legacy dependency state or recover missing downloadable plugins that are referenced by config.

openclaw gateway status --deep --require-rpc confirms the reachable Gateway URL/profile, service/process hints, config path, and RPC health.
Non-bundled conversation hooks (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) require `plugins.entries.

.hooks.allowConversationAccess=true`.

Use --link to avoid copying a local plugin directory (adds to plugins.load.paths):

openclaw plugins install -l ./my-plugin

Standalone plugin files must be listed in plugins.load.paths rather than installed with plugins install or placed directly in ~/.openclaw/extensions or `

/.openclaw/extensions`. Those auto-discovered roots load plugin package or bundle directories, while top-level script files are treated as local helpers and skipped.

Note

Workspace-origin plugins discovered from a workspace extensions root are not imported or executed until they are explicitly enabled. For local development, run `openclaw plugins enable

or setplugins.entries.

.enabled: true; if your config uses plugins.allow, include the same plugin id there too. This fail-closed rule also applies when channel setup explicitly targets a workspace-origin plugin for setup-only loading, so local channel plugin setup code will not run while that workspace plugin remains disabled or excluded from the allowlist. Linked installs and explicit plugins.load.paths` entries follow the normal policy for their resolved plugin origin. See Configure plugin policy and Configuration reference.

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

Use --pin on npm installs to save the resolved exact spec (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 the shared SQLite state database under the active OpenClaw state directory. The installed_plugin_index row stores durable installRecords metadata, including records for broken or missing plugin manifests, plus a manifest-derived cold registry cache used by openclaw plugins update, uninstall, diagnostics, and the cold plugin registry.

When OpenClaw sees shipped legacy plugins.installs records in config, runtime reads treat them as compatibility input without rewriting openclaw.json. Explicit plugin writes and openclaw doctor --fix move those records into the plugin index and remove the config key when config writes are allowed; if either write fails, the config records are kept so the install metadata is not lost.

Uninstall

openclaw plugins uninstall

openclaw plugins uninstall

—dry-run openclaw plugins uninstall

—keep-files

`uninstall` removes plugin records from `plugins.entries`, the persisted plugin index, plugin allow/deny list entries, and linked `plugins.load.paths` entries when applicable. Unless `--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 `memory-core`.

Update

openclaw plugins update

openclaw plugins update —all openclaw plugins update

—dry-run openclaw plugins update @openclaw/voice-call openclaw plugins update openclaw-codex-app-server —acknowledge-clawhub-risk 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 `hooks.internal.installs`.

Resolving plugin id vs npm spec

When you pass a plugin id, OpenClaw reuses the recorded install spec for that plugin. That means previously stored dist-tags such as @beta and exact pinned versions continue to be used on later `update

` runs.

During `update

—dry-run, exact pinned npm installs stay pinned. If OpenClaw can also resolve the package's registry default line and that default line is newer than the installed pinned version, the dry run reports the pin and prints the explicit @latest` package update command to follow the registry default line.

That targeted-update rule is different from the bulk openclaw plugins update --all maintenance path. Bulk updates still respect ordinary tracked install specs, but trusted official OpenClaw plugin records can sync to the current official catalog target instead of staying on a stale exact official package. Use targeted `update

` when you intentionally want to keep an exact or tagged official spec untouched.

For npm installs, you can also pass an explicit npm package spec with a dist-tag or exact version. OpenClaw resolves that package name back to the tracked plugin record, updates that installed plugin, and records the new npm spec for future id-based updates.

Passing the npm package name without a version or tag also resolves back to the tracked plugin record. Use this when a plugin was pinned to an exact version and you want to move it back to the registry's default release line.

Beta channel updates

Targeted `openclaw plugins update

reuses the tracked plugin spec unless you pass a new spec. Bulkopenclaw plugins update —alluses the configuredupdate.channel` when it syncs trusted official plugin records to the official catalog target, so beta-channel installs can stay on the beta release line instead of being silently normalized to stable/latest.

`openclaw update` also knows the active OpenClaw update channel: on the beta channel, default-line npm and ClawHub plugin records try `@beta` first. They fall back to the recorded default/latest spec if no plugin beta release exists; npm plugins also fall back when the beta package exists but fails install validation. That fallback is reported as a warning and does not fail the core update. Exact versions and explicit tags stay pinned to that selector for targeted updates.

Version checks and integrity drift

Before a live npm update, OpenClaw checks the installed package version against the npm registry metadata. If the installed version and recorded artifact identity already match the resolved target, the update is skipped without downloading, reinstalling, or rewriting openclaw.json.

When a stored integrity hash exists and the fetched artifact hash changes, OpenClaw treats that as npm artifact drift. The interactive openclaw plugins update command prints the expected and actual hashes and asks for confirmation before proceeding. Non-interactive update helpers fail closed unless the caller supplies an explicit continuation policy.

--dangerously-force-unsafe-install on update

--dangerously-force-unsafe-install is also accepted on plugins update for compatibility, but it is deprecated and no longer changes plugin update behavior. Operator security.installPolicy can still block updates; plugin before_install hooks only apply in processes where plugin hooks are loaded.

--acknowledge-clawhub-risk on update

Community ClawHub-backed plugin updates run the same exact-release trust check as installs before downloading the replacement package. Use --acknowledge-clawhub-risk for reviewed automation that should continue when the selected ClawHub release has a risky trust warning. Official ClawHub packages and bundled OpenClaw plugin sources bypass this release-trust prompt.

Inspect

openclaw plugins inspect

openclaw plugins inspect

—runtime openclaw plugins inspect

—json

Inspect shows identity, load status, source, manifest capabilities, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support without importing plugin runtime by default. JSON output includes the plugin manifest contracts, such as `contracts.agentToolResultMiddleware` and `contracts.trustedToolPolicies`, so operators can audit trusted-surface declarations before enabling or restarting a plugin. Add `--runtime` to load the plugin module and include registered hooks, tools, commands, services, gateway methods, and HTTP routes. Runtime inspection reports missing plugin dependencies directly; installs and repairs stay in `openclaw plugins install`, `openclaw plugins update`, and `openclaw doctor --fix`.

Plugin-owned CLI commands are usually installed as root `openclaw` command groups, but plugins may also register nested commands under a core parent such as `openclaw nodes`. After `inspect --runtime` shows a command under `cliCommands`, run it at the listed path; for example a plugin that registers `demo-git` can be verified with `openclaw demo-git ping`.

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](/en/plugins/architecture#plugin-shapes) for more on the capability model.

Doctor

openclaw plugins doctor

doctor reports plugin load errors, manifest/discovery diagnostics, compatibility notices, and stale plugin config references such as missing plugin slots. When the install tree and plugin config are clean it prints No plugin issues detected. If stale config remains but the install tree is otherwise healthy, the summary says so instead of implying full plugin health.

If a configured plugin is present on disk but blocked by the loader’s path-safety checks, config validation keeps the plugin entry and reports it as present but blocked. Fix the preceding blocked-plugin diagnostic, such as path ownership or world-writable permissions, instead of removing the `plugins.entries.

orplugins.allow` config.

For module-shape failures such as missing register/activate exports, rerun with OPENCLAW_PLUGIN_LOAD_DEBUG=1 to include a compact export-shape summary in the diagnostic output.

Registry

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 plugins registry to inspect whether the persisted registry is present, current, or stale. Use --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.

openclaw doctor --fix also repairs registry-adjacent managed npm drift: if an orphaned or recovered @openclaw/* package under a managed plugin npm project or the legacy flat managed npm root shadows a bundled plugin, doctor removes that stale package and rebuilds the registry so startup validates against the bundled manifest. Doctor also relinks the host openclaw package into managed npm plugins that declare peerDependencies.openclaw, so package-local runtime imports such as openclaw/plugin-sdk/* resolve after updates or npm repairs.

Marketplace

openclaw plugins marketplace entries
openclaw plugins marketplace entries --offline
openclaw plugins marketplace entries --json
openclaw plugins marketplace entries --feed-profile

openclaw plugins marketplace entries —feed-url

openclaw plugins marketplace list

—json openclaw plugins marketplace refresh openclaw plugins marketplace refresh —feed-profile

openclaw plugins marketplace refresh —feed-url

openclaw plugins marketplace refresh —expected-sha256

—json

`plugins marketplace entries` lists entries from the configured OpenClaw marketplace feed. By default it attempts the hosted feed and falls back to the latest accepted snapshot or bundled data. Use `--feed-profile

to read a specific configured profile,—feed-url

to read an explicit hosted feed URL, and—offline` to read the latest accepted snapshot without fetching the feed.

plugins marketplace refresh refreshes the configured hosted feed snapshot and reports whether OpenClaw accepted hosted data, a hosted snapshot, or bundled fallback data. Use --expected-sha256 when a caller needs the command to fail unless a fresh hosted payload matches a pinned checksum.

Marketplace list accepts a local marketplace path, a marketplace.json path, a GitHub shorthand like owner/repo, a GitHub repo URL, or a git URL. --json prints the resolved source label plus the parsed marketplace manifest and plugin entries.

Marketplace refresh loads a hosted OpenClaw marketplace feed and persists the validated response as the local hosted-feed snapshot. Without options, it uses the configured default feed profile. Use `—feed-profile

to refresh a specific configured profile,—feed-url

to refresh an explicit hosted feed URL,—expected-sha256

to require a matching payload checksum (sha256:

or a bare 64-character hex digest), and—json` for machine-readable output. Explicit hosted feed URLs must not include credentials, query strings, or fragments. Unpinned refreshes can report a hosted snapshot or bundled fallback result without failing the command. Pinned refreshes fail unless they accept a fresh hosted payload, and successful hosted refreshes fail if OpenClaw cannot persist the validated snapshot.

Plugins

Commands

Author

Provider Scaffold

Install

git repo

marketplace (explicit)

Marketplace shorthand

List

Plugin index

Uninstall

Update

Inspect

Doctor

Registry

Marketplace

Related