Perplexity Web Search Provider Setup Guide

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

Note

Setup of the Perplexity provider is what this page describes. 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

When the Gateway is running, installation is applied automatically; if not, it takes effect the next time it starts. See Apply changes and inspect.

Getting started

Set the API key

openclaw configure --section web

You can also 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 works as well.

Start searching

Once its key is the search credential that is available, web_search detects Perplexity automatically and no more setup is needed. To pin the provider explicitly:

openclaw config set tools.web.search.provider perplexity

Search modes

Transport resolution by the plugin follows this order:

When webSearch.baseUrl or webSearch.model is set: routing always goes through Sonar chat completions against that endpoint, whatever the key type.
If not, the endpoint is chosen by the key source: for a configured key, its prefix selects the transport (config takes precedence over environment variables); for an environment key, the matching endpoint is used 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 carrying any other prefix falls back to the native Search API too. On the chat-completions path the model defaults to perplexity/sonar-pro; use plugins.entries.perplexity.config.webSearch.model to override it.

Native API filtering

Filter	Description	Transport
`count`	Results per search, 1-10 (default 5); accepted but ignored on the chat-completions path	Both
`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; `max_tokens` max 1000000	Native only

Filters that are native-only produce a descriptive error when used 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 stays invisible to a launchd/systemd Gateway daemon, unless that environment is explicitly imported. Put the key in ~/.openclaw/.env or set it through env.shellEnv so the Gateway process can read it. The full precedence order is described in Environment variables.

OpenRouter proxy setup

Set an OPENROUTER_API_KEY (prefix sk-or-) in place of a native Perplexity key when you want Perplexity searches routed through OpenRouter. OpenClaw recognises that key and automatically switches to the Sonar transport. This helps if OpenRouter billing is already in place and you would rather keep providers consolidated there.

Integration header

Calls to the Perplexity API (api.perplexity.ai) identify OpenClaw by sending X-Pplx-Integration: openclaw/<version>. When searches go through OpenRouter, OpenRouter's app-attribution headers are sent instead. Neither set of headers reaches a custom proxy baseUrl.

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