Perplexity Search API Integration

OpenClaw integrates the web_search provider for the Perplexity Search API. This integration returns organized results containing title, url, and snippet fields.

Backward compatibility is maintained for older Perplexity Sonar and OpenRouter configurations. When OPENROUTER_API_KEY is in use, an sk-or-... key is present in plugins.entries.perplexity.config.webSearch.apiKey, or plugins.entries.perplexity.config.webSearch.baseUrl or model is configured, the provider automatically shifts to the chat-completions route. In this mode, AI-generated answers with citations are returned rather than structured Search API results.

Install plugin

After installing the official plugin, restart Gateway:

openclaw plugins install @openclaw/perplexity-plugin
openclaw gateway restart

Getting a Perplexity API key

Register for a Perplexity account at perplexity.ai/settings/api.
Create an API key through your account dashboard.
Add the key to your configuration or define PERPLEXITY_API_KEY in the Gateway environment.

OpenRouter compatibility

For those already routing Perplexity Sonar through OpenRouter, retain provider: "perplexity" and define OPENROUTER_API_KEY in the Gateway environment, or place an sk-or-... key inside plugins.entries.perplexity.config.webSearch.apiKey.

Additional compatibility options:

plugins.entries.perplexity.config.webSearch.baseUrl
plugins.entries.perplexity.config.webSearch.model

Config examples

Native Perplexity Search API

{
  plugins: {
    entries: {
      perplexity: {
        config: {
          webSearch: {
            apiKey: "pplx-...",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "perplexity",
      },
    },
  },
}

OpenRouter / Sonar compatibility

{
  plugins: {
    entries: {
      perplexity: {
        config: {
          webSearch: {
            apiKey: "<openrouter-api-key>",
            baseUrl: "https://openrouter.ai/api/v1",
            model: "perplexity/sonar-pro",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "perplexity",
      },
    },
  },
}

Where to set the key

Configuration method: execute openclaw configure --section web. This command stores the key in ~/.openclaw/openclaw.json within the plugins.entries.perplexity.config.webSearch.apiKey field. SecretRef objects are also accepted in that field.

Environment method: define PERPLEXITY_API_KEY or OPENROUTER_API_KEY in the Gateway process environment. For a gateway deployment, place it in ~/.openclaw/.env or your service environment. Refer to Env vars for more details.

When provider: "perplexity" is set and the Perplexity key SecretRef cannot be resolved with no environment variable fallback, startup or reload will fail immediately.

Tool parameters

The following parameters apply to the native Perplexity Search API path.

query (string, required), The search query.
count (number, default: 5), How many results to retrieve, from 1 to 10.
country (string), A two-letter ISO country code, for example US or DE.
language (string), An ISO 639-1 language code, such as en, de, or fr.
freshness (day' | 'week' | 'month' | 'year), Time filter; day covers the last 24 hours.
date_after (string), Limits results to those published on or after this date (YYYY-MM-DD).
date_before (string), Limits results to those published on or before this date (YYYY-MM-DD).
domain_filter (string[]), A domain allowlist or denylist array, limited to 20 entries.
max_tokens (number, default: 25000), Total content budget, capped at 1000000.
max_tokens_per_page (number, default: 2048), Token limit per page.

For the legacy Sonar or OpenRouter compatibility path:

The values query, count, and freshness are all valid.
count exists only for backward compatibility; the output remains a single compiled answer with references rather than a list of N separate results.
Filters exclusive to the Search API (country, language, date_after, date_before, domain_filter, max_tokens, max_tokens_per_page) trigger clear error messages when used.

Examples:

// Country and language-specific search
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

// Recent results (past week)
await web_search({
  query: "AI news",
  freshness: "week",
});

// Date range search
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Domain filtering (allowlist)
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// Domain filtering (denylist - prefix with -)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// More content extraction
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

Domain filter rules

Each filter supports up to 20 domains.
You cannot combine allowlist and denylist entries within a single request.
Denylist entries must begin with a - prefix, for instance ["-reddit.com"].

Notes

The Perplexity Search API delivers structured web search data (title, url, snippet).
Using OpenRouter or explicitly setting plugins.entries.perplexity.config.webSearch.baseUrl or model reverts Perplexity to Sonar chat completions for legacy support.
Sonar or OpenRouter compatibility mode returns a single synthesized answer with citations, not structured result rows.
By default, results are cached for 15 minutes, though this duration can be changed with cacheTtlMinutes.

Web search overview, Covers all search providers and how auto-detection works.
Brave search, Provides structured results with country and language filtering.
Exa search, Uses neural search with content extraction capabilities.
Perplexity Search API docs, Official quickstart guide and full reference for the Perplexity Search API.