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
```