diff --git a/docs/brave-search.md b/docs/brave-search.md
index 4a541690431..12cd78c358f 100644
--- a/docs/brave-search.md
+++ b/docs/brave-search.md
@@ -20,11 +20,21 @@ OpenClaw supports Brave Search API as a `web_search` provider.
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "brave",
-        apiKey: "BRAVE_API_KEY_HERE",
         maxResults: 5,
         timeoutSeconds: 30,
       },
@@ -33,6 +43,9 @@ OpenClaw supports Brave Search API as a `web_search` provider.
 }
 ```
 
+Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`.
+Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path.
+
 ## Tool parameters
 
 | Parameter     | Description                                                         |
diff --git a/docs/cli/config.md b/docs/cli/config.md
index 72ba3af0c9d..1eb376f0fa0 100644
--- a/docs/cli/config.md
+++ b/docs/cli/config.md
@@ -21,7 +21,7 @@ openclaw config set agents.defaults.heartbeat.every "2h"
 openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
 openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
 openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
-openclaw config unset tools.web.search.apiKey
+openclaw config unset plugins.entries.brave.config.webSearch.apiKey
 openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
 openclaw config validate
 openclaw config validate --json
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index d15efb3384b..b8977ca10ac 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -46,7 +46,7 @@ See the [full reference](/gateway/configuration-reference) for every available f
     ```bash
     openclaw config get agents.defaults.workspace
     openclaw config set agents.defaults.heartbeat.every "2h"
-    openclaw config unset tools.web.search.apiKey
+    openclaw config unset plugins.entries.brave.config.webSearch.apiKey
     ```
   </Tab>
   <Tab title="Control UI">
diff --git a/docs/help/faq.md b/docs/help/faq.md
index cc52aafd604..49b19708cc7 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -1505,12 +1505,22 @@ Environment alternatives:
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
         provider: "brave",
-        apiKey: "BRAVE_API_KEY_HERE",
         maxResults: 5,
       },
       fetch: {
@@ -1521,6 +1531,9 @@ Environment alternatives:
 }
 ```
 
+Provider-specific web-search config now lives under `plugins.entries.<plugin>.config.webSearch.*`.
+Legacy `tools.web.search.*` provider paths still load temporarily for compatibility, but they should not be used for new configs.
+
 Notes:
 
 - If you use allowlists, add `web_search`/`web_fetch` or `group:web`.
diff --git a/docs/ja-JP/start/wizard.md b/docs/ja-JP/start/wizard.md
index 19f53125857..d7a9a77bb57 100644
--- a/docs/ja-JP/start/wizard.md
+++ b/docs/ja-JP/start/wizard.md
@@ -67,7 +67,7 @@ openclaw agents add <name>
 </Note>
 
 <Tip>
-推奨：エージェントが `web_search` を使用できるように、Brave Search APIキーを設定してください（`web_fetch` はキーなしで動作します）。最も簡単な方法：`openclaw configure --section web` を実行すると `tools.web.search.apiKey` が保存されます。ドキュメント：[Webツール](/tools/web)。
+推奨：エージェントが `web_search` を使用できるように、Brave Search APIキーを設定してください（`web_fetch` はキーなしで動作します）。最も簡単な方法：`openclaw configure --section web` を実行すると `plugins.entries.brave.config.webSearch.apiKey` に保存されます。旧 `tools.web.search.apiKey` パスは互換用に引き続き読み込まれますが、新しい設定では使用しないでください。ドキュメント：[Webツール](/tools/web)。
 </Tip>
 
 ## 関連ドキュメント
diff --git a/docs/perplexity.md b/docs/perplexity.md
index b71f34d666b..3ad4c50c3f7 100644
--- a/docs/perplexity.md
+++ b/docs/perplexity.md
@@ -12,7 +12,7 @@ OpenClaw supports Perplexity Search API as a `web_search` provider.
 It returns structured results with `title`, `url`, and `snippet` fields.
 
 For compatibility, OpenClaw also supports legacy Perplexity Sonar/OpenRouter setups.
-If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `tools.web.search.perplexity.apiKey`, or set `tools.web.search.perplexity.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
+If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`, or set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
 
 ## Getting a Perplexity API key
 
@@ -22,12 +22,12 @@ If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `tools.web.search.perplex
 
 ## OpenRouter compatibility
 
-If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `tools.web.search.perplexity.apiKey`.
+If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`.
 
-Optional legacy controls:
+Optional compatibility controls:
 
-- `tools.web.search.perplexity.baseUrl`
-- `tools.web.search.perplexity.model`
+- `plugins.entries.perplexity.config.webSearch.baseUrl`
+- `plugins.entries.perplexity.config.webSearch.model`
 
 ## Config examples
 
@@ -35,13 +35,21 @@ Optional legacy controls:
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-        },
       },
     },
   },
@@ -52,15 +60,23 @@ Optional legacy controls:
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "<openrouter-api-key>",
+            baseUrl: "https://openrouter.ai/api/v1",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "perplexity",
-        perplexity: {
-          apiKey: "<openrouter-api-key>",
-          baseUrl: "https://openrouter.ai/api/v1",
-          model: "perplexity/sonar-pro",
-        },
       },
     },
   },
@@ -70,7 +86,7 @@ Optional legacy controls:
 ## Where to set the key
 
 **Via config:** run `openclaw configure --section web`. It stores the key in
-`~/.openclaw/openclaw.json` under `tools.web.search.perplexity.apiKey`.
+`~/.openclaw/openclaw.json` under `plugins.entries.perplexity.config.webSearch.apiKey`.
 That field also accepts SecretRef objects.
 
 **Via environment:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
@@ -151,7 +167,7 @@ await web_search({
 ## Notes
 
 - Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
-- OpenRouter or explicit `baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
+- OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
 - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
 
 See [Web tools](/tools/web) for the full web_search configuration.
diff --git a/docs/reference/api-usage-costs.md b/docs/reference/api-usage-costs.md
index bbb1d90de87..bfa08e4194b 100644
--- a/docs/reference/api-usage-costs.md
+++ b/docs/reference/api-usage-costs.md
@@ -79,11 +79,13 @@ See [Memory](/concepts/memory).
 
 `web_search` uses API keys and may incur usage charges depending on your provider:
 
-- **Brave Search API**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
-- **Gemini (Google Search)**: `GEMINI_API_KEY` or `tools.web.search.gemini.apiKey`
-- **Grok (xAI)**: `XAI_API_KEY` or `tools.web.search.grok.apiKey`
-- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `tools.web.search.kimi.apiKey`
-- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey`
+- **Brave Search API**: `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
+- **Gemini (Google Search)**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
+- **Grok (xAI)**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
+- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
+- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
+
+Legacy `tools.web.search.*` provider paths still load through the temporary compatibility shim, but they are no longer the recommended config surface.
 
 **Brave Search free credit:** Each Brave plan includes \$5/month in renewing
 free credit. The Search plan costs \$5 per 1,000 requests, so the credit covers
diff --git a/docs/reference/secretref-credential-surface.md b/docs/reference/secretref-credential-surface.md
index 9f73c7d0112..4af529c640f 100644
--- a/docs/reference/secretref-credential-surface.md
+++ b/docs/reference/secretref-credential-surface.md
@@ -32,11 +32,12 @@ Scope intent:
 - `messages.tts.elevenlabs.apiKey`
 - `messages.tts.openai.apiKey`
 - `tools.web.fetch.firecrawl.apiKey`
-- `tools.web.search.apiKey`
-- `tools.web.search.gemini.apiKey`
-- `tools.web.search.grok.apiKey`
-- `tools.web.search.kimi.apiKey`
-- `tools.web.search.perplexity.apiKey`
+- `plugins.entries.brave.config.webSearch.apiKey`
+- `plugins.entries.google.config.webSearch.apiKey`
+- `plugins.entries.xai.config.webSearch.apiKey`
+- `plugins.entries.moonshot.config.webSearch.apiKey`
+- `plugins.entries.perplexity.config.webSearch.apiKey`
+- `plugins.entries.firecrawl.config.webSearch.apiKey`
 - `gateway.auth.password`
 - `gateway.auth.token`
 - `gateway.remote.token`
@@ -108,6 +109,7 @@ Notes:
   - In explicit provider mode (`tools.web.search.provider` set), only the selected provider key is active.
   - In auto mode (`tools.web.search.provider` unset), only the first provider key that resolves by precedence is active.
   - In auto mode, non-selected provider refs are treated as inactive until selected.
+  - Legacy `tools.web.search.*` provider paths still resolve during the compatibility window, but the canonical SecretRef surface is `plugins.entries.<plugin>.config.webSearch.*`.
 
 ## Unsupported credentials
 
diff --git a/docs/reference/secretref-user-supplied-credentials-matrix.json b/docs/reference/secretref-user-supplied-credentials-matrix.json
index f72729dbadc..ff05f16e909 100644
--- a/docs/reference/secretref-user-supplied-credentials-matrix.json
+++ b/docs/reference/secretref-user-supplied-credentials-matrix.json
@@ -476,37 +476,44 @@
       "optIn": true
     },
     {
-      "id": "tools.web.search.apiKey",
+      "id": "plugins.entries.brave.config.webSearch.apiKey",
       "configFile": "openclaw.json",
-      "path": "tools.web.search.apiKey",
+      "path": "plugins.entries.brave.config.webSearch.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     },
     {
-      "id": "tools.web.search.gemini.apiKey",
+      "id": "plugins.entries.google.config.webSearch.apiKey",
       "configFile": "openclaw.json",
-      "path": "tools.web.search.gemini.apiKey",
+      "path": "plugins.entries.google.config.webSearch.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     },
     {
-      "id": "tools.web.search.grok.apiKey",
+      "id": "plugins.entries.xai.config.webSearch.apiKey",
       "configFile": "openclaw.json",
-      "path": "tools.web.search.grok.apiKey",
+      "path": "plugins.entries.xai.config.webSearch.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     },
     {
-      "id": "tools.web.search.kimi.apiKey",
+      "id": "plugins.entries.moonshot.config.webSearch.apiKey",
       "configFile": "openclaw.json",
-      "path": "tools.web.search.kimi.apiKey",
+      "path": "plugins.entries.moonshot.config.webSearch.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     },
     {
-      "id": "tools.web.search.perplexity.apiKey",
+      "id": "plugins.entries.perplexity.config.webSearch.apiKey",
       "configFile": "openclaw.json",
-      "path": "tools.web.search.perplexity.apiKey",
+      "path": "plugins.entries.perplexity.config.webSearch.apiKey",
+      "secretShape": "secret_input",
+      "optIn": true
+    },
+    {
+      "id": "plugins.entries.firecrawl.config.webSearch.apiKey",
+      "configFile": "openclaw.json",
+      "path": "plugins.entries.firecrawl.config.webSearch.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     }
diff --git a/docs/tools/firecrawl.md b/docs/tools/firecrawl.md
index 901890dfb0a..eab0439311f 100644
--- a/docs/tools/firecrawl.md
+++ b/docs/tools/firecrawl.md
@@ -28,20 +28,22 @@ which helps with JS-heavy sites or pages that block plain HTTP fetches.
 
 ```json5
 {
-  plugins: {
-    entries: {
-      firecrawl: {
-        enabled: true,
-      },
-    },
-  },
   tools: {
     web: {
       search: {
         provider: "firecrawl",
-        firecrawl: {
-          apiKey: "FIRECRAWL_API_KEY_HERE",
-          baseUrl: "https://api.firecrawl.dev",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      firecrawl: {
+        enabled: true,
+        config: {
+          webSearch: {
+            apiKey: "FIRECRAWL_API_KEY_HERE",
+            baseUrl: "https://api.firecrawl.dev",
+          },
         },
       },
     },
diff --git a/docs/tools/web.md b/docs/tools/web.md
index 7cc67c07710..0e30c6c9c7c 100644
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -43,12 +43,12 @@ See [Brave Search setup](/brave-search) and [Perplexity Search setup](/perplexit
 
 The table above is alphabetical. If no `provider` is explicitly set, runtime auto-detection checks providers in this order:
 
-1. **Brave** — `BRAVE_API_KEY` env var or `tools.web.search.apiKey` config
-2. **Gemini** — `GEMINI_API_KEY` env var or `tools.web.search.gemini.apiKey` config
-3. **Grok** — `XAI_API_KEY` env var or `tools.web.search.grok.apiKey` config
-4. **Kimi** — `KIMI_API_KEY` / `MOONSHOT_API_KEY` env var or `tools.web.search.kimi.apiKey` config
-5. **Perplexity** — `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey` config
-6. **Firecrawl** — `FIRECRAWL_API_KEY` env var or `tools.web.search.firecrawl.apiKey` config
+1. **Brave** — `BRAVE_API_KEY` env var or `plugins.entries.brave.config.webSearch.apiKey`
+2. **Gemini** — `GEMINI_API_KEY` env var or `plugins.entries.google.config.webSearch.apiKey`
+3. **Grok** — `XAI_API_KEY` env var or `plugins.entries.xai.config.webSearch.apiKey`
+4. **Kimi** — `KIMI_API_KEY` / `MOONSHOT_API_KEY` env var or `plugins.entries.moonshot.config.webSearch.apiKey`
+5. **Perplexity** — `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
+6. **Firecrawl** — `FIRECRAWL_API_KEY` env var or `plugins.entries.firecrawl.config.webSearch.apiKey`
 
 If no keys are found, it falls back to Brave (you'll get a missing-key error prompting you to configure one).
 
@@ -80,7 +80,10 @@ pricing.
 2. Generate an API key in the dashboard
 3. Run `openclaw configure --section web` to store the key in config, or set `PERPLEXITY_API_KEY` in your environment.
 
-For legacy Sonar/OpenRouter compatibility, set `OPENROUTER_API_KEY` instead, or configure `tools.web.search.perplexity.apiKey` with an `sk-or-...` key. Setting `tools.web.search.perplexity.baseUrl` or `model` also opts Perplexity back into the chat-completions compatibility path.
+For legacy Sonar/OpenRouter compatibility, set `OPENROUTER_API_KEY` instead, or configure `plugins.entries.perplexity.config.webSearch.apiKey` with an `sk-or-...` key. Setting `plugins.entries.perplexity.config.webSearch.baseUrl` or `model` also opts Perplexity back into the chat-completions compatibility path.
+
+Provider-specific web search config now lives under `plugins.entries.<plugin>.config.webSearch.*`.
+Legacy `tools.web.search.*` provider paths still load through a compatibility shim for one release, but they should not be used in new configs.
 
 See [Perplexity Search API Docs](https://docs.perplexity.ai/guides/search-quickstart) for more details.
 
@@ -88,12 +91,12 @@ See [Perplexity Search API Docs](https://docs.perplexity.ai/guides/search-quicks
 
 **Via config:** run `openclaw configure --section web`. It stores the key under the provider-specific config path:
 
-- Brave: `tools.web.search.apiKey`
-- Firecrawl: `tools.web.search.firecrawl.apiKey`
-- Gemini: `tools.web.search.gemini.apiKey`
-- Grok: `tools.web.search.grok.apiKey`
-- Kimi: `tools.web.search.kimi.apiKey`
-- Perplexity: `tools.web.search.perplexity.apiKey`
+- Brave: `plugins.entries.brave.config.webSearch.apiKey`
+- Firecrawl: `plugins.entries.firecrawl.config.webSearch.apiKey`
+- Gemini: `plugins.entries.google.config.webSearch.apiKey`
+- Grok: `plugins.entries.xai.config.webSearch.apiKey`
+- Kimi: `plugins.entries.moonshot.config.webSearch.apiKey`
+- Perplexity: `plugins.entries.perplexity.config.webSearch.apiKey`
 
 All of these fields also support SecretRef objects.
 
@@ -114,12 +117,22 @@ For a gateway install, put these in `~/.openclaw/.env` (or your service environm
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
         provider: "brave",
-        apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
       },
     },
   },
@@ -142,9 +155,18 @@ For a gateway install, put these in `~/.openclaw/.env` (or your service environm
       search: {
         enabled: true,
         provider: "firecrawl",
-        firecrawl: {
-          apiKey: "fc-...", // optional if FIRECRAWL_API_KEY is set
-          baseUrl: "https://api.firecrawl.dev",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      firecrawl: {
+        enabled: true,
+        config: {
+          webSearch: {
+            apiKey: "fc-...", // optional if FIRECRAWL_API_KEY is set
+            baseUrl: "https://api.firecrawl.dev",
+          },
         },
       },
     },
@@ -158,15 +180,23 @@ When you choose Firecrawl in onboarding or `openclaw configure --section web`, O
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
+            mode: "llm-context",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
         provider: "brave",
-        apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
-        brave: {
-          mode: "llm-context",
-        },
       },
     },
   },
@@ -181,14 +211,22 @@ In this mode, `country` and `language` / `search_lang` still work, but `ui_lang`
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
         provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
-        },
       },
     },
   },
@@ -199,16 +237,24 @@ In this mode, `country` and `language` / `search_lang` still work, but `ui_lang`
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "<openrouter-api-key>", // optional if OPENROUTER_API_KEY is set
+            baseUrl: "https://openrouter.ai/api/v1",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
         provider: "perplexity",
-        perplexity: {
-          apiKey: "<openrouter-api-key>", // optional if OPENROUTER_API_KEY is set
-          baseUrl: "https://openrouter.ai/api/v1",
-          model: "perplexity/sonar-pro",
-        },
       },
     },
   },
@@ -224,22 +270,30 @@ which returns AI-synthesized answers backed by live Google Search results with c
 
 1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
 2. Create an API key
-3. Set `GEMINI_API_KEY` in the Gateway environment, or configure `tools.web.search.gemini.apiKey`
+3. Set `GEMINI_API_KEY` in the Gateway environment, or configure `plugins.entries.google.config.webSearch.apiKey`
 
 ### Setting up Gemini search
 
 ```json5
 {
+  plugins: {
+    entries: {
+      google: {
+        config: {
+          webSearch: {
+            // API key (optional if GEMINI_API_KEY is set)
+            apiKey: "AIza...",
+            // Model (defaults to "gemini-2.5-flash")
+            model: "gemini-2.5-flash",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "gemini",
-        gemini: {
-          // API key (optional if GEMINI_API_KEY is set)
-          apiKey: "AIza...",
-          // Model (defaults to "gemini-2.5-flash")
-          model: "gemini-2.5-flash",
-        },
       },
     },
   },
@@ -266,12 +320,12 @@ Search the web using your configured provider.
 
 - `tools.web.search.enabled` must not be `false` (default: enabled)
 - API key for your chosen provider:
-  - **Brave**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
-  - **Firecrawl**: `FIRECRAWL_API_KEY` or `tools.web.search.firecrawl.apiKey`
-  - **Gemini**: `GEMINI_API_KEY` or `tools.web.search.gemini.apiKey`
-  - **Grok**: `XAI_API_KEY` or `tools.web.search.grok.apiKey`
-  - **Kimi**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `tools.web.search.kimi.apiKey`
-  - **Perplexity**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey`
+  - **Brave**: `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
+  - **Firecrawl**: `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey`
+  - **Gemini**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
+  - **Grok**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
+  - **Kimi**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
+  - **Perplexity**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
 - All provider key fields above support SecretRef objects.
 
 ### Config
@@ -297,7 +351,7 @@ Search the web using your configured provider.
 Parameters depend on the selected provider.
 
 Perplexity's OpenRouter / Sonar compatibility path supports only `query` and `freshness`.
-If you set `tools.web.search.perplexity.baseUrl` / `model`, use `OPENROUTER_API_KEY`, or configure an `sk-or-...` key, Search API-only filters return explicit errors.
+If you set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, use `OPENROUTER_API_KEY`, or configure an `sk-or-...` key under `plugins.entries.perplexity.config.webSearch.apiKey`, Search API-only filters return explicit errors.
 
 | Parameter             | Description                                           |
 | --------------------- | ----------------------------------------------------- |
diff --git a/docs/zh-CN/brave-search.md b/docs/zh-CN/brave-search.md
index d69d45f04d3..1f63d2441d0 100644
--- a/docs/zh-CN/brave-search.md
+++ b/docs/zh-CN/brave-search.md
@@ -27,11 +27,21 @@ OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "brave",
-        apiKey: "BRAVE_API_KEY_HERE",
         maxResults: 5,
         timeoutSeconds: 30,
       },
@@ -40,6 +50,8 @@ OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。
 }
 ```
 
+Brave 的提供商专属搜索配置现在位于 `plugins.entries.brave.config.webSearch.*`。旧的 `tools.web.search.apiKey` 仅作为兼容层暂时保留。
+
 ## 注意事项
 
 - Data for AI 套餐与 `web_search` **不**兼容。
diff --git a/docs/zh-CN/cli/config.md b/docs/zh-CN/cli/config.md
index 06efbaec751..9c63985ab96 100644
--- a/docs/zh-CN/cli/config.md
+++ b/docs/zh-CN/cli/config.md
@@ -24,7 +24,7 @@ openclaw config get browser.executablePath
 openclaw config set browser.executablePath "/usr/bin/google-chrome"
 openclaw config set agents.defaults.heartbeat.every "2h"
 openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
-openclaw config unset tools.web.search.apiKey
+openclaw config unset plugins.entries.brave.config.webSearch.apiKey
 ```
 
 ## 路径
diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md
index 49c62eea4c9..86b0e50b4d7 100644
--- a/docs/zh-CN/gateway/configuration.md
+++ b/docs/zh-CN/gateway/configuration.md
@@ -53,7 +53,7 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5
     ```bash
     openclaw config get agents.defaults.workspace
     openclaw config set agents.defaults.heartbeat.every "2h"
-    openclaw config unset tools.web.search.apiKey
+    openclaw config unset plugins.entries.brave.config.webSearch.apiKey
     ```
   </Tab>
   <Tab title="Control UI">
diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md
index 18b936e2cc8..b5531457484 100644
--- a/docs/zh-CN/help/faq.md
+++ b/docs/zh-CN/help/faq.md
@@ -1266,15 +1266,26 @@ Gateway 网关监视配置文件并支持热重载：
 
 ### 如何启用网络搜索（和网页抓取）
 
-`web_fetch` 无需 API 密钥即可工作。`web_search` 需要 Brave Search API 密钥。**推荐：** 运行 `openclaw configure --section web` 将其存储在 `tools.web.search.apiKey` 中。环境变量替代方案：为 Gateway 网关进程设置 `BRAVE_API_KEY`。
+`web_fetch` 无需 API 密钥即可工作。`web_search` 需要所选提供商的 API 密钥。**推荐：** 运行 `openclaw configure --section web`。新的提供商专属配置会存储在 `plugins.entries.<plugin>.config.webSearch.*` 下。环境变量替代方案：为 Gateway 网关进程设置相应的提供商环境变量。
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
-        apiKey: "BRAVE_API_KEY_HERE",
+        provider: "brave",
         maxResults: 5,
       },
       fetch: {
@@ -1290,6 +1301,7 @@ Gateway 网关监视配置文件并支持热重载：
 - 如果你使用允许列表，添加 `web_search`/`web_fetch` 或 `group:web`。
 - `web_fetch` 默认启用（除非明确禁用）。
 - 守护进程从 `~/.openclaw/.env`（或服务环境）读取环境变量。
+- 旧的 `tools.web.search.*` 提供商路径仍通过兼容层继续生效，但不应再用于新配置。
 
 文档：[Web 工具](/tools/web)。
 
diff --git a/docs/zh-CN/perplexity.md b/docs/zh-CN/perplexity.md
index 56a7505b302..ae9b4a05c72 100644
--- a/docs/zh-CN/perplexity.md
+++ b/docs/zh-CN/perplexity.md
@@ -34,15 +34,23 @@ OpenClaw 可以使用 Perplexity Sonar 作为 `web_search` 工具。你可以通
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+            baseUrl: "https://api.perplexity.ai",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-          model: "perplexity/sonar-pro",
-        },
       },
     },
   },
@@ -53,21 +61,31 @@ OpenClaw 可以使用 Perplexity Sonar 作为 `web_search` 工具。你可以通
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+            baseUrl: "https://api.perplexity.ai",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-        },
       },
     },
   },
 }
 ```
 
-如果同时设置了 `PERPLEXITY_API_KEY` 和 `OPENROUTER_API_KEY`，请设置 `tools.web.search.perplexity.baseUrl`（或 `tools.web.search.perplexity.apiKey`）以消除歧义。
+如果同时设置了 `PERPLEXITY_API_KEY` 和 `OPENROUTER_API_KEY`，请设置 `plugins.entries.perplexity.config.webSearch.baseUrl`（或 `plugins.entries.perplexity.config.webSearch.apiKey`）以消除歧义。
+
+提供商专属配置现在统一放在 `plugins.entries.<plugin>.config.webSearch.*`。旧的 `tools.web.search.*` 路径仅通过兼容层继续生效，不再推荐用于新配置。
 
 如果未设置 base URL，OpenClaw 会根据 API 密钥来源选择默认值：
 
diff --git a/docs/zh-CN/reference/api-usage-costs.md b/docs/zh-CN/reference/api-usage-costs.md
index feb62d60c6d..91d4bf1160c 100644
--- a/docs/zh-CN/reference/api-usage-costs.md
+++ b/docs/zh-CN/reference/api-usage-costs.md
@@ -79,8 +79,13 @@ OpenClaw 可以从以下来源获取凭据：
 
 `web_search` 使用 API 密钥，可能产生使用费用：
 
-- **Brave Search API**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
-- **Perplexity**（通过 OpenRouter）：`PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY`
+- **Brave Search API**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`
+- **Gemini**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey`
+- **Grok**：`XAI_API_KEY` 或 `plugins.entries.xai.config.webSearch.apiKey`
+- **Kimi**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey`
+- **Perplexity**：`PERPLEXITY_API_KEY`、`OPENROUTER_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey`
+
+旧的 `tools.web.search.*` 提供商路径仍会通过兼容层加载，但不再是推荐配置方式。
 
 **Brave 免费套餐（额度充裕）：**
 
diff --git a/docs/zh-CN/tools/web.md b/docs/zh-CN/tools/web.md
index 17c346dc64e..44026c67e29 100644
--- a/docs/zh-CN/tools/web.md
+++ b/docs/zh-CN/tools/web.md
@@ -18,7 +18,7 @@ x-i18n:
 
 OpenClaw 提供两个轻量级 Web 工具：
 
-- `web_search` — 通过 Brave Search API（默认）或 Perplexity Sonar（直连或通过 OpenRouter）搜索网络。
+- `web_search` — 通过 Brave Search API、Firecrawl Search、Gemini with Google Search grounding、Grok、Kimi 或 Perplexity Search API 搜索网络。
 - `web_fetch` — HTTP 获取 + 可读性提取（HTML → markdown/文本）。
 
 这些**不是**浏览器自动化。对于 JS 密集型网站或需要登录的情况，请使用[浏览器工具](/tools/browser)。
@@ -26,18 +26,21 @@ OpenClaw 提供两个轻量级 Web 工具：
 ## 工作原理
 
 - `web_search` 调用你配置的提供商并返回结果。
-  - **Brave**（默认）：返回结构化结果（标题、URL、摘要）。
-  - **Perplexity**：返回带有实时网络搜索引用的 AI 综合答案。
 - 结果按查询缓存 15 分钟（可配置）。
 - `web_fetch` 执行普通 HTTP GET 并提取可读内容（HTML → markdown/文本）。它**不**执行 JavaScript。
 - `web_fetch` 默认启用（除非显式禁用）。
+- 启用捆绑的 Firecrawl 插件后，还会提供 `firecrawl_search` 和 `firecrawl_scrape`。
 
 ## 选择搜索提供商
 
-| 提供商            | 优点                     | 缺点                               | API 密钥                                     |
-| ----------------- | ------------------------ | ---------------------------------- | -------------------------------------------- |
-| **Brave**（默认） | 快速、结构化结果、免费层 | 传统搜索结果                       | `BRAVE_API_KEY`                              |
-| **Perplexity**    | AI 综合答案、引用、实时  | 需要 Perplexity 或 OpenRouter 访问 | `OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY` |
+| 提供商                | 结果形式           | 说明                                            | API 密钥                                    |
+| --------------------- | ------------------ | ----------------------------------------------- | ------------------------------------------- |
+| **Brave Search API**  | 结构化结果 + 摘要  | 支持 Brave `llm-context` 模式                   | `BRAVE_API_KEY`                             |
+| **Firecrawl Search**  | 结构化结果 + 摘要  | Firecrawl 专用搜索控制请使用 `firecrawl_search` | `FIRECRAWL_API_KEY`                         |
+| **Gemini**            | AI 综合答案 + 引用 | 使用 Google Search grounding                    | `GEMINI_API_KEY`                            |
+| **Grok**              | AI 综合答案 + 引用 | 使用 xAI 实时网络搜索                           | `XAI_API_KEY`                               |
+| **Kimi**              | AI 综合答案 + 引用 | 使用 Moonshot web search                        | `KIMI_API_KEY` / `MOONSHOT_API_KEY`         |
+| **Perplexity Search** | 结构化结果 + 摘要  | 兼容 OpenRouter Sonar 路径                      | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
 
 参见 [Brave Search 设置](/brave-search) 和 [Perplexity Sonar](/perplexity) 了解提供商特定详情。
 
@@ -48,26 +51,34 @@ OpenClaw 提供两个轻量级 Web 工具：
   tools: {
     web: {
       search: {
-        provider: "brave", // 或 "perplexity"
+        provider: "brave", // 或 "firecrawl" | "gemini" | "grok" | "kimi" | "perplexity"
       },
     },
   },
 }
 ```
 
-示例：切换到 Perplexity Sonar（直连 API）：
+示例：切换到 Perplexity Search / Sonar 兼容路径：
 
 ```json5
 {
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+            baseUrl: "https://api.perplexity.ai",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-          baseUrl: "https://api.perplexity.ai",
-          model: "perplexity/sonar-pro",
-        },
       },
     },
   },
@@ -84,7 +95,7 @@ Brave 提供免费层和付费计划；查看 Brave API 门户了解当前限制
 
 ### 在哪里设置密钥（推荐）
 
-**推荐：** 运行 `openclaw configure --section web`。它将密钥存储在 `~/.openclaw/openclaw.json` 的 `tools.web.search.apiKey` 下。
+**推荐：** 运行 `openclaw configure --section web`。它会把密钥存储到 `~/.openclaw/openclaw.json` 的 `plugins.entries.brave.config.webSearch.apiKey`。
 
 **环境变量替代方案：** 在 Gateway 网关进程环境中设置 `BRAVE_API_KEY`。对于 Gateway 网关安装，将其放在 `~/.openclaw/.env`（或你的服务环境）中。参见[环境变量](/help/faq#how-does-openclaw-load-environment-variables)。
 
@@ -107,13 +118,21 @@ Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用
       search: {
         enabled: true,
         provider: "perplexity",
-        perplexity: {
-          // API 密钥（如果设置了 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 则可选）
-          apiKey: "sk-or-v1-...",
-          // 基础 URL（如果省略则根据密钥感知默认值）
-          baseUrl: "https://openrouter.ai/api/v1",
-          // 模型（默认为 perplexity/sonar-pro）
-          model: "perplexity/sonar-pro",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            // API 密钥（如果设置了 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 则可选）
+            apiKey: "sk-or-v1-...",
+            // 基础 URL（如果省略则根据密钥感知默认值）
+            baseUrl: "https://openrouter.ai/api/v1",
+            // 模型（默认为 perplexity/sonar-pro）
+            model: "perplexity/sonar-pro",
+          },
         },
       },
     },
@@ -145,18 +164,28 @@ Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用
 
 - `tools.web.search.enabled` 不能为 `false`（默认：启用）
 - 所选提供商的 API 密钥：
-  - **Brave**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
-  - **Perplexity**：`OPENROUTER_API_KEY`、`PERPLEXITY_API_KEY` 或 `tools.web.search.perplexity.apiKey`
+  - **Brave**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`
+  - **Perplexity**：`OPENROUTER_API_KEY`、`PERPLEXITY_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey`
 
 ### 配置
 
 ```json5
 {
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+          },
+        },
+      },
+    },
+  },
   tools: {
     web: {
       search: {
         enabled: true,
-        apiKey: "BRAVE_API_KEY_HERE", // 如果设置了 BRAVE_API_KEY 则可选
         maxResults: 5,
         timeoutSeconds: 30,
         cacheTtlMinutes: 15,
@@ -166,6 +195,9 @@ Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用
 }
 ```
 
+提供商专属的 web_search 配置现在统一放在 `plugins.entries.<plugin>.config.webSearch.*`。
+旧的 `tools.web.search.*` 提供商路径仅作为兼容层暂时保留，不应再用于新配置。
+
 ### 工具参数
 
 - `query`（必需）
diff --git a/extensions/firecrawl/src/firecrawl-client.ts b/extensions/firecrawl/src/firecrawl-client.ts
index 18500d81c14..565e1d6aac3 100644
--- a/extensions/firecrawl/src/firecrawl-client.ts
+++ b/extensions/firecrawl/src/firecrawl-client.ts
@@ -234,7 +234,7 @@ export async function runFirecrawlSearch(
   const apiKey = resolveFirecrawlApiKey(params.cfg);
   if (!apiKey) {
     throw new Error(
-      "web_search (firecrawl) needs a Firecrawl API key. Set FIRECRAWL_API_KEY in the Gateway environment, or configure tools.web.search.firecrawl.apiKey.",
+      "web_search (firecrawl) needs a Firecrawl API key. Set FIRECRAWL_API_KEY in the Gateway environment, or configure plugins.entries.firecrawl.config.webSearch.apiKey.",
     );
   }
   const count =
diff --git a/extensions/xai/web-search.ts b/extensions/xai/web-search.ts
index 5728731d7ab..6202e18f4bd 100644
--- a/extensions/xai/web-search.ts
+++ b/extensions/xai/web-search.ts
@@ -238,7 +238,7 @@ export function createXaiWebSearchProvider() {
           return {
             error: "missing_xai_api_key",
             message:
-              "web_search (grok) needs an xAI API key. Set XAI_API_KEY in the Gateway environment, or configure tools.web.search.grok.apiKey.",
+              "web_search (grok) needs an xAI API key. Set XAI_API_KEY in the Gateway environment, or configure plugins.entries.xai.config.webSearch.apiKey.",
             docs: "https://docs.openclaw.ai/tools/web",
           };
         }