Vai al contenuto principale
OpenClaw supporta Perplexity Search API come provider web_search. Restituisce risultati strutturati con i campi title, url e snippet. Per compatibilità, OpenClaw supporta anche le configurazioni legacy Perplexity Sonar/OpenRouter. Se usi OPENROUTER_API_KEY, una chiave sk-or-... in plugins.entries.perplexity.config.webSearch.apiKey, oppure imposti plugins.entries.perplexity.config.webSearch.baseUrl / model, il provider passa al percorso chat-completions e restituisce risposte sintetizzate dall’IA con citazioni invece di risultati strutturati della Search API.

​
Installa il Plugin

Installa il Plugin ufficiale, quindi riavvia Gateway: 
openclaw plugins install @openclaw/perplexity-plugin
openclaw gateway restart

​
Ottenere una chiave API Perplexity

  1. Crea un account Perplexity su perplexity.ai/settings/api
  2. Genera una chiave API nella dashboard
  3. Archivia la chiave nella configurazione oppure imposta PERPLEXITY_API_KEY nell’ambiente Gateway.

​
Compatibilità con OpenRouter

Se stavi già usando OpenRouter per Perplexity Sonar, mantieni provider: "perplexity" e imposta OPENROUTER_API_KEY nell’ambiente Gateway, oppure archivia una chiave sk-or-... in plugins.entries.perplexity.config.webSearch.apiKey. Controlli di compatibilità opzionali:
  • plugins.entries.perplexity.config.webSearch.baseUrl
  • plugins.entries.perplexity.config.webSearch.model

​
Esempi di configurazione

​
Perplexity Search API nativa

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

​
Compatibilità OpenRouter / Sonar

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

​
Dove impostare la chiave

Tramite configurazione: esegui openclaw configure --section web. Archivia la chiave in ~/.openclaw/openclaw.json sotto plugins.entries.perplexity.config.webSearch.apiKey. Quel campo accetta anche oggetti SecretRef. Tramite ambiente: imposta PERPLEXITY_API_KEY oppure OPENROUTER_API_KEY nell’ambiente del processo Gateway. Per un’installazione gateway, inseriscila in ~/.openclaw/.env (o nell’ambiente del tuo servizio). Vedi Variabili d’ambiente. Se provider: "perplexity" è configurato e il SecretRef della chiave Perplexity non viene risolto senza fallback di ambiente, l’avvio/ricaricamento fallisce subito.

​
Parametri dello strumento

Questi parametri si applicano al percorso Perplexity Search API nativo.
​
query
string
obbligatorio
Query di ricerca.
​
count
number
predefinito:"5"
Numero di risultati da restituire (1-10).
​
country
string
Codice paese ISO a 2 lettere (ad es. US, DE).
​
language
string
Codice lingua ISO 639-1 (ad es. en, de, fr).
​
freshness
'day' | 'week' | 'month' | 'year'
Filtro temporale - day corrisponde a 24 ore.
​
date_after
string
Solo risultati pubblicati dopo questa data (YYYY-MM-DD).
​
date_before
string
Solo risultati pubblicati prima di questa data (YYYY-MM-DD).
​
domain_filter
string[]
Array allowlist/denylist di domini (max 20).
​
max_tokens
number
predefinito:"25000"
Budget totale di contenuto (max 1000000).
​
max_tokens_per_page
number
predefinito:"2048"
Limite di token per pagina.
Per il percorso di compatibilità legacy Sonar/OpenRouter:
  • query, count e freshness sono accettati
  • lì count serve solo per compatibilità; la risposta resta comunque una singola risposta sintetizzata con citazioni invece di un elenco di N risultati
  • i filtri disponibili solo nella Search API come country, language, date_after, date_before, domain_filter, max_tokens e max_tokens_per_page restituiscono errori espliciti
Esempi: 
// 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,
});

​
Regole del filtro di dominio

  • Massimo 20 domini per filtro
  • Non è possibile combinare allowlist e denylist nella stessa richiesta
  • Usa il prefisso - per le voci denylist (ad es. ["-reddit.com"])

​
Note

  • Perplexity Search API restituisce risultati di ricerca web strutturati (title, url, snippet)
  • OpenRouter oppure plugins.entries.perplexity.config.webSearch.baseUrl / model espliciti riportano Perplexity alle chat completions Sonar per compatibilità
  • La compatibilità Sonar/OpenRouter restituisce una singola risposta sintetizzata con citazioni, non righe di risultati strutturati
  • I risultati vengono memorizzati nella cache per 15 minuti per impostazione predefinita (configurabile tramite cacheTtlMinutes)

​
Correlati

Web search overview

Tutti i provider e le regole di rilevamento automatico.

Brave search

Risultati strutturati con filtri per paese e lingua.

Exa search

Ricerca neurale con estrazione del contenuto.

Perplexity Search API docs

Guida rapida e riferimento ufficiali di Perplexity Search API.