Perplexity Web Search Provider Setup

The Perplexity plugin registers a web_search provider with two transports: the native Perplexity Search API (structured results with filters) and Perplexity Sonar chat completions, either direct or through OpenRouter (AI-synthesized answers with citations).

Note

This page covers the Perplexity provider setup. For the Perplexity tool (how the agent uses it), see Perplexity search.

Property	Value
Type	Web search provider (not a model provider)
Auth	`PERPLEXITY_API_KEY` (native) or `OPENROUTER_API_KEY` (via OpenRouter)
Config path	`plugins.entries.perplexity.config.webSearch.apiKey`
Overrides	`plugins.entries.perplexity.config.webSearch.baseUrl` / `.model`
Get a key	perplexity.ai/settings/api

Install plugin

openclaw plugins install @openclaw/perplexity-plugin
openclaw gateway restart

Getting started

Set the API key

openclaw configure --section web

Or set the key directly:

openclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"

A key exported as PERPLEXITY_API_KEY or OPENROUTER_API_KEY in the Gateway environment also works.

Start searching

web_search auto-detects Perplexity once its key is the available search credential; no further setup is required. To pin the provider explicitly:

openclaw config set tools.web.search.provider perplexity

Search modes

The plugin resolves transport in this order:

webSearch.baseUrl or webSearch.model set: always routes through Sonar chat completions against that endpoint, regardless of key type.
Otherwise, key source decides the endpoint: a configured key's prefix picks the transport (config beats environment variables); an environment key uses its matching endpoint directly.

Key prefix	Transport	Features
`pplx-`	Native Perplexity Search API (`https://api.perplexity.ai`)	Structured results, domain/language/date filters
`sk-or-`	OpenRouter (`https://openrouter.ai/api/v1`), Sonar model	AI-synthesized answers with citations

A configured key with any other prefix also uses the native Search API. The chat-completions path defaults to the perplexity/sonar-pro model; override it with plugins.entries.perplexity.config.webSearch.model.

Native API filtering

Filter	Description	Transport
`count`	Results per search, 1-10 (default 5)	Native only
`freshness`	Recency window: `day`, `week`, `month`, `year`	Both
`country`	2-letter country code (`us`, `de`, `jp`)	Native only
`language`	ISO 639-1 language code (`en`, `fr`, `zh`)	Native only
`date_after` / `date_before`	Published-date range in `YYYY-MM-DD`	Native only
`domain_filter`	Max 20 domains; allowlist or `-`-prefixed denylist, never mixed	Native only
`max_tokens` / `max_tokens_per_page`	Content budget across all results / per page	Native only

Native-only filters return a descriptive error on the chat-completions path. freshness cannot be combined with date_after/date_before.

Advanced configuration

Environment variable for daemon processes

Warning

A key exported only in an interactive shell is not visible to a launchd/systemd Gateway daemon unless that environment is explicitly imported. Set the key in ~/.openclaw/.env or via env.shellEnv so the Gateway process can read it. See Environment variables for the full precedence order.

OpenRouter proxy setup

To route Perplexity searches through OpenRouter, set an OPENROUTER_API_KEY (prefix sk-or-) instead of a native Perplexity key. OpenClaw detects the key and switches to the Sonar transport automatically. Useful if you already have OpenRouter billing set up and want to consolidate providers there.

Perplexity search tool, How the agent invokes Perplexity searches and interprets results.
Configuration reference, Full configuration reference including plugin entries.