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.

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

apus plugins install @openclaw/perplexity-plugin

Installation applies to a running Gateway automatically; otherwise it takes effect on the next startup. See Apply changes and inspect.

Getting started

Set the API key

```bash
apus configure --section web
```

Or set the key directly:

```bash
apus 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:

```bash
apus 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); 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

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 
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 `~/.apus/.env` or via `env.shellEnv` so the
Gateway process can read it. See [Environment variables](/help/environment)
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. Apus 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.
Integration header 
Requests to the Perplexity API (`api.perplexity.ai`) identify Apus with
`X-Pplx-Integration: apus/<version>`. Searches routed through OpenRouter
send OpenRouter's app-attribution headers instead. A custom proxy `baseUrl`
gets neither.

Related

Perplexity search tool

How the agent invokes Perplexity searches and interprets results.

Configuration reference

Full configuration reference including plugin entries.