Perplexity search

Perplexity Search API

OpenClaw supports Perplexity Search API as a

provider. It returns structured results with , , and fields.

For compatibility, OpenClaw also supports legacy Perplexity Sonar/OpenRouter setups. If you use

, an key in , or set / , the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.

Getting a Perplexity API key

1. Create a Perplexity account at perplexity.ai/settings/api
2. Generate an API key in the dashboard
3. Store the key in config or set
   text

   Copy

   PERPLEXITY_API_KEY
   in the Gateway environment.

OpenRouter compatibility

If you were already using OpenRouter for Perplexity Sonar, keep

and set in the Gateway environment, or store an key in .

Optional compatibility controls:

• text

  Copy

  plugins.entries.perplexity.config.webSearch.baseUrl
• text

  Copy

  plugins.entries.perplexity.config.webSearch.model

Config examples

Native Perplexity Search API

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

OpenRouter / Sonar compatibility

json5
Copy
{
  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

Via config: run

. It stores the key in under . That field also accepts SecretRef objects.

Via environment: set

or in the Gateway process environment. For a gateway install, put it in (or your service environment). See Env vars.

If

is configured and the Perplexity key SecretRef is unresolved with no env fallback, startup/reload fails fast.

Tool parameters

These parameters apply to the native Perplexity Search API path.

Search query. Number of results to return (1–10). 2-letter ISO country code (e.g. `US`, `DE`). ISO 639-1 language code (e.g. `en`, `de`, `fr`). Time filter — `day` is 24 hours. Only results published after this date (`YYYY-MM-DD`). Only results published before this date (`YYYY-MM-DD`). Domain allowlist/denylist array (max 20). Total content budget (max 1000000). Per-page token limit.

For the legacy Sonar/OpenRouter compatibility path:

• text

  Copy

  query
  ,
  text

  Copy

  count
  , and
  text

  Copy

  freshness
  are accepted
• text

  Copy

  count
  is compatibility-only there; the response is still one synthesized answer with citations rather than an N-result list
• Search API-only filters such as
  text

  Copy

  country
  ,
  text

  Copy

  language
  ,
  text

  Copy

  date_after
  ,
  text

  Copy

  date_before
  ,
  text

  Copy

  domain_filter
  ,
  text

  Copy

  max_tokens
  , and
  text

  Copy

  max_tokens_per_page
  return explicit errors

Examples:

javascript
Copy
// 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

• Maximum 20 domains per filter
• Cannot mix allowlist and denylist in the same request
• Use
  text

  Copy

  -
  prefix for denylist entries (e.g.,
  text

  Copy

  ["-reddit.com"]
  )

Notes

• Perplexity Search API returns structured web search results (
  text

  Copy

  title
  ,
  text

  Copy

  url
  ,
  text

  Copy

  snippet
  )
• OpenRouter or explicit
  text

  Copy

  plugins.entries.perplexity.config.webSearch.baseUrl
  /
  text

  Copy

  model
  switches Perplexity back to Sonar chat completions for compatibility
• Sonar/OpenRouter compatibility returns one synthesized answer with citations, not structured result rows
• Results are cached for 15 minutes by default (configurable via
  text

  Copy

  cacheTtlMinutes
  )

Related

• Web Search overview -- all providers and auto-detection
• Perplexity Search API docs -- official Perplexity documentation
• Brave Search -- structured results with country/language filters
• Exa Search -- neural search with content extraction