docs: plugin manifest precedence, QQBot engine/bot-approve/QR onboarding, web-search plugin-scoped SecretRefs

2026-05-06 08:40:44 +00:00 · 2026-04-21 13:26:25 -07:00
parent b4a59be9b6
commit 78030d0d52
3 changed files with 52 additions and 10 deletions
--- a/docs/channels/qqbot.md
+++ b/docs/channels/qqbot.md
@@ -171,16 +171,36 @@ Outbound audio upload/transcode behavior can also be tuned with

 Built-in commands intercepted before the AI queue:

-| Command        | Description                          |
-| -------------- | ------------------------------------ |
-| `/bot-ping`    | Latency test                         |
-| `/bot-version` | Show the OpenClaw framework version  |
-| `/bot-help`    | List all commands                    |
-| `/bot-upgrade` | Show the QQBot upgrade guide link    |
-| `/bot-logs`    | Export recent gateway logs as a file |
+| Command        | Description                                                                                              |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `/bot-ping`    | Latency test                                                                                             |
+| `/bot-version` | Show the OpenClaw framework version                                                                      |
+| `/bot-help`    | List all commands                                                                                        |
+| `/bot-upgrade` | Show the QQBot upgrade guide link                                                                        |
+| `/bot-logs`    | Export recent gateway logs as a file                                                                     |
+| `/bot-approve` | Approve a pending QQ Bot action (for example, confirming a C2C or group upload) through the native flow. |

 Append `?` to any command for usage help (for example `/bot-upgrade ?`).

+## Engine architecture
+
+QQ Bot ships as a self-contained engine inside the plugin:
+
+- Each account owns an isolated resource stack (WebSocket connection, API client, token cache, media storage root) keyed by `appId`. Accounts never share inbound/outbound state.
+- The multi-account logger tags log lines with the owning account so diagnostics stay separable when you run several bots under one gateway.
+- Inbound, outbound, and gateway bridge paths share a single media payload root under `~/.openclaw/media`, so uploads, downloads, and transcode caches land under one guarded directory instead of a per-subsystem tree.
+- Credentials can be backed up and restored as part of standard OpenClaw credential snapshots; the engine re-attaches each account's resource stack on restore without requiring a fresh QR-code pair.
+
+## QR-code onboarding
+
+As an alternative to pasting `AppID:AppSecret` manually, the engine supports a QR-code onboarding flow for linking a QQ Bot to OpenClaw:
+
+1. Run the QQ Bot setup path (for example `openclaw channels add --channel qqbot`) and pick the QR-code flow when prompted.
+2. Scan the generated QR code with the phone app tied to the target QQ Bot.
+3. Approve the pairing on the phone. OpenClaw persists the returned credentials into `credentials/` under the right account scope.
+
+Approval prompts generated by the bot itself (for example, "allow this action?" flows exposed by the QQ Bot API) surface as native OpenClaw prompts that you can accept with `/bot-approve` rather than replying through the raw QQ client.
+
 ## Troubleshooting

 - **Bot replies "gone to Mars":** credentials not configured or Gateway not started.
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -581,6 +581,23 @@ non-runtime inputs. If the check needs full config resolution or the real
 channel runtime, keep that logic in the plugin `config.hasConfiguredState`
 hook instead.

+## Discovery precedence (duplicate plugin ids)
+
+OpenClaw discovers plugins from several roots (bundled, global install, workspace, explicit config-selected paths). If two discoveries share the same `id`, only the **highest-precedence** manifest is kept; lower-precedence duplicates are dropped instead of loading beside it.
+
+Precedence, highest to lowest:
+
+1. **Config-selected** — a path explicitly pinned in `plugins.entries.<id>`
+2. **Bundled** — plugins shipped with OpenClaw
+3. **Global install** — plugins installed into the global OpenClaw plugin root
+4. **Workspace** — plugins discovered relative to the current workspace
+
+Implications:
+
+- A forked or stale copy of a bundled plugin sitting in the workspace will not shadow the bundled build.
+- To actually override a bundled plugin with a local one, pin it via `plugins.entries.<id>` so it wins by precedence rather than relying on workspace discovery.
+- Duplicate drops are logged so Doctor and startup diagnostics can point at the discarded copy.
+
 ## JSON Schema requirements

 - **Every plugin must ship a JSON Schema**, even if it accepts no config.
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -181,9 +181,14 @@ If no provider is detected, it falls back to Brave (you will get a missing-key
 error prompting you to configure one).

 <Note>
-  All provider key fields support SecretRef objects. In auto-detect mode,
-  OpenClaw resolves only the selected provider key -- non-selected SecretRefs
-  stay inactive.
+  All provider key fields support SecretRef objects. Plugin-scoped SecretRefs
+  under `plugins.entries.<plugin>.config.webSearch.apiKey` are resolved for the
+  bundled Exa, Firecrawl, Gemini, Grok, Kimi, Perplexity, and Tavily providers
+  whether the provider is picked explicitly via `tools.web.search.provider` or
+  selected through auto-detect. In auto-detect mode, OpenClaw resolves only the
+  selected provider key -- non-selected SecretRefs stay inactive, so you can
+  keep multiple providers configured without paying resolution cost for the
+  ones you are not using.
 </Note>

 ## Config