Pular para o conteúdo principal

​
API de Busca Perplexity

O OpenClaw oferece suporte à API de Busca Perplexity como provider de web_search. Ela retorna resultados estruturados com os campos title, url e snippet. Para compatibilidade, o OpenClaw também oferece suporte a configurações legadas de Perplexity Sonar/OpenRouter. Se você usar OPENROUTER_API_KEY, uma chave sk-or-... em plugins.entries.perplexity.config.webSearch.apiKey, ou definir plugins.entries.perplexity.config.webSearch.baseUrl / model, o provider muda para o caminho de chat completions e retorna respostas sintetizadas por IA com citações em vez de resultados estruturados da API de Busca.

​
Obtendo uma chave de API da Perplexity

  1. Crie uma conta Perplexity em perplexity.ai/settings/api
  2. Gere uma chave de API no painel
  3. Armazene a chave na configuração ou defina PERPLEXITY_API_KEY no ambiente do Gateway.

​
Compatibilidade com OpenRouter

Se você já estava usando OpenRouter para Perplexity Sonar, mantenha provider: "perplexity" e defina OPENROUTER_API_KEY no ambiente do Gateway, ou armazene uma chave sk-or-... em plugins.entries.perplexity.config.webSearch.apiKey. Controles opcionais de compatibilidade:
  • plugins.entries.perplexity.config.webSearch.baseUrl
  • plugins.entries.perplexity.config.webSearch.model

​
Exemplos de configuração

​
API de Busca Perplexity nativa

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

​
Compatibilidade 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",
      },
    },
  },
}

​
Onde definir a chave

Via configuração: execute openclaw configure --section web. Isso armazena a chave em ~/.openclaw/openclaw.json em plugins.entries.perplexity.config.webSearch.apiKey. Esse campo também aceita objetos SecretRef. Via ambiente: defina PERPLEXITY_API_KEY ou OPENROUTER_API_KEY no ambiente do processo do Gateway. Para uma instalação de gateway, coloque em ~/.openclaw/.env (ou no ambiente do seu serviço). Consulte Variáveis de ambiente. Se provider: "perplexity" estiver configurado e o SecretRef da chave Perplexity não for resolvido sem fallback por ambiente, a inicialização/recarregamento falha imediatamente.

​
Parâmetros da ferramenta

Estes parâmetros se aplicam ao caminho nativo da API de Busca Perplexity.
ParâmetroDescrição
queryConsulta de busca (obrigatório)
countNúmero de resultados a retornar (1-10, padrão: 5)
countryCódigo de país ISO de 2 letras (ex.: "US", "DE")
languageCódigo de idioma ISO 639-1 (ex.: "en", "de", "fr")
freshnessFiltro de tempo: day (24h), week, month ou year
date_afterApenas resultados publicados após esta data (YYYY-MM-DD)
date_beforeApenas resultados publicados antes desta data (YYYY-MM-DD)
domain_filterArray de allowlist/denylist de domínios (máx. 20)
max_tokensOrçamento total de conteúdo (padrão: 25000, máx.: 1000000)
max_tokens_per_pageLimite de tokens por página (padrão: 2048)
Para o caminho legado de compatibilidade Sonar/OpenRouter:
  • query, count e freshness são aceitos
  • count é apenas para compatibilidade nesse caso; a resposta continua sendo uma resposta sintetizada com citações, em vez de uma lista com N resultados
  • Filtros exclusivos da API de Busca, como country, language, date_after, date_before, domain_filter, max_tokens e max_tokens_per_page, retornam erros explícitos
Exemplos: 
// Busca específica por país e idioma
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

// Resultados recentes (última semana)
await web_search({
  query: "AI news",
  freshness: "week",
});

// Busca por intervalo de datas
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Filtragem de domínio (allowlist)
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// Filtragem de domínio (denylist - prefixe com -)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// Mais extração de conteúdo
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

​
Regras de filtro de domínio

  • Máximo de 20 domínios por filtro
  • Não é possível misturar allowlist e denylist na mesma requisição
  • Use o prefixo - para entradas de denylist (ex.: ["-reddit.com"])

​
Observações

  • A API de Busca Perplexity retorna resultados estruturados de busca na web (title, url, snippet)
  • OpenRouter ou plugins.entries.perplexity.config.webSearch.baseUrl / model explícitos fazem a Perplexity voltar para Sonar chat completions por compatibilidade
  • A compatibilidade Sonar/OpenRouter retorna uma resposta sintetizada com citações, não linhas de resultado estruturadas
  • Os resultados ficam em cache por 15 minutos por padrão (configurável por cacheTtlMinutes)

​
Relacionados