Herramientas web

OpenClaw incluye dos herramientas web ligeras:

web_search — Busca en la web usando Brave Search API, Gemini con grounding de Google Search, Grok, Kimi o Perplexity Search API.
web_fetch — HTTP fetch + extracción legible (HTML -> markdown/texto).

Estas no son automatización del navegador. Para sitios con mucho JS o inicios de sesión, usa la herramienta Browser.

Cómo funciona

web_search llama a tu proveedor configurado y devuelve resultados.
Los resultados se almacenan en caché por consulta durante 15 minutos (configurable).
web_fetch hace un HTTP GET simple y extrae contenido legible (HTML -> markdown/texto). No ejecuta JavaScript.
web_fetch está habilitado por defecto (a menos que se desactive explícitamente).

Consulta Configuración de Brave Search y Configuración de Perplexity Search para detalles específicos del proveedor.

Elegir un proveedor de búsqueda

Proveedor	Forma de resultados	Filtros específicos del proveedor	Notas	Clave API
Brave Search API	Resultados estructurados con fragmentos	`country`, `language`, `ui_lang`, tiempo	Admite modo Brave `llm-context`	`BRAVE_API_KEY`
Gemini	Respuestas sintetizadas por IA + citas	—	Usa grounding de Google Search	`GEMINI_API_KEY`
Grok	Respuestas sintetizadas por IA + citas	—	Usa respuestas de xAI con grounding web	`XAI_API_KEY`
Kimi	Respuestas sintetizadas por IA + citas	—	Usa búsqueda web de Moonshot	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
Perplexity Search API	Resultados estructurados con fragmentos	`country`, `language`, tiempo, `domain_filter`	Admite controles de extracción de contenido; OpenRouter usa ruta de compatibilidad Sonar	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`

Auto-detección

La tabla anterior es alfabética. Si no se configura provider explícitamente, la auto-detección en runtime verifica proveedores en este orden:

Brave — variable de entorno BRAVE_API_KEY o configuración tools.web.search.apiKey
Gemini — variable de entorno GEMINI_API_KEY o configuración tools.web.search.gemini.apiKey
Grok — variable de entorno XAI_API_KEY o configuración tools.web.search.grok.apiKey
Kimi — variable de entorno KIMI_API_KEY / MOONSHOT_API_KEY o configuración tools.web.search.kimi.apiKey
Perplexity — PERPLEXITY_API_KEY, OPENROUTER_API_KEY o configuración tools.web.search.perplexity.apiKey

Si no se encuentran claves, recurre a Brave (obtendrás un error de clave faltante indicándote que configures una).

Comportamiento de SecretRef en runtime:

Los SecretRefs de herramientas web se resuelven atómicamente al iniciar/recargar el gateway.
En modo auto-detect, OpenClaw resuelve solo la clave del proveedor seleccionado. Los SecretRefs de proveedores no seleccionados permanecen inactivos hasta que se seleccionen.
Si el SecretRef del proveedor seleccionado no se resuelve y no hay fallback de variable de entorno del proveedor, el inicio/recarga falla inmediatamente.

Configurar la búsqueda web

Usa openclaw configure --section web para configurar tu clave API y elegir un proveedor.

Brave Search

Crea una cuenta de Brave Search API en brave.com/search/api
En el panel, elige el plan Search y genera una clave API.
Ejecuta openclaw configure --section web para almacenar la clave en la configuración, o configura BRAVE_API_KEY en tu entorno.

Cada plan de Brave incluye $5/mes en crédito gratuito (renovable). El plan Search cuesta $5 por cada 1,000 solicitudes, así que el crédito cubre 1,000 consultas/mes. Configura tu límite de uso en el panel de Brave para evitar cargos inesperados. Consulta el portal de API de Brave para los planes y precios actuales.

Perplexity Search

Crea una cuenta de Perplexity en perplexity.ai/settings/api
Genera una clave API en el panel
Ejecuta openclaw configure --section web para almacenar la clave en la configuración, o configura PERPLEXITY_API_KEY en tu entorno.

Para compatibilidad legacy con Sonar/OpenRouter, configura OPENROUTER_API_KEY en su lugar, o configura tools.web.search.perplexity.apiKey con una clave sk-or-.... Configurar tools.web.search.perplexity.baseUrl o model también opta a Perplexity de vuelta a la ruta de compatibilidad chat-completions.

Consulta Documentación de Perplexity Search API para más detalles.

Dónde almacenar la clave

Mediante configuración: ejecuta openclaw configure --section web. Almacena la clave en la ruta de configuración específica del proveedor:

Brave: tools.web.search.apiKey
Gemini: tools.web.search.gemini.apiKey
Grok: tools.web.search.grok.apiKey
Kimi: tools.web.search.kimi.apiKey
Perplexity: tools.web.search.perplexity.apiKey

Todos estos campos también admiten objetos SecretRef.

Mediante entorno: configura las variables de entorno del proveedor en el entorno del proceso del Gateway:

Brave: BRAVE_API_KEY
Gemini: GEMINI_API_KEY
Grok: XAI_API_KEY
Kimi: KIMI_API_KEY o MOONSHOT_API_KEY
Perplexity: PERPLEXITY_API_KEY o OPENROUTER_API_KEY

Para una instalación de gateway, ponlas en ~/.openclaw/.env (o en el entorno de tu servicio). Consulta Variables de entorno.

Ejemplos de configuración

Brave Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // opcional si BRAVE_API_KEY está configurado // pragma: allowlist secret
      },
    },
  },
}

Modo Brave LLM Context:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // opcional si BRAVE_API_KEY está configurado // pragma: allowlist secret
        brave: {
          mode: "llm-context",
        },
      },
    },
  },
}

llm-context devuelve fragmentos de página extraídos para grounding en vez de snippets estándar de Brave. En este modo, country y language / search_lang siguen funcionando, pero ui_lang, freshness, date_after y date_before son rechazados.

Perplexity Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // opcional si PERPLEXITY_API_KEY está configurado
        },
      },
    },
  },
}

Perplexity vía OpenRouter / compatibilidad Sonar:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "<openrouter-api-key>", // opcional si OPENROUTER_API_KEY está configurado
          baseUrl: "https://openrouter.ai/api/v1",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

Usar Gemini (grounding de Google Search)

Los modelos Gemini admiten grounding de Google Search integrado, que devuelve respuestas sintetizadas por IA respaldadas por resultados en vivo de Google Search con citas.

Obtener una clave API de Gemini

Ve a Google AI Studio
Crea una clave API
Configura GEMINI_API_KEY en el entorno del Gateway, o configura tools.web.search.gemini.apiKey

Configurar búsqueda con Gemini

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // Clave API (opcional si GEMINI_API_KEY está configurado)
          apiKey: "AIza...",
          // Modelo (por defecto "gemini-2.5-flash")
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

Alternativa por entorno: configura GEMINI_API_KEY en el entorno del Gateway. Para una instalación de gateway, ponla en ~/.openclaw/.env.

Notas

Las URLs de citas del grounding de Gemini se resuelven automáticamente desde las URLs de redirección de Google a URLs directas.
La resolución de redirecciones usa la ruta de protección SSRF (HEAD + verificaciones de redirección + validación http/https) antes de devolver la URL final de cita.
La resolución de redirecciones usa valores por defecto SSRF estrictos, por lo que las redirecciones a destinos privados/internos se bloquean.
El modelo por defecto (gemini-2.5-flash) es rápido y económico. Se puede usar cualquier modelo Gemini que admita grounding.

web_search

Busca en la web usando tu proveedor configurado.

Requisitos

tools.web.search.enabled no debe ser false (por defecto: habilitado)
Clave API para tu proveedor elegido:
- Brave: BRAVE_API_KEY o tools.web.search.apiKey
- Gemini: GEMINI_API_KEY o tools.web.search.gemini.apiKey
- Grok: XAI_API_KEY o tools.web.search.grok.apiKey
- Kimi: KIMI_API_KEY, MOONSHOT_API_KEY o tools.web.search.kimi.apiKey
- Perplexity: PERPLEXITY_API_KEY, OPENROUTER_API_KEY o tools.web.search.perplexity.apiKey
Todos los campos de claves de proveedor anteriores admiten objetos SecretRef.

Configuración

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // opcional si BRAVE_API_KEY está configurado
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

Parámetros de la herramienta

Todos los parámetros funcionan para Brave y para la API nativa de Perplexity Search a menos que se indique lo contrario.

La ruta de compatibilidad OpenRouter / Sonar de Perplexity solo admite query y freshness. Si configuras tools.web.search.perplexity.baseUrl / model, usas OPENROUTER_API_KEY o configuras una clave sk-or-..., los filtros exclusivos de Search API devuelven errores explícitos.

Parámetro	Descripción
`query`	Consulta de búsqueda (obligatorio)
`count`	Resultados a devolver (1-10, por defecto: 5)
`country`	Código ISO de país de 2 letras (ej., “US”, “DE”)
`language`	Código de idioma ISO 639-1 (ej., “en”, “de”)
`freshness`	Filtro temporal: `day`, `week`, `month` o `year`
`date_after`	Resultados después de esta fecha (YYYY-MM-DD)
`date_before`	Resultados antes de esta fecha (YYYY-MM-DD)
`ui_lang`	Código de idioma de UI (solo Brave)
`domain_filter`	Array de allowlist/denylist de dominios (solo Perplexity)
`max_tokens`	Presupuesto total de contenido, por defecto 25000 (solo Perplexity)
`max_tokens_per_page`	Límite de tokens por página, por defecto 2048 (solo Perplexity)

Ejemplos:

// Búsqueda específica para Alemania
await web_search({
  query: "TV online schauen",
  country: "DE",
  language: "de",
});

// Resultados recientes (última semana)
await web_search({
  query: "TMBG interview",
  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 de dominios (solo Perplexity)
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// Excluir dominios (solo Perplexity)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

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

Cuando el modo Brave llm-context está habilitado, ui_lang, freshness, date_after y date_before no están admitidos. Usa el modo Brave web para esos filtros.

web_fetch

Obtén una URL y extrae contenido legible.

Requisitos de web_fetch

tools.web.fetch.enabled no debe ser false (por defecto: habilitado)
Fallback opcional de Firecrawl: configura tools.web.fetch.firecrawl.apiKey o FIRECRAWL_API_KEY.
tools.web.fetch.firecrawl.apiKey admite objetos SecretRef.

Configuración de web_fetch

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "FIRECRAWL_API_KEY_HERE", // opcional si FIRECRAWL_API_KEY está configurado
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1 día)
          timeoutSeconds: 60,
        },
      },
    },
  },
}

Parámetros de la herramienta web_fetch

url (obligatorio, solo http/https)
extractMode (markdown | text)
maxChars (trunca páginas largas)

Notas:

web_fetch usa Readability (extracción de contenido principal) primero, luego Firecrawl (si está configurado). Si ambos fallan, la herramienta devuelve un error.
Las solicitudes de Firecrawl usan modo de evasión de bots y almacenan resultados en caché por defecto.
Los SecretRefs de Firecrawl se resuelven solo cuando Firecrawl está activo (tools.web.fetch.enabled !== false y tools.web.fetch.firecrawl.enabled !== false).
Si Firecrawl está activo y su SecretRef no se resuelve sin fallback FIRECRAWL_API_KEY, el inicio/recarga falla inmediatamente.
web_fetch envía un User-Agent tipo Chrome y Accept-Language por defecto; sobreescribe userAgent si es necesario.
web_fetch bloquea hostnames privados/internos y re-verifica redirecciones (limita con maxRedirects).
maxChars está limitado a tools.web.fetch.maxCharsCap.
web_fetch limita el tamaño del cuerpo de respuesta descargado a tools.web.fetch.maxResponseBytes antes del parseo; las respuestas que exceden el tamaño se truncan e incluyen una advertencia.
web_fetch es extracción best-effort; algunos sitios necesitarán la herramienta browser.
Consulta Firecrawl para configuración de claves y detalles del servicio.
Las respuestas se almacenan en caché (15 minutos por defecto) para reducir fetches repetidos.
Si usas perfiles/listas de herramientas permitidas, agrega web_search/web_fetch o group:web.
Si falta la clave API, web_search devuelve una pista breve de configuración con un enlace a la documentación.