From 1d9217b6ea5b56f432255349e95bbf1e606d32a3 Mon Sep 17 00:00:00 2001
From: "openclaw-docs-sync[bot]"
 <openclaw-docs-sync[bot]@users.noreply.github.com>
Date: Sun, 12 Apr 2026 02:30:03 +0000
Subject: [PATCH] chore(sync): mirror docs from
 openclaw/openclaw@8ba50aa23eedd71e48a4c995cf29ede496a20c24

---
 .openclaw-sync/source.json   |  4 ++--
 docs/plugins/architecture.md |  7 +++++++
 docs/plugins/manifest.md     | 33 ++++++++++++++++++++++-----------
 3 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index d45d65b3c..4441253de 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "52bf19c45e0891a17dd7031aefe3c10f4e4713e9",
-  "syncedAt": "2026-04-12T01:24:49.115Z"
+  "sha": "8ba50aa23eedd71e48a4c995cf29ede496a20c24",
+  "syncedAt": "2026-04-12T02:30:02.821Z"
 }
diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md
index f833e5919..406e450a3 100644
--- a/docs/plugins/architecture.md
+++ b/docs/plugins/architecture.md
@@ -528,6 +528,13 @@ Optional manifest `activation` and `setup` blocks stay on the control plane.
 They are metadata-only descriptors for activation planning and setup discovery;
 they do not replace runtime registration, `register(...)`, or `setupEntry`.
 
+Setup discovery now prefers descriptor-owned ids such as `setup.providers` and
+`setup.cliBackends` to narrow candidate plugins before it falls back to
+`setup-api` for plugins that still need setup-time runtime hooks. If more than
+one discovered plugin claims the same normalized setup provider or CLI backend
+id, setup lookup refuses the ambiguous owner instead of relying on discovery
+order.
+
 ### What the loader caches
 
 OpenClaw keeps short in-process caches for:
diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
index d6818dc9b..f1a6d424c 100644
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -268,22 +268,33 @@ Top-level `cliBackends` stays valid and continues to describe CLI inference
 backends. `setup.cliBackends` is the setup-specific descriptor surface for
 control-plane/setup flows that should stay metadata-only.
 
+When present, `setup.providers` and `setup.cliBackends` are the preferred
+descriptor-first lookup surface for setup discovery. If the descriptor only
+narrows the candidate plugin and setup still needs richer setup-time runtime
+hooks, set `requiresRuntime: true` and keep `setup-api` in place as the
+fallback execution path.
+
+Because setup lookup can execute plugin-owned `setup-api` code, normalized
+`setup.providers[].id` and `setup.cliBackends[]` values must stay unique across
+discovered plugins. Ambiguous ownership fails closed instead of picking a
+winner from discovery order.
+
 ### setup.providers reference
 
-| Field         | Required | Type       | What it means                                                                      |
-| ------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
-| `id`          | Yes      | `string`   | Provider id exposed during setup or onboarding.                                    |
-| `authMethods` | No       | `string[]` | Setup/auth method ids this provider supports without loading full runtime.         |
-| `envVars`     | No       | `string[]` | Env vars that generic setup/status surfaces can check before plugin runtime loads. |
+| Field         | Required | Type       | What it means                                                                        |
+| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
+| `id`          | Yes      | `string`   | Provider id exposed during setup or onboarding. Keep normalized ids globally unique. |
+| `authMethods` | No       | `string[]` | Setup/auth method ids this provider supports without loading full runtime.           |
+| `envVars`     | No       | `string[]` | Env vars that generic setup/status surfaces can check before plugin runtime loads.   |
 
 ### setup fields
 
-| Field              | Required | Type       | What it means                                                               |
-| ------------------ | -------- | ---------- | --------------------------------------------------------------------------- |
-| `providers`        | No       | `object[]` | Provider setup descriptors exposed during setup and onboarding.             |
-| `cliBackends`      | No       | `string[]` | Setup-time backend ids available without full runtime activation.           |
-| `configMigrations` | No       | `string[]` | Config migration ids owned by this plugin's setup surface.                  |
-| `requiresRuntime`  | No       | `boolean`  | Whether setup still needs plugin runtime execution after descriptor lookup. |
+| Field              | Required | Type       | What it means                                                                                       |
+| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
+| `providers`        | No       | `object[]` | Provider setup descriptors exposed during setup and onboarding.                                     |
+| `cliBackends`      | No       | `string[]` | Setup-time backend ids used for descriptor-first setup lookup. Keep normalized ids globally unique. |
+| `configMigrations` | No       | `string[]` | Config migration ids owned by this plugin's setup surface.                                          |
+| `requiresRuntime`  | No       | `boolean`  | Whether setup still needs `setup-api` execution after descriptor lookup.                            |
 
 ## uiHints reference