diff --git a/AGENTS.md b/AGENTS.md index 840522224fb..6aaee94b2ed 100644 --- a/AGENTS.md +++ b/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). diff --git a/docs/brave-search.md b/docs/brave-search.md index d8799de96e8..3b1e55c0aae 100644 --- a/docs/brave-search.md +++ b/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 diff --git a/docs/perplexity.md b/docs/perplexity.md index 3e8ac4a6837..85b4a7c48c8 100644 --- a/docs/perplexity.md +++ b/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. -Perplexity Search returns structured results (title, URL, snippet) for fast research. +OpenClaw supports Perplexity Search API as a `web_search` provider. +It returns structured results with `title`, `url`, and `snippet` fields. ## Getting a Perplexity API key 1. Create a Perplexity account at 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 -{ - 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 +**Via config:** 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. diff --git a/docs/tools/web.md b/docs/tools/web.md index df1918056ab..4884de6bc7b 100644 --- a/docs/tools/web.md +++ b/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 | -| ------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------- | -| **Perplexity Search API** | Fast, structured results; domain, language, region, and freshness filters; content extraction | — | `PERPLEXITY_API_KEY` | -| **Brave Search API** | Fast, structured results | Fewer filtering options; AI-use terms apply | `BRAVE_API_KEY` | -| **Gemini** | Google Search grounding, AI-synthesized | Requires Gemini API key | `GEMINI_API_KEY` | -| **Grok** | xAI web-grounded responses | Requires xAI API key | `XAI_API_KEY` | -| **Kimi** | Moonshot web search capability | Requires Moonshot API key | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | +| Provider | Result shape | Provider-specific filters | Notes | API key | +| ------------------------- | ---------------------------------- | -------------------------------------------- | ------------------------------------ | ----------------------------------- | +| **Brave Search API** | Structured results with snippets | `country`, `language`, `ui_lang`, time | Supports Brave `llm-context` mode | `BRAVE_API_KEY` | +| **Gemini** | AI-synthesized answers + citations | — | Uses Google Search grounding | `GEMINI_API_KEY` | +| **Grok** | AI-synthesized answers + citations | — | Uses xAI web-grounded responses | `XAI_API_KEY` | +| **Kimi** | AI-synthesized answers + citations | — | Uses Moonshot web search | `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 diff --git a/src/commands/configure.wizard.ts b/src/commands/configure.wizard.ts index ac31b6d5f4e..7a00fffbda1 100644 --- a/src/commands/configure.wizard.ts +++ b/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( diff --git a/src/commands/onboard-search.test.ts b/src/commands/onboard-search.test.ts index 69995eef3d7..10e2df9f81b 100644 --- a/src/commands/onboard-search.test.ts +++ b/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"]); }); }); diff --git a/src/commands/onboard-search.ts b/src/commands/onboard-search.ts index f5e06a44f96..f71a37b55da 100644 --- a/src/commands/onboard-search.ts +++ b/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__";