Vai al contenuto principale

​
API di ricerca Perplexity

OpenClaw supporta l’API di ricerca Perplexity come provider web_search. Restituisce risultati strutturati con 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’AI con citazioni invece dei risultati strutturati dell’API di ricerca.

​
Ottenere una chiave API Perplexity

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

​
Compatibilità OpenRouter

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

​
Esempi di configurazione

​
API di ricerca Perplexity 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. Memorizza la chiave in ~/.openclaw/openclaw.json sotto plugins.entries.perplexity.config.webSearch.apiKey. Questo campo accetta anche oggetti SecretRef. Tramite ambiente: imposta PERPLEXITY_API_KEY o OPENROUTER_API_KEY nell’ambiente del processo Gateway. Per un’installazione gateway, inseriscilo in ~/.openclaw/.env (o nell’ambiente del tuo servizio). Vedi Variabili env. Se provider: "perplexity" è configurato e il SecretRef della chiave Perplexity non viene risolto senza fallback env, l’avvio/ricaricamento fallisce immediatamente.

​
Parametri dello strumento

Questi parametri si applicano al percorso nativo dell’API di ricerca Perplexity.
ParametroDescrizione
queryQuery di ricerca (obbligatoria)
countNumero di risultati da restituire (1-10, predefinito: 5)
countryCodice paese ISO di 2 lettere (ad es., “US”, “DE”)
languageCodice lingua ISO 639-1 (ad es., “en”, “de”, “fr”)
freshnessFiltro temporale: day (24h), week, month o year
date_afterSolo risultati pubblicati dopo questa data (YYYY-MM-DD)
date_beforeSolo risultati pubblicati prima di questa data (YYYY-MM-DD)
domain_filterArray di allowlist/denylist di domini (max 20)
max_tokensBudget totale di contenuto (predefinito: 25000, max: 1000000)
max_tokens_per_pageLimite di token per pagina (predefinito: 2048)
Per il percorso di compatibilità legacy Sonar/OpenRouter:
  • Sono accettati query, count e freshness
  • count è lì solo per compatibilità; la risposta resta comunque una singola risposta sintetizzata con citazioni anziché un elenco di N risultati
  • I filtri solo API di ricerca come country, language, date_after, date_before, domain_filter, max_tokens e max_tokens_per_page restituiscono errori espliciti
Esempi: 
// Ricerca specifica per paese e lingua
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

// Risultati recenti (ultima settimana)
await web_search({
  query: "AI news",
  freshness: "week",
});

// Ricerca per intervallo di date
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

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

// Filtro di dominio (denylist - prefisso con -)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// Maggiore estrazione di contenuto
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 mescolare allowlist e denylist nella stessa richiesta
  • Usa il prefisso - per le voci di denylist (ad es. ["-reddit.com"])

​
Note

  • L’API di ricerca Perplexity restituisce risultati strutturati di ricerca web (title, url, snippet)
  • OpenRouter o 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