diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 03a97ea8a..0b1dd9c2c 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "6ed642a86ddbea83e0f84186de47613a1a146d35", - "syncedAt": "2026-04-26T00:06:36.229Z" + "sha": "3a4325b28548862b42289447921ac4b23575622a", + "syncedAt": "2026-04-26T00:07:18.274Z" } diff --git a/docs/plugins/community.md b/docs/plugins/community.md index 76739fe2d..7377194f5 100644 --- a/docs/plugins/community.md +++ b/docs/plugins/community.md @@ -105,6 +105,10 @@ Connect OpenClaw to QQ via the QQ Bot API. Supports private chats, group mentions, channel messages, and rich media including voice, images, videos, and files. +Current OpenClaw releases bundle QQ Bot. Use the bundled setup in +[QQ Bot](/channels/qqbot) for normal installs; install this external plugin only +when you intentionally want the Tencent-maintained standalone package. + - **npm:** `@tencent-connect/openclaw-qqbot` - **repo:** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot) diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index b0d95de84..b61f15d95 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -508,6 +508,11 @@ runtime loads. Read-only channel setup/status discovery can use this metadata directly for configured external channels when no setup entry is available, or when `setup.requiresRuntime: false` declares setup runtime unnecessary. +`channelConfigs` is plugin manifest metadata, not a new top-level user config +section. Users still configure channel instances under `channels.`. +OpenClaw reads manifest metadata to decide which plugin owns that configured +channel before plugin runtime code executes. + For a channel plugin, `configSchema` and `channelConfigs` describe different paths: @@ -554,6 +559,43 @@ Each channel entry can include: | `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. | +### Replacing another channel plugin + +Use `preferOver` when your plugin is the preferred owner for a channel id that +another plugin can also provide. Common cases are a renamed plugin id, a +standalone plugin that supersedes a bundled plugin, or a maintained fork that +keeps the same channel id for config compatibility. + +```json +{ + "id": "acme-chat", + "channels": ["chat"], + "channelConfigs": { + "chat": { + "schema": { + "type": "object", + "additionalProperties": false, + "properties": { + "webhookUrl": { "type": "string" } + } + }, + "preferOver": ["chat"] + } + } +} +``` + +When `channels.chat` is configured, OpenClaw considers both the channel id and +the preferred plugin id. If the lower-priority plugin was only selected because +it is bundled or enabled by default, OpenClaw disables it in the effective +runtime config so one plugin owns the channel and its tools. Explicit user +selection still wins: if the user explicitly enables both plugins, OpenClaw +preserves that choice and reports duplicate channel/tool diagnostics instead of +silently changing the requested plugin set. + +Keep `preferOver` scoped to plugin ids that can really provide the same channel. +It is not a general priority field and it does not rename user config keys. + ## modelSupport reference Use `modelSupport` when OpenClaw should infer your provider plugin from diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index fb36bef75..a4eda7a88 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -232,6 +232,40 @@ do not run in live chat traffic, check these first: Gateway session/status surfaces and, when debugging provider payloads, start the Gateway with `--raw-stream --raw-stream-path `. +### Duplicate channel or tool ownership + +Symptoms: + +- `channel already registered: ()` +- `channel setup already registered: ()` +- `plugin tool name conflict (): ` + +These mean more than one enabled plugin is trying to own the same channel, +setup flow, or tool name. The most common cause is an external channel plugin +installed beside a bundled plugin that now provides the same channel id. + +Debug steps: + +- Run `openclaw plugins list --enabled --verbose` to see every enabled plugin + and origin. +- Run `openclaw plugins inspect --json` for each suspected plugin and + compare `channels`, `channelConfigs`, `tools`, and diagnostics. +- Run `openclaw plugins registry --refresh` after installing or removing + plugin packages so persisted metadata reflects the current install. +- Restart the Gateway after install, registry, or config changes. + +Fix options: + +- If one plugin intentionally replaces another for the same channel id, the + preferred plugin should declare `channelConfigs..preferOver` with + the lower-priority plugin id. See [/plugins/manifest#replacing-another-channel-plugin](/plugins/manifest#replacing-another-channel-plugin). +- If the duplicate is accidental, disable one side with + `plugins.entries..enabled: false` or remove the stale plugin + install. +- If you explicitly enabled both plugins, OpenClaw keeps that request and + reports the conflict. Pick one owner for the channel or rename plugin-owned + tools so the runtime surface is unambiguous. + ## Plugin slots (exclusive categories) Some categories are exclusive (only one active at a time):