From 3607962a449fbf14a8e158b3d4beef180d4b570a Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 13:18:34 +0100 Subject: [PATCH] docs: refresh plugin channel metadata refs --- docs/plugins/architecture.md | 12 +++++ docs/plugins/sdk-channel-plugins.md | 3 +- docs/plugins/sdk-setup.md | 71 +++++++++++++++++++++++++---- 3 files changed, 75 insertions(+), 11 deletions(-) diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md index 7a9142a50ca..81b9a8dffff 100644 --- a/docs/plugins/architecture.md +++ b/docs/plugins/architecture.md @@ -1344,6 +1344,18 @@ Example: } ``` +Useful `openclaw.channel` fields beyond the minimal example: + +- `detailLabel`: secondary label for richer catalog/status surfaces +- `docsLabel`: override link text for the docs link +- `preferOver`: lower-priority plugin/channel ids this catalog entry should outrank +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: selection-surface copy controls +- `markdownCapable`: marks the channel as markdown-capable for outbound formatting decisions +- `showConfigured`: hide the channel from configured-channel listing surfaces when set to `false` +- `quickstartAllowFrom`: opt the channel into the standard quickstart `allowFrom` flow +- `forceAccountBinding`: require explicit account binding even when only one account exists +- `preferSessionLookupForAnnounceTarget`: prefer session lookup when resolving announce targets + OpenClaw can also merge **external channel catalogs** (for example, an MPM registry export). Drop a JSON file at one of: diff --git a/docs/plugins/sdk-channel-plugins.md b/docs/plugins/sdk-channel-plugins.md index 4622e6648ef..145aa3f1b25 100644 --- a/docs/plugins/sdk-channel-plugins.md +++ b/docs/plugins/sdk-channel-plugins.md @@ -114,7 +114,8 @@ Auth-only channels can usually stop at the default path: core handles approvals Create the standard plugin files. The `channel` field in `package.json` is - what makes this a channel plugin: + what makes this a channel plugin. For the full package-metadata surface, + see [Plugin Setup and Config](/plugins/sdk-setup#openclawchannel): ```json package.json diff --git a/docs/plugins/sdk-setup.md b/docs/plugins/sdk-setup.md index 19ab5a11920..4e6ec2c8bfd 100644 --- a/docs/plugins/sdk-setup.md +++ b/docs/plugins/sdk-setup.md @@ -70,14 +70,66 @@ 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`, `preferOver` | -| `providers` | `string[]` | Provider ids registered by this plugin | -| `install` | `object` | Install hints: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | -| `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 catalog metadata for setup, picker, quickstart, and status surfaces | +| `providers` | `string[]` | Provider ids registered by this plugin | +| `install` | `object` | Install hints: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | +| `startup` | `object` | Startup behavior flags | + +### `openclaw.channel` + +`openclaw.channel` is cheap package metadata for channel discovery and setup +surfaces before runtime loads. + +| Field | Type | What it means | +| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | +| `id` | `string` | Canonical channel id. | +| `label` | `string` | Primary channel label. | +| `selectionLabel` | `string` | Picker/setup label when it should differ from `label`. | +| `detailLabel` | `string` | Secondary detail label for richer channel catalogs and status surfaces. | +| `docsPath` | `string` | Docs path for setup and selection links. | +| `docsLabel` | `string` | Override label used for docs links when it should differ from the channel id. | +| `blurb` | `string` | Short onboarding/catalog description. | +| `order` | `number` | Sort order in channel catalogs. | +| `aliases` | `string[]` | Extra lookup aliases for channel selection. | +| `preferOver` | `string[]` | Lower-priority plugin/channel ids this channel should outrank. | +| `systemImage` | `string` | Optional icon/system-image name for channel UI catalogs. | +| `selectionDocsPrefix` | `string` | Prefix text before docs links in selection surfaces. | +| `selectionDocsOmitLabel` | `boolean` | Show the docs path directly instead of a labeled docs link in selection copy. | +| `selectionExtras` | `string[]` | Extra short strings appended in selection copy. | +| `markdownCapable` | `boolean` | Marks the channel as markdown-capable for outbound formatting decisions. | +| `showConfigured` | `boolean` | Controls whether configured-channel listing surfaces show this channel. | +| `quickstartAllowFrom` | `boolean` | Opt this channel into the standard quickstart `allowFrom` setup flow. | +| `forceAccountBinding` | `boolean` | Require explicit account binding even when only one account exists. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Prefer session lookup when resolving announce targets for this channel. | + +Example: + +```json +{ + "openclaw": { + "channel": { + "id": "my-channel", + "label": "My Channel", + "selectionLabel": "My Channel (self-hosted)", + "detailLabel": "My Channel Bot", + "docsPath": "/channels/my-channel", + "docsLabel": "my-channel", + "blurb": "Webhook-based self-hosted chat integration.", + "order": 80, + "aliases": ["mc"], + "preferOver": ["my-channel-legacy"], + "selectionDocsPrefix": "Guide:", + "selectionExtras": ["Markdown"], + "markdownCapable": true, + "quickstartAllowFrom": true + } + } +} +``` ### `openclaw.install` @@ -368,10 +420,9 @@ openclaw plugins install npm:@myorg/openclaw-my-plugin # npm only **In-repo plugins:** place under the bundled plugin workspace tree and they are automatically discovered during build. -**Users can browse and install:** +**Users can install:** ```bash -openclaw plugins search openclaw plugins install ```