Manage Gateway plugins, hook packs, and compatible bundles.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. The trace writes phase timings
to stderr and keeps JSON output parseable. See Debugging.
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 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
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.Config includes and invalid-config recovery
Config includes and invalid-config recovery
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, invalid config for one plugin is isolated to that plugin so other channels and plugins can keep running; 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 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 <id-or-npm-spec>.If you run plugins install for a plugin id that is already installed, OpenClaw stops and points you at plugins update <id-or-npm-spec> for a normal upgrade, or at plugins install <package> --force when you genuinely want to overwrite the current install from a different source.--pin scope
--pin scope
--pin applies to npm installs only. 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
--dangerously-force-unsafe-install is a break-glass option for false positives in the built-in dangerous-code scanner. It allows the install to continue even when the built-in scanner reports critical findings, but it does not bypass plugin before_install hook policy blocks and does not bypass scan failures.This CLI flag applies to plugin install/update flows. Gateway-backed skill dependency installs use the matching dangerouslyForceUnsafeInstall request override, while openclaw skills install remains a separate ClawHub skill download/install flow.If a plugin you published on ClawHub is blocked by a registry scan, use the publisher steps in ClawHub.Hook packs and npm specs
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 project-local with --ignore-scripts for safety, even when your shell has global npm install settings.Use npm:<package> when you want to skip ClawHub lookup and install directly from npm. Bare package specs still prefer ClawHub and only fall back to npm when ClawHub does not have that package or version.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).Archives
Archives
Supported archives:
.zip, .tgz, .tar.gz, .tar. Native OpenClaw plugin archives must contain a valid openclaw.plugin.json at the extracted plugin root; archives that only contain package.json are rejected before OpenClaw writes install records.Claude marketplace installs are also supported.clawhub:<package> locator:
npm: to force npm-only resolution, for example when ClawHub is unreachable or you know the package exists only on npm:
openclaw plugins update can follow newer ClawHub releases; explicit version or tag selectors such as clawhub:pkg@1.2.3 and clawhub:pkg@beta remain pinned to that selector.
Marketplace shorthand
Useplugin@marketplace shorthand when the marketplace name exists in Claude’s local registry cache at ~/.claude/plugins/known_marketplaces.json:
--marketplace when you want to pass the marketplace source explicitly:
- Marketplace sources
- Remote marketplace rules
- a Claude known-marketplace name from
~/.claude/plugins/known_marketplaces.json - a local marketplace root or
marketplace.jsonpath - a GitHub repo shorthand such as
owner/repo - a GitHub repo URL such as
https://github.com/owner/repo - a git URL
- 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 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
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.
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./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 <id> --jsonshows registered hooks and diagnostics from a module-loaded inspection pass.openclaw gateway status --deep --require-rpcconfirms the reachable Gateway, service/process hints, config path, and RPC health.- Non-bundled conversation hooks (
llm_input,llm_output,before_agent_finalize,agent_end) requireplugins.entries.<id>.hooks.allowConversationAccess=true.
--link to avoid copying a local directory (adds to plugins.load.paths):
--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 toplugins/installs.json under the active OpenClaw state directory. Its top-level installRecords map is the durable source of install metadata, including records for broken or missing plugin manifests. The plugins array is the manifest-derived cold registry cache. The file includes a do-not-edit warning and is used by openclaw plugins update, uninstall, diagnostics, and the cold plugin registry.
When OpenClaw sees shipped legacy 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
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 --repair when a packaged install reports missing bundled runtime dependencies during Gateway startup or plugins doctor. Repair installs only missing enabled bundled-plugin deps with lifecycle scripts disabled. Use --prune to remove stale unknown external runtime-dependency roots left behind by older packaged layouts.
Uninstall
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.
--keep-config is supported as a deprecated alias for --keep-files.Update
hooks.internal.installs.
Resolving plugin id vs npm spec
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 <id> runs.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.Version checks and integrity drift
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 on update
--dangerously-force-unsafe-install is also available on plugins update as a break-glass override for built-in dangerous-code scan false positives during plugin updates. It still does not bypass plugin before_install policy blocks or scan-failure blocking, and it only applies to plugin updates, not hook-pack updates.Inspect
- 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
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
doctor reports plugin load errors, manifest/discovery diagnostics, and compatibility notices. When everything is clean it prints No plugin issues detected.
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
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.
Marketplace
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.