vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-29 19:43:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 29
openclaw/docs/cli/plugins.md
Vincent Koc 32af0c610d
fix: drain accepted QA suites and cancel refused plugin retries (#158087) 
Keep accepted QA Lab suites alive through shutdown by closing admission before awaited planning and joining the existing suite promise before retiring Gateway, bus, and capture resources. New mutable work receives a visible stopping response; accepted work retains its original execution deadlines.

Require the recorded correlated Gateway response before retrying an explicit pre-admission plugin refusal, and use the existing signal-exit gate for every lifecycle mutation wait. Interruptions stop further dispatch without replaying accepted or uncertain effects. Preserve the ten-minute admission budget and the admitted reload --wait contract.

Retain bounded failure-only runtime timing and cleanup-owner diagnostics without changing workload, assertions, deadlines, or physical cleanup. The final production delta is eight lines after simplifying the CLI's conditional cancellation branches.

Validated with the actual HTTP regressions, all 19 plugin CLI cases, complete reconnect/worker-wire/telemetry runtime flows, fresh independent P0-P2 review, and exact-head successful CI (89 jobs). Preserve the limitations of unexplained historical timeouts; passing replays do not establish their cause.

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
2026-10-13 17:05:21 -07:00

11 KiB
Raw Blame History

summary read_when title sidebarTitle
CLI reference for `openclaw plugins` (init, build, validate, list, install, reload, marketplace, uninstall, enable/disable, doctor)
You want to install or manage Gateway plugins or compatible bundles
You want to scaffold or validate a simple tool plugin
You want to debug plugin load failures
Plugins CLI Plugins

openclaw plugins

Manage Gateway plugins, hook packs, and compatible bundles.

Install, uninstall, enable, disable, and reload use their existing Gateway routes when a Gateway is running. Local fallbacks require exclusive offline state ownership. Stop the Gateway through its service owner before running plugins update, plugins registry --refresh, marketplace feed refreshes, or hook-pack install fallbacks. plugins marketplace entries --offline reads the saved feed without refreshing it. Refused commands report how to retry.

While a plugin or config operation is running, the CLI waits and retries only if the Gateway confirms that it did not accept the mutation. Admission stays within the command's existing ten-minute budget, including plugins reload --wait. Interrupting the command cancels pending admission retries. An already accepted mutation may still finish; inspect plugin status before retrying it. Lost replies and failures after acceptance are reported without automatic replay; inspect plugin status before retrying them. Older Gateways that do not provide the admission fact keep the explicit busy response.

If a command encounters offline database maintenance, it reports the reason without OPENCLAW_DEBUG. Wait for maintenance to finish, then retry the command.

plugins enable and plugins disable accept case-insensitive plugin IDs, including when the Gateway is stopped. Reported IDs retain their manifest spelling; plugin policy keys in config use the required lowercase form. The same policy applies to live activation and the next Gateway start. Runtime IDs and Gateway method names retain the plugin's declared spelling.

End-user guide for installing, enabling, and troubleshooting plugins. Quick examples for install, list, update, uninstall, and publishing. Bundle compatibility model. Manifest fields and config schema. Security hardening for plugin installs.

Commands

openclaw plugins list [--enabled] [--verbose] [--json]
openclaw plugins search <query> [--limit <n>] [--json]
openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--no-enable] [--accept-capabilities] [--acknowledge-install-policy-warning] [--marketplace <source>]
openclaw plugins inspect <id> [--runtime] [--json]
openclaw plugins inspect --all [--runtime] [--json]
openclaw plugins info <id>                    # alias for inspect
openclaw plugins enable <ids...> [--accept-capabilities]
openclaw plugins disable <ids...>
openclaw plugins reload <ids...> [--wait] [--accept-capabilities] [--json]
openclaw plugins uninstall <ids...> [--dry-run] [--keep-files] [--force]
openclaw plugins update <ids-or-npm-specs...> | --all [--dry-run]
openclaw plugins registry [--refresh] [--json]
openclaw plugins doctor [--json]
openclaw plugins init <id> [--name <name>] [--type tool|provider|feature] [--directory <path>]
openclaw plugins build [--root <path>] [--entry <path>] [--check]
openclaw plugins validate [--root <path>] [--entry <path>] [--json]
openclaw plugins pack [--root <path>] [--out <file.tgz>] [--json]
openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]
openclaw plugins marketplace list <source> [--json]
openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

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.

In Nix mode (`OPENCLAW_NIX_MODE=1`), `openclaw.json` is immutable. `install`, `update`, `uninstall`, `enable`, and `disable` all refuse to run. Manage those choices in the Nix source for this install (`programs.openclaw.config` or `instances..config` for nix-openclaw), then rebuild. Reload remains available when no new capability consent needs to be recorded; it preserves config and installation state. See the agent-first [Quick Start](https://github.com/openclaw/nix-openclaw#quick-start). Bundled plugins ship with OpenClaw. A little over half are enabled by default — mostly model and speech providers, plus a few others such as the bundled browser plugin. Other bundled plugins need explicit enablement or relevant configuration. Enabled does not mean currently in use. Provider use depends on configuration and requests. Providers that require authentication need credentials; keyless providers such as Microsoft speech do not. An enabled entry in `plugins list` does not mean the plugin is doing work.

Native OpenClaw plugins 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 (agent (Agent Plugins), codex, claude, or cursor) plus detected bundle capabilities.

Plugins pages

This page is an index. openclaw plugins is documented on six pages, one per reader job. Open the page that matches your task.

Page Read it when
Author plugins You are creating, building, validating, or packing a plugin project.
Install plugins You are installing from ClawHub, npm, git, a path, an archive, or a marketplace.
List installed plugins You want the installed inventory, discovery diagnostics, or the plugin index.
Uninstall and update plugins You are removing or reloading a plugin, or updating its version and source.
Inspect and diagnose plugins You need plugin identity, runtime registrations, load errors, or registry state.
Marketplace feeds You are browsing, listing, or refreshing a marketplace or hosted signed feed.

Where each section moved

Every section anchor from the previous single-page version keeps its id here, so an existing link such as /cli/plugins#registry still resolves. Each entry points at the page that now holds the content.

Related