API de Perplexity Search

OpenClaw soporta la API de Perplexity Search como proveedor de web_search. Devuelve resultados estructurados con campos title, url y snippet.

Para compatibilidad, OpenClaw también soporta configuraciones legacy con Perplexity Sonar/OpenRouter. Si usas OPENROUTER_API_KEY, una clave sk-or-... en tools.web.search.perplexity.apiKey, o configuras tools.web.search.perplexity.baseUrl / model, el proveedor cambia a la ruta de chat-completions y devuelve respuestas sintetizadas por IA con citas en lugar de resultados estructurados de la Search API.

Obtener una clave API de Perplexity

1. Crea una cuenta de Perplexity en https://www.perplexity.ai/settings/api
2. Genera una clave API en el panel de control
3. Guarda la clave en la configuración o establece PERPLEXITY_API_KEY en el entorno del Gateway.

Compatibilidad con OpenRouter

Si ya usabas OpenRouter para Perplexity Sonar, mantén provider: "perplexity" y establece OPENROUTER_API_KEY en el entorno del Gateway, o guarda una clave sk-or-... en tools.web.search.perplexity.apiKey.

Controles legacy opcionales:

• tools.web.search.perplexity.baseUrl
• tools.web.search.perplexity.model

Ejemplos de configuración

API nativa de Perplexity Search

{
  tools: {
    web: {
      search: {
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...",
        },
      },
    },
  },
}

Compatibilidad OpenRouter / Sonar

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

Dónde configurar la clave

Vía configuración: ejecuta openclaw configure --section web. La clave se guarda en ~/.openclaw/openclaw.json bajo tools.web.search.perplexity.apiKey. Ese campo también acepta objetos SecretRef.

Vía variable de entorno: establece PERPLEXITY_API_KEY o OPENROUTER_API_KEY en el entorno del proceso del Gateway. Para una instalación como gateway, ponlo en ~/.openclaw/.env (o el entorno de tu servicio). Consulta Variables de entorno.

Si provider: "perplexity" está configurado y el SecretRef de la clave de Perplexity no se puede resolver sin fallback de entorno, el arranque/recarga falla inmediatamente.

Parámetros de la herramienta

Estos parámetros aplican a la ruta nativa de la API de Perplexity Search.

Para la ruta de compatibilidad legacy con Sonar/OpenRouter, solo se soportan query y freshness. Los filtros exclusivos de la Search API como country, language, date_after, date_before, domain_filter, max_tokens y max_tokens_per_page devuelven errores explícitos.

Ejemplos:

// Búsqueda por país e idioma
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

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

// Búsqueda por rango de fechas
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

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

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

// Más extracción de contenido
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

Reglas del filtro de dominios

• Máximo 20 dominios por filtro
• No se puede mezclar allowlist y denylist en la misma solicitud
• Usa el prefijo - para entradas de denylist (ej., ["-reddit.com"])

Notas

• La API de Perplexity Search devuelve resultados de búsqueda web estructurados (title, url, snippet)
• OpenRouter o un baseUrl / model explícito cambia Perplexity de vuelta a chat completions de Sonar por compatibilidad
• Los resultados se cachean durante 15 minutos por defecto (configurable con cacheTtlMinutes)

Consulta Web tools para la configuración completa de web_search. Consulta la documentación de la API de Perplexity Search para más detalles.