openclaw/parallel-search.md at c6972a0664ff05a400e30ee7cc5ae1807dcb75ff

mirror of https://github.com/openclaw/openclaw.git synced 2026-06-06 14:01:24 +08:00

Files

Matt H db7d70ae4d feat(parallel): add Parallel as a bundled web_search provider (#85158 )

- New extensions/parallel package modeled on extensions/exa
- Wires Parallel's POST /v1/search through the generic web_search contract,
  exposing Parallel's recommended {objective, search_queries} shape (plus
  optional count, session_id, client_model) so the model can supply both the
  natural-language goal and 2-3 short keyword queries as Parallel docs advise
- client_model lets the model report its own slug so Parallel can tailor
  optimizations for the consuming model's capabilities; partitions the cache
  by client_model so different models do not silently share ranked excerpts
- Honors top-level tools.web.search.{maxResults,timeoutSeconds,cacheTtlMinutes}
  via the shared SDK helpers (mergeScopedSearchConfig, withTrustedWebSearchEndpoint,
  buildSearchCacheKey, read/writeCachedSearchPayload)
- Auto-detect order 75; auth via PARALLEL_API_KEY or
  plugins.entries.parallel.config.webSearch.apiKey
- Optional baseUrl override for proxies (e.g. Cloudflare AI Gateway)
- Threads caller-supplied session_id through follow-up calls; strips
  auto-generated session_id from the shared cache to avoid cross-task leaks
- Always sends advanced_settings.max_results so result volume matches the
  OpenClaw web_search default (5) instead of Parallel's default (10)
- Identifies the plugin via User-Agent header built from package version
- Runtime accepts the generic `query` arg as a fallback so the operator
  CLI (openclaw capability web.search) keeps working when Parallel is the
  active provider: it is promoted into the lone `search_queries` entry.
  `objective` stays optional and is never synthesized from a keyword
  query (Parallel documents it as natural-language intent). Agent callers
  using the native objective+search_queries shape take precedence; the
  schema still advertises only the native keys
- Updates the agent tool-display extractor (src/agents/tool-display-common.ts)
  to recognize Parallel's objective+search_queries shape so calls render with
  query context in CLI progress and Codex activity metadata
- Adds /tools/parallel-search docs page, web.md provider listing, docs nav,
  labeler entry, per-plugin registration contract test, and minimal core
  touch-points (legacy migrate, registration cases, providers contract list,
  runtime bundled list, vitest extension paths)

2026-06-05 12:01:58 -07:00

4.3 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Parallel Search -- LLM-optimized dense excerpts from web sources

You want to use Parallel for web_search

You need a PARALLEL_API_KEY

You want dense excerpts ranked for LLM context efficiency

Parallel search

OpenClaw supports Parallel as a web_search provider. Parallel returns ranked, LLM-optimized dense excerpts from a web index purpose-built for AI agents.

Get an API key

Sign up at [platform.parallel.ai](https://platform.parallel.ai) and generate an API key from your dashboard. Set `PARALLEL_API_KEY` in the Gateway environment, or configure via:

```bash
openclaw configure --section web
```

Config

{
  plugins: {
    entries: {
      parallel: {
        config: {
          webSearch: {
            apiKey: "par-...", // optional if PARALLEL_API_KEY is set
            baseUrl: "https://api.parallel.ai", // optional; OpenClaw appends /v1/search
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "parallel",
      },
    },
  },
}

Environment alternative: set PARALLEL_API_KEY in the Gateway environment. For a gateway install, put it in ~/.openclaw/.env.

Base URL override

Set plugins.entries.parallel.config.webSearch.baseUrl when Parallel requests should go through a compatible proxy or alternate Parallel endpoint (for example, the Cloudflare AI Gateway). OpenClaw normalizes bare hosts by prepending https:// and appends /v1/search unless the path already ends there. The resolved endpoint is included in the search cache key, so results from different Parallel endpoints are not shared.

Tool parameters

OpenClaw exposes Parallel's native search shape so the model can fill in both the natural-language goal and a few short keyword queries — the pairing Parallel recommends for best results.

Natural-language description of the underlying question or goal (max 5000 chars). Should be self-contained. Concise keyword search queries, 3-6 words each (1-5 entries, max 200 chars each). Provide 2-3 diverse queries for best results. Results to return (1-40). Optional Parallel session id (max 1000 chars). Pass the `sessionId` from a previous Parallel result on follow-up searches that are part of the same task so Parallel can group related calls and improve subsequent results. Optional identifier of the model making the call (e.g. `claude-opus-4-7`, `gpt-5.5`). Lets Parallel tailor default settings for your model's capabilities. Pass the exact active model slug; do not shorten to a family alias.

Notes

Parallel ranks and compresses results based on LLM reasoning utility, not human click-through; expect dense excerpts in each result rather than full-page content
Result excerpts come back as the excerpts array and are also joined into the description field for compatibility with the generic web_search contract
Parallel returns a session_id on every response; OpenClaw surfaces it as sessionId in the tool payload so callers can group follow-up searches
searchId, warnings, and usage from Parallel are passed through when present
OpenClaw always forwards a resolved result count to Parallel as advanced_settings.max_results. The caller's count arg wins, then the top-level tools.web.search.maxResults setting, otherwise OpenClaw's generic web_search default (5). This keeps result volume consistent when switching between providers; Parallel on its own defaults to 10
Results are cached for 15 minutes by default (configurable via cacheTtlMinutes)

Web Search overview -- all providers and auto-detection
Exa search -- neural search with content extraction
Perplexity Search -- structured results with domain filtering

4.3 KiB Raw Blame History