docs: use alphabetical provider ordering

AGENTS.md

@@ -28,6 +28,7 @@
 - Docs are hosted on Mintlify (docs.openclaw.ai).
 - Internal doc links in `docs/**/*.md`: root-relative, no `.md`/`.mdx` (example: `[Config](/configuration)`).
 - When working with documentation, read the mintlify skill.
+- For docs, UI copy, and picker lists, order services/providers alphabetically unless the section is explicitly describing runtime behavior (for example auto-detection or execution order).
 - Section cross-references: use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
 - Doc headings and anchors: avoid em dashes and apostrophes in headings because they break Mintlify anchor links.
 - When Peter asks for links, reply with full `https://docs.openclaw.ai/...` URLs (not root-relative).

docs/brave-search.md

@@ -8,13 +8,13 @@ title: "Brave Search"
 
 # Brave Search API
 
-OpenClaw supports Brave Search as a web search provider for `web_search`.
+OpenClaw supports Brave Search API as a `web_search` provider.
 
 ## Get an API key
 
 1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
 2. In the dashboard, choose the **Data for Search** plan and generate an API key.
-3. Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment.
+3. Store the key in config or set `BRAVE_API_KEY` in the Gateway environment.
 
 ## Config example
 

docs/perplexity.md

@@ -8,14 +8,14 @@ title: "Perplexity Search"
 
 # Perplexity Search API
 
-OpenClaw uses Perplexity Search API for the `web_search` tool when `provider: "perplexity"` is set.
+OpenClaw supports Perplexity Search API as a `web_search` provider.
-Perplexity Search returns structured results (title, URL, snippet) for fast research.
+It returns structured results with `title`, `url`, and `snippet` fields.
 
 ## Getting a Perplexity API key
 
 1. Create a Perplexity account at <https://www.perplexity.ai/settings/api>
 2. Generate an API key in the dashboard
-3. Store the key in config (recommended) or set `PERPLEXITY_API_KEY` in the Gateway environment.
+3. Store the key in config or set `PERPLEXITY_API_KEY` in the Gateway environment.
 
 ## Config example
 
@@ -34,29 +34,12 @@ Perplexity Search returns structured results (title, URL, snippet) for fast rese
 }
 ```
 
-## Switching from Brave
+## Where to set the key
 
-```json5
+**Via config:** run `openclaw configure --section web`. It stores the key in
-{
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...",
-        },
-      },
-    },
-  },
-}
-```
-
-## Where to set the key (recommended)
-
-**Recommended:** run `openclaw configure --section web`. It stores the key in
 `~/.openclaw/openclaw.json` under `tools.web.search.perplexity.apiKey`.
 
-**Environment alternative:** set `PERPLEXITY_API_KEY` in the Gateway process
+**Via environment:** set `PERPLEXITY_API_KEY` in the Gateway process
 environment. For a gateway install, put it in `~/.openclaw/.env` (or your
 service environment). See [Env vars](/help/faq#how-does-openclaw-load-environment-variables).
 
@@ -126,7 +109,7 @@ await web_search({
 
 ## Notes
 
-- Perplexity Search API returns structured web search results (title, URL, snippet)
+- Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
 - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
 
 See [Web tools](/tools/web) for the full web_search configuration.

docs/tools/web.md

@@ -1,8 +1,8 @@
 ---
-summary: "Web search + fetch tools (Perplexity Search API, Brave, Gemini, Grok, and Kimi providers)"
+summary: "Web search + fetch tools (Brave, Gemini, Grok, Kimi, and Perplexity providers)"
 read_when:
   - You want to enable web_search or web_fetch
-  - You need Perplexity or Brave Search API key setup
+  - You need Brave or Perplexity Search API key setup
   - You want to use Gemini with Google Search grounding
 title: "Web Tools"
 ---
@@ -11,7 +11,7 @@ title: "Web Tools"
 
 OpenClaw ships two lightweight web tools:
 
-- `web_search` — Search the web using Perplexity Search API, Brave Search API, Gemini with Google Search grounding, Grok, or Kimi.
+- `web_search` — Search the web using Brave Search API, Gemini with Google Search grounding, Grok, Kimi, or Perplexity Search API.
 - `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).
 
 These are **not** browser automation. For JS-heavy sites or logins, use the
@@ -25,21 +25,21 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
   (HTML → markdown/text). It does **not** execute JavaScript.
 - `web_fetch` is enabled by default (unless explicitly disabled).
 
-See [Perplexity Search setup](/perplexity) and [Brave Search setup](/brave-search) for provider-specific details.
+See [Brave Search setup](/brave-search) and [Perplexity Search setup](/perplexity) for provider-specific details.
 
 ## Choosing a search provider
 
-| Provider                  | Pros                                                                                          | Cons                                        | API Key                             |
+| Provider                  | Result shape                       | Provider-specific filters                    | Notes                                | API key                             |
-| ------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------- |
+| ------------------------- | ---------------------------------- | -------------------------------------------- | ------------------------------------ | ----------------------------------- |
-| **Perplexity Search API** | Fast, structured results; domain, language, region, and freshness filters; content extraction | —                                           | `PERPLEXITY_API_KEY`                |
+| **Brave Search API**      | Structured results with snippets   | `country`, `language`, `ui_lang`, time       | Supports Brave `llm-context` mode    | `BRAVE_API_KEY`                     |
-| **Brave Search API**      | Fast, structured results                                                                      | Fewer filtering options; AI-use terms apply | `BRAVE_API_KEY`                     |
+| **Gemini**                | AI-synthesized answers + citations | —                                            | Uses Google Search grounding         | `GEMINI_API_KEY`                    |
-| **Gemini**                | Google Search grounding, AI-synthesized                                                       | Requires Gemini API key                     | `GEMINI_API_KEY`                    |
+| **Grok**                  | AI-synthesized answers + citations | —                                            | Uses xAI web-grounded responses      | `XAI_API_KEY`                       |
-| **Grok**                  | xAI web-grounded responses                                                                    | Requires xAI API key                        | `XAI_API_KEY`                       |
+| **Kimi**                  | AI-synthesized answers + citations | —                                            | Uses Moonshot web search             | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
-| **Kimi**                  | Moonshot web search capability                                                                | Requires Moonshot API key                   | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
+| **Perplexity Search API** | Structured results with snippets   | `country`, `language`, time, `domain_filter` | Supports content extraction controls | `PERPLEXITY_API_KEY`                |
 
 ### Auto-detection
 
-If no `provider` is explicitly set, OpenClaw auto-detects which provider to use based on available API keys, checking in this order:
+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
@@ -53,6 +53,14 @@ If no keys are found, it falls back to Brave (you'll get a missing-key error pro
 
 Use `openclaw configure --section web` to set up your API key and choose a provider.
 
+### Brave Search
+
+1. Create a Brave Search API account at [brave.com/search/api](https://brave.com/search/api/)
+2. In the dashboard, choose the **Data for Search** plan (not "Data for AI") and generate an API key.
+3. Run `openclaw configure --section web` to store the key in config, or set `BRAVE_API_KEY` in your environment.
+
+Brave provides paid plans; check the Brave API portal for the current limits and pricing.
+
 ### Perplexity Search
 
 1. Create a Perplexity account at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
@@ -61,40 +69,14 @@ Use `openclaw configure --section web` to set up your API key and choose a provi
 
 See [Perplexity Search API Docs](https://docs.perplexity.ai/guides/search-quickstart) for more details.
 
-### Brave Search
-
-1. Create a Brave Search API account at [brave.com/search/api](https://brave.com/search/api/)
-2. In the dashboard, choose the **Data for Search** plan (not "Data for AI") and generate an API key.
-3. Run `openclaw configure --section web` to store the key in config (recommended), or set `BRAVE_API_KEY` in your environment.
-
-Brave provides paid plans; check the Brave API portal for the current limits and pricing.
-
 ### Where to store the key
 
-**Via config (recommended):** run `openclaw configure --section web`. It stores the key under `tools.web.search.perplexity.apiKey` or `tools.web.search.apiKey`.
+**Via config:** run `openclaw configure --section web`. It stores the key under `tools.web.search.apiKey` or `tools.web.search.perplexity.apiKey`, depending on provider.
 
 **Via environment:** set `PERPLEXITY_API_KEY` or `BRAVE_API_KEY` in the Gateway process environment. For a gateway install, put it in `~/.openclaw/.env` (or your service environment). See [Env vars](/help/faq#how-does-openclaw-load-environment-variables).
 
 ### Config examples
 
-**Perplexity Search:**
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        enabled: true,
-        provider: "perplexity",
-        perplexity: {
-          apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
-        },
-      },
-    },
-  },
-}
-```
-
 **Brave Search:**
 
 ```json5
@@ -134,6 +116,24 @@ Brave provides paid plans; check the Brave API portal for the current limits and
 In this mode, `country` and `language` / `search_lang` still work, but `ui_lang`,
 `freshness`, `date_after`, and `date_before` are rejected.
 
+**Perplexity Search:**
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        provider: "perplexity",
+        perplexity: {
+          apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
+        },
+      },
+    },
+  },
+}
+```
+
 ## Using Gemini (Google Search grounding)
 
 Gemini models support built-in [Google Search grounding](https://ai.google.dev/gemini-api/docs/grounding),
@@ -186,10 +186,10 @@ 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`
-  - **Perplexity**: `PERPLEXITY_API_KEY` or `tools.web.search.perplexity.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` or `tools.web.search.perplexity.apiKey`
 
 ### Config
 

src/commands/configure.wizard.ts

@@ -188,7 +188,7 @@ async function promptWebToolsConfig(
     if (stored && SEARCH_PROVIDER_OPTIONS.some((e) => e.value === stored)) {
       return stored;
     }
-    return SEARCH_PROVIDER_OPTIONS.find((e) => hasKeyForProvider(e.value))?.value ?? "perplexity";
+    return SEARCH_PROVIDER_OPTIONS.find((e) => hasKeyForProvider(e.value))?.value ?? "brave";
   })();
 
   note(

src/commands/onboard-search.test.ts

@@ -286,6 +286,6 @@ describe("setupSearch", () => {
   it("exports all 5 providers in SEARCH_PROVIDER_OPTIONS", () => {
     expect(SEARCH_PROVIDER_OPTIONS).toHaveLength(5);
     const values = SEARCH_PROVIDER_OPTIONS.map((e) => e.value);
-    expect(values).toEqual(["perplexity", "brave", "gemini", "grok", "kimi"]);
+    expect(values).toEqual(["brave", "gemini", "grok", "kimi", "perplexity"]);
   });
 });

src/commands/onboard-search.ts

@@ -22,18 +22,10 @@ type SearchProviderEntry = {
 };
 
 export const SEARCH_PROVIDER_OPTIONS: readonly SearchProviderEntry[] = [
-  {
-    value: "perplexity",
-    label: "Perplexity Search",
-    hint: "Structured results · domain/language/freshness filters",
-    envKeys: ["PERPLEXITY_API_KEY"],
-    placeholder: "pplx-...",
-    signupUrl: "https://www.perplexity.ai/settings/api",
-  },
   {
     value: "brave",
     label: "Brave Search",
-    hint: "Structured results · region-specific",
+    hint: "Structured results · country/language/time filters",
     envKeys: ["BRAVE_API_KEY"],
     placeholder: "BSA...",
     signupUrl: "https://brave.com/search/api/",
@@ -62,6 +54,14 @@ export const SEARCH_PROVIDER_OPTIONS: readonly SearchProviderEntry[] = [
     placeholder: "sk-...",
     signupUrl: "https://platform.moonshot.cn/",
   },
+  {
+    value: "perplexity",
+    label: "Perplexity Search",
+    hint: "Structured results · domain/country/language/time filters",
+    envKeys: ["PERPLEXITY_API_KEY"],
+    placeholder: "pplx-...",
+    signupUrl: "https://www.perplexity.ai/settings/api",
+  },
 ] as const;
 
 export function hasKeyInEnv(entry: SearchProviderEntry): boolean {
@@ -222,7 +222,7 @@ export async function setupSearch(
     if (detected) {
       return detected.value;
     }
-    return "perplexity";
+    return "brave";
   })();
 
   type PickerValue = SearchProvider | "__skip__";