On this page
On this page
Providers
Perplexity
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).
| Property | Value |
|---|---|
| Type | Web search and native Decision 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
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
Or set the key directly:
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:
Search modes
The plugin resolves transport in this order:
webSearch.baseUrlorwebSearch.modelset: 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); 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
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.
Integration header
Requests to the Perplexity API (api.perplexity.ai) identify OpenClaw with
X-Pplx-Integration: openclaw/<version>. Searches routed through OpenRouter
send OpenRouter's app-attribution headers instead. A custom proxy baseUrl
gets neither.
Decision models
The same plugin also connects directly to Perplexity's Decisions API, using the separate Decision role, not Sonar chat completions. This requires a plugin/host release containing this integration and the prepared Decision V2 contract; older installed versions may provide search only.
Connect with openclaw models auth login --provider perplexity-decisions --method api-key
or provide PERPLEXITY_API_KEY to the Gateway process. Decision auth uses normal
the separate perplexity-decisions provider profiles; it does not reuse the plugin's web-search key,
OPENROUTER_API_KEY, or Sonar search routing. Existing web-search setup remains
independent. Connecting the key leaves chat and Decision selections unchanged.
Select perplexity-decisions/pplx-decider-v1.2 in the Decision picker or set
agents.defaults.decisionModel to that reference. Calls use
POST https://api.perplexity.ai/v1/decisions with native state and named
questions fields. This is not the OpenAI Decisions request format despite
the matching endpoint suffix.
The adapter supports text/JSON evidence, Boolean probabilities, 2–255 Choice options, 2–10 Score levels, and up to 128 questions. JSON state is serialized as text rather than interpreted as native image parts. Image input, Flash/latest aliases, web grounding, sorting, tags, boxes, and reasoning switches are not exposed by this adapter. Perplexity documents a 256K-token state-plus-question limit and may group questions internally; there is no client-side splitting, truncation, or retry. Normal proxy/TLS policy, cancellation, total deadlines, and dispatch-time authority checks apply.
Results preserve expected fractional Score values, original distributions, provider-specific confidence, served model identity, and reported token usage. Confidence is not the chosen option's probability or a correctness guarantee. Use current API prices and reported usage, not benchmark cost per task, for billing expectations.