OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Parallel search

The Parallel plugin provides two Parallel web_search providers, both returning ranked, LLM-optimized excerpts from a web index built for AI agents:

Provider id Auth
Parallel Search (Free) parallel-free None -- Parallel's free Search MCP
Parallel Search parallel PARALLEL_API_KEY -- paid Search API, higher rate limits and objective tuning

Set tools.web.search.provider to parallel-free or parallel to select one explicitly. Paid Parallel can also be auto-detected from its API key; Parallel Search (Free) must be selected explicitly.

Install plugin

bash
openclaw plugins install @openclaw/parallel-plugin

Installation applies to a running Gateway automatically; otherwise it takes effect on the next startup. See Apply changes and inspect.

API key (paid provider)

parallel-free needs no key but still must be selected explicitly. The paid parallel provider needs an API key:

  • Create an account

    Sign up at platform.parallel.ai and generate an API key from your dashboard.

  • Store the key

    Set PARALLEL_API_KEY in the Gateway environment, or configure via:

    bash
    openclaw configure --section web

    • Config

    json5
    {  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: {        // "parallel-free" for the free Search MCP, or "parallel" for the        // paid API-backed provider shown here.        provider: "parallel",      },    },  },}

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

    Base URL override

    Applies to the paid parallel provider only; parallel-free always uses https://search.parallel.ai/mcp and ignores this setting.

    Set plugins.entries.parallel.config.webSearch.baseUrl to route paid requests through a compatible proxy or alternate 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 part of the search cache key, so results from different endpoints are never shared.

    Tool parameters

    Both providers expose Parallel's native search shape so the model fills in a natural-language goal plus a few short keyword queries -- the pairing Parallel recommends for best results.

    objectivestringrequired

    Natural-language description of the underlying question or goal (max 5000 chars). Should be self-contained.

    search_queriesstring[]required

    Concise keyword search queries, 3-6 words each (1-5 entries, max 200 chars each). Provide 2-3 diverse queries for best results.

    countnumber

    Results to return (1-40).

    session_idstring

    Optional Parallel session id from a previous result's sessionId. Pass it on follow-up searches in the same task so Parallel groups related calls and improves subsequent results. Max 1000 chars on parallel; the free parallel-free Search MCP caps it at 100. An id past the limit is dropped (paid) or a fresh one is minted (free).

    client_modelstring

    Optional identifier of the model making the call (e.g. claude-opus-4-7, gpt-6-astra), max 100 chars. 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 for LLM reasoning utility, not human click-through; expect dense excerpts per result rather than full-page content.
    • Result excerpts come back as the excerpts array and are also joined into description for compatibility with the generic web_search contract.
    • Both providers return a session_id; OpenClaw surfaces it as sessionId in the tool payload so callers can group follow-up searches. A Parallel-generated session id (one the caller did not supply) is excluded from the cache entry, since unrelated tasks with identical queries should not inherit it.
    • 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 (parallel) or applies count client-side after Parallel's fixed-size response (parallel-free). The caller's count arg wins, then tools.web.search.maxResults, otherwise OpenClaw's generic web_search default (5) -- Parallel's own API defaults to 10.
    • Results are cached for 15 minutes by default (cacheTtlMinutes).
    • parallel-free mints a fresh session_id per call via its MCP handshake when the caller does not supply one; parallel leaves it unset in that case.

    Decisions

    The same plugin provides Parallel's native web-grounded Decisions API. Enable the plugin, set PARALLEL_API_KEY (or use /login parallel), and select parallel/decisions-fast for the decision_evaluate tool with contractVersion: 2. It is a decision-only route, not an agent chat model. The OpenRouter equivalent is openrouter/parallel/decisions-fast, using an OpenRouter credential.

    The direct route calls POST https://api.parallel.ai/v1/decisions with mode: "fast"; the local model ID is not sent as a native model parameter. It accepts text or JSON state and up to 100 related boolean, choice, or score questions. Boolean results preserve Parallel's estimated probability of truth; score results preserve its fractional, zero-based score and level probabilities. Refusals are explicit per-question provider errors, not false/zero answers. Citations are returned in result metadata for the whole request, not per answer.

    Parallel performs live web retrieval for these requests. Do not use this route for state you do not want sent to a web-grounding provider. Images, list state, sort/tags/box questions, and generation/reasoning controls are unsupported. The native API limits each state-plus-question input to 32,000 estimated tokens, rendered questions to 5,000 characters, choices to 2–255 options, and scores to 2–10 levels. Native usage is billed per request, not per generated token; token counts are retained without inventing token prices.

    See the Parallel Decisions reference and pricing for current API limits and billing. Marketing trials and promotions are not configuration guarantees.

    Was this useful?