Perplexity Web Search Provider Setup

The Perplexity plugin adds a web_search provider that offers two transport mechanisms: the native Perplexity Search API (which returns structured results with filtering capabilities) and Perplexity Sonar chat completions (which produce AI-generated answers with citations), the latter available either directly or through OpenRouter.

Note

This document explains how to configure the Perplexity provider. For details on the Perplexity tool (how the agent interacts with it), refer to 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

Alternatively, 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 will also be recognized.

Start searching

web_search automatically identifies Perplexity when its key is the only available search credential, requiring no additional configuration. To explicitly specify the provider:

openclaw config set tools.web.search.provider perplexity

Search modes

The plugin determines which transport to use in the following priority order:

If webSearch.baseUrl or webSearch.model is set: traffic always goes through Sonar chat completions against that endpoint, regardless of the key type.
If not, the key source dictates the endpoint: a configured key's prefix selects the transport (configuration takes precedence over environment variables); an environment key uses its corresponding 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 will also use the native Search API. The chat-completions path defaults to the perplexity/sonar-pro model; you can change it with plugins.entries.perplexity.config.webSearch.model.

Native API filtering

Filter	Description	Transport
`count`	Number of results per search, 1-10 (default 5)	Native only
`freshness`	Recency filter: `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

Filters exclusive to the native transport will return a descriptive error when used on the chat-completions path. freshness cannot be used together with date_after/date_before.

Advanced configuration

Environment variable for daemon processes

Warning

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

OpenRouter proxy setup

If you already have an OpenRouter billing arrangement and prefer to consolidate providers there, use an OPENROUTER_API_KEY (prefixed with sk-or-) rather than a native Perplexity key. OpenClaw automatically detects this key type and switches to the Sonar transport. This is convenient when you want to route Perplexity searches through OpenRouter.

Perplexity search tool, Describes how the agent triggers Perplexity searches and processes the returned results.
Configuration reference, Complete configuration reference, including plugin entries.