adolf/docs/providers/perplexity-provider.md

summary, title, read_when

summary	title	read_when
Perplexity web search provider setup (API key, search modes, filtering)	Perplexity	You want to configure Perplexity as a web search provider You need the Perplexity API key or OpenRouter proxy 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, direct or via OpenRouter (AI-synthesized answers with citations).

This page covers the Perplexity **provider** setup. For the Perplexity **tool** (how the agent uses it), see [Perplexity search](/tools/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

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

Or set the key directly:

```bash
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.

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

```bash
openclaw config set tools.web.search.provider perplexity
```

Search modes

The plugin resolves transport in this order:

1. webSearch.baseUrl or webSearch.model set: always routes through Sonar chat completions against that endpoint, regardless of key type.
2. 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

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](/help/environment) for the full precedence order. 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.

Related

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