From 20f9f99db6bc9f50d1db2bc153f8caca9a84ac8d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 13:15:19 +0100 Subject: [PATCH] docs: refresh plugin manifest and bundle refs --- docs/plugins/bundles.md | 16 ++++- docs/plugins/manifest.md | 148 ++++++++++++++++++++++++++++---------- docs/plugins/sdk-setup.md | 31 +++++--- 3 files changed, 147 insertions(+), 48 deletions(-) diff --git a/docs/plugins/bundles.md b/docs/plugins/bundles.md index 67a3efe3a1d..ba2cc815bb6 100644 --- a/docs/plugins/bundles.md +++ b/docs/plugins/bundles.md @@ -60,7 +60,7 @@ and use it immediately. openclaw gateway restart ``` - Mapped features (skills, hooks, MCP tools) are available in the next session. + Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session. @@ -78,6 +78,7 @@ is detected but not yet wired. | Commands | `commands/` and `.cursor/commands/` treated as skill roots | Claude, Cursor | | Hook packs | OpenClaw-style `HOOK.md` + `handler.ts` layouts | Codex | | MCP tools | Bundle MCP config merged into embedded Pi settings; supported stdio and HTTP servers loaded | All formats | +| LSP servers | Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded Pi LSP defaults | Claude | | Settings | Claude `settings.json` imported as embedded Pi defaults | Claude | #### Skill content @@ -181,11 +182,19 @@ Sanitized keys: - `shellPath` - `shellCommandPrefix` +#### Embedded Pi LSP + +- enabled Claude bundles can contribute LSP server config +- OpenClaw loads `.lsp.json` plus any manifest-declared `lspServers` paths +- bundle LSP config is merged into the effective embedded Pi LSP defaults +- only supported stdio-backed LSP servers are runnable today; unsupported + transports still show up in `openclaw plugins inspect ` + ### Detected but not executed These are recognized and shown in diagnostics, but OpenClaw does not run them: -- Claude `agents`, `hooks.json` automation, `lspServers`, `outputStyles` +- Claude `agents`, `hooks.json` automation, `outputStyles` - Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` - Codex inline/app metadata beyond capability reporting @@ -206,13 +215,14 @@ These are recognized and shown in diagnostics, but OpenClaw does not run them: Two detection modes: - **Manifest-based:** `.claude-plugin/plugin.json` - - **Manifestless:** default Claude layout (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `settings.json`) + - **Manifestless:** default Claude layout (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`) Claude-specific behavior: - `commands/` is treated as skill content - `settings.json` is imported into embedded Pi settings (shell override keys are sanitized) - `.mcp.json` exposes supported stdio tools to embedded Pi + - `.lsp.json` plus manifest-declared `lspServers` paths load into embedded Pi LSP defaults - `hooks/hooks.json` is detected but not executed - Custom component paths in the manifest are additive (they extend defaults, not replace them) diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index 5445bb9fa12..2ad4c63b98b 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -46,10 +46,13 @@ Use it for: - config validation - auth and onboarding metadata that should be available without booting plugin runtime +- alias and auto-enable metadata that should resolve before plugin runtime loads - shorthand model-family ownership metadata that should auto-activate the plugin before runtime loads - static capability ownership snapshots used for bundled compat wiring and contract coverage +- channel-specific config metadata that should merge into catalog and validation + surfaces without loading runtime - config UI hints Do not use it for: @@ -125,45 +128,51 @@ Those belong in your plugin code and `package.json`. ## Top-level field reference -| Field | Required | Type | What it means | -| --------------------- | -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `id` | Yes | `string` | Canonical plugin id. This is the id used in `plugins.entries.`. | -| `configSchema` | Yes | `object` | Inline JSON Schema for this plugin's config. | -| `enabledByDefault` | No | `true` | Marks a bundled plugin as enabled by default. Omit it, or set any non-`true` value, to leave the plugin disabled by default. | -| `kind` | No | `"memory"` \| `"context-engine"` | Declares an exclusive plugin kind used by `plugins.slots.*`. | -| `channels` | No | `string[]` | Channel ids owned by this plugin. Used for discovery and config validation. | -| `providers` | No | `string[]` | Provider ids owned by this plugin. | -| `modelSupport` | No | `object` | Manifest-owned shorthand model-family metadata used to auto-load the plugin before runtime. | -| `cliBackends` | No | `string[]` | CLI inference backend ids owned by this plugin. Used for startup auto-activation from explicit config refs. | -| `providerAuthEnvVars` | No | `Record` | Cheap provider-auth env metadata that OpenClaw can inspect without loading plugin code. | -| `providerAuthChoices` | No | `object[]` | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring. | -| `contracts` | No | `object` | Static bundled capability snapshot for speech, media-understanding, image-generation, web search, and tool ownership. | -| `skills` | No | `string[]` | Skill directories to load, relative to the plugin root. | -| `name` | No | `string` | Human-readable plugin name. | -| `description` | No | `string` | Short summary shown in plugin surfaces. | -| `version` | No | `string` | Informational plugin version. | -| `uiHints` | No | `Record` | UI labels, placeholders, and sensitivity hints for config fields. | +| Field | Required | Type | What it means | +| ----------------------------------- | -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `id` | Yes | `string` | Canonical plugin id. This is the id used in `plugins.entries.`. | +| `configSchema` | Yes | `object` | Inline JSON Schema for this plugin's config. | +| `enabledByDefault` | No | `true` | Marks a bundled plugin as enabled by default. Omit it, or set any non-`true` value, to leave the plugin disabled by default. | +| `legacyPluginIds` | No | `string[]` | Legacy ids that normalize to this canonical plugin id. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | Provider ids that should auto-enable this plugin when auth, config, or model refs mention them. | +| `kind` | No | `"memory"` \| `"context-engine"` | Declares an exclusive plugin kind used by `plugins.slots.*`. | +| `channels` | No | `string[]` | Channel ids owned by this plugin. Used for discovery and config validation. | +| `providers` | No | `string[]` | Provider ids owned by this plugin. | +| `modelSupport` | No | `object` | Manifest-owned shorthand model-family metadata used to auto-load the plugin before runtime. | +| `cliBackends` | No | `string[]` | CLI inference backend ids owned by this plugin. Used for startup auto-activation from explicit config refs. | +| `providerAuthEnvVars` | No | `Record` | Cheap provider-auth env metadata that OpenClaw can inspect without loading plugin code. | +| `providerAuthChoices` | No | `object[]` | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring. | +| `contracts` | No | `object` | Static bundled capability snapshot for speech, media-understanding, image-generation, web search, and tool ownership. | +| `channelConfigs` | No | `Record` | Manifest-owned channel config metadata merged into discovery and validation surfaces before runtime loads. | +| `skills` | No | `string[]` | Skill directories to load, relative to the plugin root. | +| `name` | No | `string` | Human-readable plugin name. | +| `description` | No | `string` | Short summary shown in plugin surfaces. | +| `version` | No | `string` | Informational plugin version. | +| `uiHints` | No | `Record` | UI labels, placeholders, and sensitivity hints for config fields. | ## providerAuthChoices reference Each `providerAuthChoices` entry describes one onboarding or auth choice. OpenClaw reads this before provider runtime loads. -| Field | Required | Type | What it means | -| ------------------ | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Yes | `string` | Provider id this choice belongs to. | -| `method` | Yes | `string` | Auth method id to dispatch to. | -| `choiceId` | Yes | `string` | Stable auth-choice id used by onboarding and CLI flows. | -| `choiceLabel` | No | `string` | User-facing label. If omitted, OpenClaw falls back to `choiceId`. | -| `choiceHint` | No | `string` | Short helper text for the picker. | -| `groupId` | No | `string` | Optional group id for grouping related choices. | -| `groupLabel` | No | `string` | User-facing label for that group. | -| `groupHint` | No | `string` | Short helper text for the group. | -| `optionKey` | No | `string` | Internal option key for simple one-flag auth flows. | -| `cliFlag` | No | `string` | CLI flag name, such as `--openrouter-api-key`. | -| `cliOption` | No | `string` | Full CLI option shape, such as `--openrouter-api-key `. | -| `cliDescription` | No | `string` | Description used in CLI help. | -| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | Which onboarding surfaces this choice should appear in. If omitted, it defaults to `["text-inference"]`. | +| Field | Required | Type | What it means | +| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Yes | `string` | Provider id this choice belongs to. | +| `method` | Yes | `string` | Auth method id to dispatch to. | +| `choiceId` | Yes | `string` | Stable auth-choice id used by onboarding and CLI flows. | +| `choiceLabel` | No | `string` | User-facing label. If omitted, OpenClaw falls back to `choiceId`. | +| `choiceHint` | No | `string` | Short helper text for the picker. | +| `assistantPriority` | No | `number` | Lower values sort earlier in assistant-driven interactive pickers. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Hide the choice from assistant pickers while still allowing manual CLI selection. | +| `deprecatedChoiceIds` | No | `string[]` | Legacy choice ids that should redirect users to this replacement choice. | +| `groupId` | No | `string` | Optional group id for grouping related choices. | +| `groupLabel` | No | `string` | User-facing label for that group. | +| `groupHint` | No | `string` | Short helper text for the group. | +| `optionKey` | No | `string` | Internal option key for simple one-flag auth flows. | +| `cliFlag` | No | `string` | CLI flag name, such as `--openrouter-api-key`. | +| `cliOption` | No | `string` | Full CLI option shape, such as `--openrouter-api-key `. | +| `cliDescription` | No | `string` | Description used in CLI help. | +| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | Which onboarding surfaces this choice should appear in. If omitted, it defaults to `["text-inference"]`. | ## uiHints reference @@ -221,9 +230,50 @@ Each list is optional: | `realtimeVoiceProviders` | `string[]` | Realtime-voice provider ids this plugin owns. | | `mediaUnderstandingProviders` | `string[]` | Media-understanding provider ids this plugin owns. | | `imageGenerationProviders` | `string[]` | Image-generation provider ids this plugin owns. | +| `webFetchProviders` | `string[]` | Web-fetch provider ids this plugin owns. | | `webSearchProviders` | `string[]` | Web-search provider ids this plugin owns. | | `tools` | `string[]` | Agent tool names this plugin owns for bundled contract checks. | +## channelConfigs reference + +Use `channelConfigs` when a channel plugin needs cheap config metadata before +runtime loads. + +```json +{ + "channelConfigs": { + "matrix": { + "schema": { + "type": "object", + "additionalProperties": false, + "properties": { + "homeserverUrl": { "type": "string" } + } + }, + "uiHints": { + "homeserverUrl": { + "label": "Homeserver URL", + "placeholder": "https://matrix.example.com" + } + }, + "label": "Matrix", + "description": "Matrix homeserver connection", + "preferOver": ["matrix-legacy"] + } + } +} +``` + +Each channel entry can include: + +| Field | Type | What it means | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema for `channels.`. Required for each declared channel config entry. | +| `uiHints` | `Record` | Optional UI labels/placeholders/sensitive hints for that channel config section. | +| `label` | `string` | Channel label merged into picker and inspect surfaces when runtime metadata is not ready. | +| `description` | `string` | Short channel description for inspect and catalog surfaces. | +| `preferOver` | `string[]` | Legacy or lower-priority plugin ids this channel should outrank in selection surfaces. | + ## modelSupport reference Use `modelSupport` when OpenClaw should infer your provider plugin from @@ -263,16 +313,38 @@ capability ownership. The two files serve different jobs: -| File | Use it for | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `openclaw.plugin.json` | Discovery, config validation, auth-choice metadata, and UI hints that must exist before plugin code runs | -| `package.json` | npm metadata, dependency installation, and the `openclaw` block used for entrypoints and setup or catalog metadata | +| File | Use it for | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Discovery, config validation, auth-choice metadata, and UI hints that must exist before plugin code runs | +| `package.json` | npm metadata, dependency installation, and the `openclaw` block used for entrypoints, install gating, setup, or catalog metadata | If you are unsure where a piece of metadata belongs, use this rule: - if OpenClaw must know it before loading plugin code, put it in `openclaw.plugin.json` - if it is about packaging, entry files, or npm install behavior, put it in `package.json` +### package.json fields that affect discovery + +Some pre-runtime plugin metadata intentionally lives in `package.json` under the +`openclaw` block instead of `openclaw.plugin.json`. + +Important examples: + +| Field | What it means | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Declares native plugin entrypoints. | +| `openclaw.setupEntry` | Lightweight setup-only entrypoint used during onboarding and deferred channel startup. | +| `openclaw.channel` | Cheap channel catalog metadata like labels, docs paths, aliases, and selection copy. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Install/update hints for bundled and externally published plugins. | +| `openclaw.install.defaultChoice` | Preferred install path when multiple install sources are available. | +| `openclaw.install.minHostVersion` | Minimum supported OpenClaw host version, using a semver floor like `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Allows setup/install flows to offer guarded recovery when config is invalid. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Lets setup-only channel surfaces load before the full channel plugin during startup. | + +`openclaw.install.minHostVersion` is enforced during install and manifest +registry loading. Invalid values are rejected; newer-but-valid values skip the +plugin on older hosts. + ## JSON Schema requirements - **Every plugin must ship a JSON Schema**, even if it accepts no config. @@ -297,6 +369,8 @@ See [Configuration reference](/gateway/configuration) for the full `plugins.*` s - The manifest is **required for native OpenClaw plugins**, including local filesystem loads. - Runtime still loads the plugin module separately; the manifest is only for discovery + validation. +- Native manifests are parsed with JSON5, so comments, trailing commas, and + unquoted keys are accepted as long as the final value is still an object. - Only documented manifest fields are read by the manifest loader. Avoid adding custom top-level keys here. - `providerAuthEnvVars` is the cheap metadata path for auth probes, env-marker diff --git a/docs/plugins/sdk-setup.md b/docs/plugins/sdk-setup.md index 9b4dff75a1e..19ab5a11920 100644 --- a/docs/plugins/sdk-setup.md +++ b/docs/plugins/sdk-setup.md @@ -70,14 +70,29 @@ fields are required. The canonical publish snippets live in ### `openclaw` fields -| Field | Type | Description | -| ------------ | ---------- | ------------------------------------------------------------------------------------------ | -| `extensions` | `string[]` | Entry point files (relative to package root) | -| `setupEntry` | `string` | Lightweight setup-only entry (optional) | -| `channel` | `object` | Channel metadata: `id`, `label`, `blurb`, `selectionLabel`, `docsPath`, `order`, `aliases` | -| `providers` | `string[]` | Provider ids registered by this plugin | -| `install` | `object` | Install hints: `npmSpec`, `localPath`, `defaultChoice` | -| `startup` | `object` | Startup behavior flags | +| Field | Type | Description | +| ------------ | ---------- | -------------------------------------------------------------------------------------------------------- | +| `extensions` | `string[]` | Entry point files (relative to package root) | +| `setupEntry` | `string` | Lightweight setup-only entry (optional) | +| `channel` | `object` | Channel metadata: `id`, `label`, `blurb`, `selectionLabel`, `docsPath`, `order`, `aliases`, `preferOver` | +| `providers` | `string[]` | Provider ids registered by this plugin | +| `install` | `object` | Install hints: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | +| `startup` | `object` | Startup behavior flags | + +### `openclaw.install` + +`openclaw.install` is package metadata, not manifest metadata. + +| Field | Type | What it means | +| ---------------------------- | -------------------- | ------------------------------------------------------------------------------ | +| `npmSpec` | `string` | Canonical npm spec for install/update flows. | +| `localPath` | `string` | Local development or bundled install path. | +| `defaultChoice` | `"npm"` \| `"local"` | Preferred install source when both are available. | +| `minHostVersion` | `string` | Minimum supported OpenClaw version in the form `>=x.y.z`. | +| `allowInvalidConfigRecovery` | `boolean` | Lets setup/install flows offer guarded recovery when plugin config is invalid. | + +If `minHostVersion` is set, install and manifest-registry loading both enforce +it. Older hosts skip the plugin; invalid version strings are rejected. ### Deferred full load