From fb293fa36fad51f844116caca385ef8824bd6bde Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Fri, 20 Mar 2026 11:20:36 -0700 Subject: [PATCH] docs: rewrite plugins install/configure page with Steps, Accordions, and clear hierarchy --- docs/tools/plugin.md | 393 +++++++++++++++++-------------------------- 1 file changed, 153 insertions(+), 240 deletions(-) diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 9b61c2ee015..b30463ce270 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -1,5 +1,5 @@ --- -summary: "OpenClaw plugins: install, configure, and manage plugins that extend the gateway" +summary: "Install, configure, and manage OpenClaw plugins" read_when: - Installing or configuring plugins - Understanding plugin discovery and load rules @@ -10,61 +10,55 @@ sidebarTitle: "Install and Configure" # Plugins +Plugins extend OpenClaw with new capabilities: channels, model providers, tools, +skills, speech, image generation, and more. Some plugins are **core** (shipped +with OpenClaw), others are **external** (published on npm by the community). + ## Quick start -A plugin is either: + + + ```bash + openclaw plugins list + ``` + -- a native **OpenClaw plugin** (`openclaw.plugin.json` + runtime module), or -- a compatible **bundle** (`.codex-plugin/plugin.json` or `.claude-plugin/plugin.json`) + + ```bash + # From npm + openclaw plugins install @openclaw/voice-call -Both show up under `openclaw plugins`, but only native OpenClaw plugins execute -runtime code in-process. + # From a local directory or archive + openclaw plugins install ./my-plugin + openclaw plugins install ./my-plugin.tgz + ``` -1. See what is already loaded: + -```bash -openclaw plugins list -``` + + ```bash + openclaw gateway restart + ``` -2. Install an official plugin (example: Voice Call): + Then configure under `plugins.entries.\.config` in your config file. -```bash -openclaw plugins install @openclaw/voice-call -``` + + -Npm specs are registry-only. See [install rules](/cli/plugins#install) for -details on pinning, prerelease gating, and supported spec formats. +## Plugin types -3. Restart the Gateway, then configure under `plugins.entries..config`. +OpenClaw recognizes two plugin formats: -See [Voice Call](/plugins/voice-call) for a concrete example plugin. -Looking for third-party listings? See [Community plugins](/plugins/community). -Need the bundle compatibility details? See [Plugin bundles](/plugins/bundles). +| Format | How it works | Examples | +| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | +| **Native** | `openclaw.plugin.json` + runtime module; executes in-process | Official plugins, community npm packages | +| **Bundle** | Codex/Claude/Cursor-compatible layout; mapped to OpenClaw features | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -For compatible bundles, install from a local directory or archive: +Both show up under `openclaw plugins list`. See [Plugin Bundles](/plugins/bundles) for bundle details. -```bash -openclaw plugins install ./my-bundle -openclaw plugins install ./my-bundle.tgz -``` +## Official plugins -For Claude marketplace installs, list the marketplace first, then install by -marketplace entry name: - -```bash -openclaw plugins marketplace list -openclaw plugins install @ -``` - -OpenClaw resolves known Claude marketplace names from -`~/.claude/plugins/known_marketplaces.json`. You can also pass an explicit -marketplace source with `--marketplace`. - -## Available plugins (official) - -### Installable plugins - -These are published to npm and installed with `openclaw plugins install`: +### Installable (npm) | Plugin | Package | Docs | | --------------- | ---------------------- | ------------------------------------ | @@ -75,51 +69,34 @@ These are published to npm and installed with `openclaw plugins install`: | Zalo | `@openclaw/zalo` | [Zalo](/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/plugins/zalouser) | -Microsoft Teams is plugin-only as of 2026.1.15. +### Core (shipped with OpenClaw) -Packaged installs also ship install-on-demand metadata for heavyweight official -plugins. Today that includes WhatsApp and `memory-lancedb`: onboarding, -`openclaw channels add`, `openclaw channels login --channel whatsapp`, and -other channel setup flows prompt to install them when first used instead of -shipping their full runtime trees inside the main npm tarball. + + + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, + `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `modelstudio`, + `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, + `qianfan`, `qwen-portal-auth`, `synthetic`, `together`, `venice`, + `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` + -### Bundled plugins + + - `memory-core` — bundled memory search (default via `plugins.slots.memory`) + - `memory-lancedb` — install-on-demand long-term memory with auto-recall/capture (set `plugins.slots.memory = "memory-lancedb"`) + -These ship with OpenClaw and are enabled by default unless noted. + + `elevenlabs`, `microsoft` + -**Memory:** + + - `copilot-proxy` — VS Code Copilot Proxy bridge (disabled by default) + + -- `memory-core` -- bundled memory search (default via `plugins.slots.memory`) -- `memory-lancedb` -- install-on-demand long-term memory with auto-recall/capture (set `plugins.slots.memory = "memory-lancedb"`) +Looking for third-party plugins? See [Community Plugins](/plugins/community). -**Model providers** (all enabled by default): - -`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `modelstudio`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, `qianfan`, `qwen-portal-auth`, `synthetic`, `together`, `venice`, `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - -**Speech providers** (enabled by default): - -`elevenlabs`, `microsoft` - -**Other bundled:** - -- `copilot-proxy` -- VS Code Copilot Proxy bridge (disabled by default) - -## Compatible bundles - -OpenClaw also recognizes compatible external bundle layouts: - -- Codex-style bundles: `.codex-plugin/plugin.json` -- Claude-style bundles: `.claude-plugin/plugin.json` or the default Claude - component layout without a manifest -- Cursor-style bundles: `.cursor-plugin/plugin.json` - -They are shown in the plugin list as `format=bundle`, with a subtype of -`codex`, `claude`, or `cursor` in verbose/inspect output. - -See [Plugin bundles](/plugins/bundles) for the exact detection rules, mapping -behavior, and current support matrix. - -## Config +## Configuration ```json5 { @@ -135,204 +112,140 @@ behavior, and current support matrix. } ``` -Fields: +| Field | Description | +| ---------------- | --------------------------------------------------------- | +| `enabled` | Master toggle (default: `true`) | +| `allow` | Plugin allowlist (optional) | +| `deny` | Plugin denylist (optional; deny wins) | +| `load.paths` | Extra plugin files/directories | +| `slots` | Exclusive slot selectors (e.g. `memory`, `contextEngine`) | +| `entries.\` | Per-plugin toggles + config | -- `enabled`: master toggle (default: true) -- `allow`: allowlist (optional) -- `deny`: denylist (optional; deny wins) -- `load.paths`: extra plugin files/dirs -- `slots`: exclusive slot selectors such as `memory` and `contextEngine` -- `entries.`: per-plugin toggles + config +Config changes **require a gateway restart**. -Config changes **require a gateway restart**. See -[Configuration reference](/configuration) for the full config schema. - -Validation rules (strict): - -- Unknown plugin ids in `entries`, `allow`, `deny`, or `slots` are **errors**. -- Unknown `channels.` keys are **errors** unless a plugin manifest declares - the channel id. -- Native plugin config is validated using the JSON Schema embedded in - `openclaw.plugin.json` (`configSchema`). -- Compatible bundles currently do not expose native OpenClaw config schemas. -- If a plugin is disabled, its config is preserved and a **warning** is emitted. - -### Disabled vs missing vs invalid - -These states are intentionally different: - -- **disabled**: plugin exists, but enablement rules turned it off -- **missing**: config references a plugin id that discovery did not find -- **invalid**: plugin exists, but its config does not match the declared schema - -OpenClaw preserves config for disabled plugins so toggling them back on is not -destructive. + + - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved. + - **Missing**: config references a plugin id that discovery did not find. + - **Invalid**: plugin exists but its config does not match the declared schema. + ## Discovery and precedence -OpenClaw scans, in order: +OpenClaw scans for plugins in this order (first match wins): -1. Config paths + + + `plugins.load.paths` — explicit file or directory paths. + -- `plugins.load.paths` (file or directory) + + `\/.openclaw/extensions/*.ts` and `\/.openclaw/extensions/*/index.ts`. + -2. Workspace extensions + + `~/.openclaw/extensions/*.ts` and `~/.openclaw/extensions/*/index.ts`. + -- `/.openclaw/extensions/*.ts` -- `/.openclaw/extensions/*/index.ts` - -3. Global extensions - -- `~/.openclaw/extensions/*.ts` -- `~/.openclaw/extensions/*/index.ts` - -4. Bundled extensions (shipped with OpenClaw; mixed default-on/default-off) - -- `/dist/extensions/*` in packaged installs -- `/dist-runtime/extensions/*` in local built checkouts -- `/extensions/*` in source/Vitest workflows - -Many bundled provider plugins are enabled by default so model catalogs/runtime -hooks stay available without extra setup. Others still require explicit -enablement via `plugins.entries..enabled` or -`openclaw plugins enable `. - -Bundled plugin runtime dependencies are owned by each plugin package. Packaged -builds stage opted-in bundled dependencies under -`dist/extensions//node_modules` instead of requiring mirrored copies in the -root package. Very large official plugins can ship as metadata-only bundled -entries and install their runtime package on demand. npm artifacts ship the -built `dist/extensions/*` tree; source `extensions/*` directories stay in source -checkouts only. - -Installed plugins are enabled by default, but can be disabled the same way. - -Workspace plugins are **disabled by default** unless you explicitly enable them -or allowlist them. This is intentional: a checked-out repo should not silently -become production gateway code. - -If multiple plugins resolve to the same id, the first match in the order above -wins and lower-precedence copies are ignored. + + Shipped with OpenClaw. Many are enabled by default (model providers, speech). + Others require explicit enablement. + + ### Enablement rules -Enablement is resolved after discovery: - - `plugins.enabled: false` disables all plugins -- `plugins.deny` always wins -- `plugins.entries..enabled: false` disables that plugin -- workspace-origin plugins are disabled by default -- allowlists restrict the active set when `plugins.allow` is non-empty -- allowlists are **id-based**, not source-based -- bundled plugins are disabled by default unless: - - the bundled id is in the built-in default-on set, or - - you explicitly enable it, or - - channel config implicitly enables the bundled channel plugin -- exclusive slots can force-enable the selected plugin for that slot +- `plugins.deny` always wins over allow +- `plugins.entries.\.enabled: false` disables that plugin +- Workspace-origin plugins are **disabled by default** (must be explicitly enabled) +- Bundled plugins follow the built-in default-on set unless overridden +- Exclusive slots can force-enable the selected plugin for that slot ## Plugin slots (exclusive categories) -Some plugin categories are **exclusive** (only one active at a time). Use -`plugins.slots` to select which plugin owns the slot: +Some categories are exclusive (only one active at a time): ```json5 { plugins: { slots: { - memory: "memory-core", // or "none" to disable memory plugins - contextEngine: "legacy", // or a plugin id such as "lossless-claw" + memory: "memory-core", // or "none" to disable + contextEngine: "legacy", // or a plugin id }, }, } ``` -Supported exclusive slots: +| Slot | What it controls | Default | +| --------------- | --------------------- | ------------------- | +| `memory` | Active memory plugin | `memory-core` | +| `contextEngine` | Active context engine | `legacy` (built-in) | -- `memory`: active memory plugin (`"none"` disables memory plugins) -- `contextEngine`: active context engine plugin (`"legacy"` is the built-in default) - -If multiple plugins declare `kind: "memory"` or `kind: "context-engine"`, only -the selected plugin loads for that slot. Others are disabled with diagnostics. -Declare `kind` in your [plugin manifest](/plugins/manifest). - -## Plugin IDs - -Default plugin ids: - -- Package packs: `package.json` `name` -- Standalone file: file base name (`~/.../voice-call.ts` -> `voice-call`) - -If a plugin exports `id`, OpenClaw uses it but warns when it does not match the -configured id. - -## Inspection +## CLI reference ```bash -openclaw plugins inspect openai # deep detail on one plugin -openclaw plugins inspect openai --json # machine-readable -openclaw plugins list # compact inventory -openclaw plugins status # operational summary -openclaw plugins doctor # issue-focused diagnostics -``` +openclaw plugins list # compact inventory +openclaw plugins inspect # deep detail +openclaw plugins inspect --json # machine-readable +openclaw plugins status # operational summary +openclaw plugins doctor # diagnostics -## CLI +openclaw plugins install # install from npm +openclaw plugins install # install from local path +openclaw plugins install -l # link (no copy) for dev +openclaw plugins update # update one plugin +openclaw plugins update --all # update all -```bash -openclaw plugins list -openclaw plugins inspect -openclaw plugins install # copy a local file/dir into ~/.openclaw/extensions/ -openclaw plugins install ./extensions/voice-call # relative path ok -openclaw plugins install ./plugin.tgz # install from a local tarball -openclaw plugins install ./plugin.zip # install from a local zip -openclaw plugins install -l ./extensions/voice-call # link (no copy) for dev -openclaw plugins install @openclaw/voice-call # install from npm -openclaw plugins install @openclaw/voice-call --pin # store exact resolved name@version -openclaw plugins update -openclaw plugins update --all openclaw plugins enable openclaw plugins disable -openclaw plugins doctor ``` -See [`openclaw plugins` CLI reference](/cli/plugins) for full details on each -command (install rules, inspect output, marketplace installs, uninstall). +See [`openclaw plugins` CLI reference](/cli/plugins) for full details. -Plugins may also register their own top-level commands (example: -`openclaw voicecall`). +## Plugin API overview -## Plugin API (overview) +Plugins export either a function or an object with `register(api)`: -Plugins export either: +```typescript +export default definePluginEntry({ + id: "my-plugin", + name: "My Plugin", + register(api) { + api.registerProvider({ + /* ... */ + }); + api.registerTool({ + /* ... */ + }); + api.registerChannel({ + /* ... */ + }); + }, +}); +``` -- A function: `(api) => { ... }` -- An object: `{ id, name, configSchema, register(api) { ... } }` +Common registration methods: -`register(api)` is where plugins attach behavior. Common registrations include: +| Method | What it registers | +| ------------------------------------ | -------------------- | +| `registerProvider` | Model provider (LLM) | +| `registerChannel` | Chat channel | +| `registerTool` | Agent tool | +| `registerHook` / `on(...)` | Lifecycle hooks | +| `registerSpeechProvider` | Text-to-speech / STT | +| `registerMediaUnderstandingProvider` | Image/audio analysis | +| `registerImageGenerationProvider` | Image generation | +| `registerWebSearchProvider` | Web search | +| `registerHttpRoute` | HTTP endpoint | +| `registerCommand` / `registerCli` | CLI commands | +| `registerContextEngine` | Context engine | +| `registerService` | Background service | -- `registerTool` -- `registerHook` -- `on(...)` for typed lifecycle hooks -- `registerChannel` -- `registerProvider` -- `registerSpeechProvider` -- `registerMediaUnderstandingProvider` -- `registerWebSearchProvider` -- `registerHttpRoute` -- `registerCommand` -- `registerCli` -- `registerContextEngine` -- `registerService` +## Related -See [Plugin manifest](/plugins/manifest) for the manifest file format. - -## Further reading - -- [Plugin architecture and internals](/plugins/architecture) -- capability model, - ownership model, contracts, load pipeline, runtime helpers, and developer API - reference -- [Building plugins](/plugins/building-plugins) -- [Plugin bundles](/plugins/bundles) -- [Plugin manifest](/plugins/manifest) -- [Plugin agent tools](/plugins/agent-tools) -- [Capability Cookbook](/tools/capability-cookbook) -- [Community plugins](/plugins/community) +- [Building Plugins](/plugins/building-plugins) — create your own plugin +- [Plugin Bundles](/plugins/bundles) — Codex/Claude/Cursor bundle compatibility +- [Plugin Manifest](/plugins/manifest) — manifest schema +- [Registering Tools](/plugins/agent-tools) — add agent tools in a plugin +- [Plugin Internals](/plugins/architecture) — capability model and load pipeline +- [Community Plugins](/plugins/community) — third-party listings