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.

Direct OpenAI Responses models (api: "openai-responses", provider openai, official API base URL) use OpenAI's hosted native web search automatically when tools.web.search.provider is unset, empty, "auto", or "openai" -- so they bypass Parallel by default. Set tools.web.search.provider to parallel-free or parallel to route them through Parallel instead. See Web Search overview.

Install plugin

apus 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](https://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
apus configure --section web
```

Config

{
  plugins: {
    entries: {
      parallel: {
        config: {
          webSearch: {
            apiKey: "par-...", // optional if PARALLEL_API_KEY is set
            baseUrl: "https://api.parallel.ai", // optional; Apus 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 ~/.apus/.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). Apus 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.

objective string

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

search_queries string[]

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

count number

Results to return (1-40).

session_id string

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_model string

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

Related