Búsqueda web

​

Inicio rápido

openclaw configure --section web

await web_search({ query: "OpenClaw plugin SDK" });

await x_search({ query: "dinner recipes" });

​

Elegir un proveedor

​

Comparación de proveedores

​

Estructura de los resultados

type WebSearchOutput =
  | {
      kind: "error";
      provider: string;
      error: "provider_error";
      message: string;
      docs?: string;
    }
  | {
      kind: "results";
      provider: string;
      query: string;
      count: number;
      tookMs?: number;
      results: Array<{
        title: string;
        url: string;
        snippet?: string;
        published?: string;
        siteName?: string;
      }>;
      externalContent: {
        untrusted: true;
        source: "web_search";
        wrapped: true;
        provider: string;
      };
      cached?: true;
    }
  | {
      kind: "answer";
      provider: string;
      query: string;
      tookMs?: number;
      content: string;
      citations?: Array<{ url: string; title?: string }>;
      externalContent: {
        untrusted: true;
        source: "web_search";
        wrapped: true;
        provider: string;
      };
      cached?: true;
    }
  | {
      kind: "raw";
      provider: string;
      data: unknown;
    };

​

Detección automática

1. Brave — BRAVE_API_KEY o plugins.entries.brave.config.webSearch.apiKey (orden 10)
2. MiniMax Search — MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY o plugins.entries.minimax.config.webSearch.apiKey (orden 15)
3. Gemini — plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY o models.providers.google.apiKey (orden 20)
4. Grok — OAuth de xAI, XAI_API_KEY o plugins.entries.xai.config.webSearch.apiKey (orden 30)
5. Kimi — KIMI_API_KEY / MOONSHOT_API_KEY o plugins.entries.moonshot.config.webSearch.apiKey (orden 40)
6. Perplexity — PERPLEXITY_API_KEY / OPENROUTER_API_KEY o plugins.entries.perplexity.config.webSearch.apiKey (orden 50)
7. Firecrawl — FIRECRAWL_API_KEY o plugins.entries.firecrawl.config.webSearch.apiKey (orden 60)
8. Exa — EXA_API_KEY o plugins.entries.exa.config.webSearch.apiKey; el valor opcional plugins.entries.exa.config.webSearch.baseUrl sustituye el endpoint de Exa (orden 65)
9. Tavily — TAVILY_API_KEY o plugins.entries.tavily.config.webSearch.apiKey (orden 70)
10. Parallel — API de pago Parallel Search mediante PARALLEL_API_KEY o plugins.entries.parallel.config.webSearch.apiKey; el valor opcional plugins.entries.parallel.config.webSearch.baseUrl sustituye el endpoint (orden 75)

11. SearXNG — SEARXNG_BASE_URL o plugins.entries.searxng.config.webSearch.baseUrl (orden 200)

​

Búsqueda web nativa de OpenAI

​

Búsqueda web nativa de Codex

• Configure la búsqueda nativa bajo tools.web.search.openaiCodex
• Defina tools.web.search.provider: "codex" para proporcionar Codex Hosted Search como el proveedor web_search administrado para cualquier modelo principal. Cada llamada ejecuta un turno efímero y acotado del app-server de Codex y falla si Codex no emite un elemento webSearch alojado.
• mode: "cached" es la preferencia predeterminada, pero Codex la resuelve como acceso externo en vivo para los turnos de app-server sin restricciones; defina "live" para solicitar explícitamente acceso en vivo.
• Defina tools.web.search.provider como un proveedor administrado, por ejemplo brave, para utilizar en su lugar el web_search administrado de OpenClaw.
• Defina tools.web.search.openaiCodex.enabled: false para excluirse de la búsqueda alojada por Codex; los demás proveedores administrados seguirán disponibles.
• Restringir la superficie de herramientas nativas de Codex también mantiene disponible el web_search administrado.
• Cuando se define allowedDomains, la alternativa administrada automática falla de forma cerrada si la búsqueda alojada no está disponible, de modo que no se pueda eludir la lista de permitidos nativa.
• Las ejecuciones solo con LLM y herramientas deshabilitadas deshabilitan tanto la búsqueda nativa como la administrada.
• tools.web.search.enabled: false deshabilita tanto la búsqueda administrada como la nativa.

{
  tools: {
    web: {
      search: {
        enabled: true,
        // Opcional: utilizar Codex Hosted Search también desde modelos principales que no sean Codex.
        provider: "codex",
        openaiCodex: {
          enabled: true,
          mode: "cached",
          allowedDomains: ["example.com"],
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "New York",
            timezone: "America/New_York",
          },
        },
      },
    },
  },
}

​

Seguridad de la red

​

Configuración

{
  tools: {
    web: {
      search: {
        enabled: true, // predeterminado: true
        provider: "brave", // u omitir para la detección automática
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

• elíjalo con tools.web.fetch.provider
• o bien omita ese campo y permita que OpenClaw detecte automáticamente el primer proveedor de obtención web disponible entre las credenciales configuradas.
• El web_fetch sin entorno aislado puede utilizar proveedores de Plugins instalados que declaren contracts.webFetchProviders; las obtenciones en entornos aislados permiten proveedores incluidos e instalaciones verificadas de Plugins oficiales, pero excluyen los Plugins externos de terceros.
• El Plugin oficial Firecrawl es actualmente el único colaborador incluido de webFetchProviders, configurado bajo plugins.entries.firecrawl.config.webFetch.*.

• la región de la API de Moonshot (https://api.moonshot.ai/v1 o https://api.moonshot.cn/v1)
• el modelo de búsqueda web predeterminado de Kimi (el valor predeterminado es kimi-k2.6)

​

Almacenamiento de claves de API

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_KEY", // pragma: allowlist secret
          },
        },
      },
    },
  },
}

export BRAVE_API_KEY="YOUR_KEY"

​

Parámetros de la herramienta

​

x_search

​

Configuración de x_search

{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true, // obligatorio para un proveedor conocido de modelos que no sea xAI
            model: "grok-4.3",
            baseUrl: "https://api.x.ai/v1", // opcional, reemplaza webSearch.baseUrl
            inlineCitations: false,
            maxTurns: 2,
            timeoutSeconds: 30,
            cacheTtlMinutes: 15,
          },
          webSearch: {
            apiKey: "xai-...", // opcional si se ha configurado un perfil de autenticación de xAI o XAI_API_KEY
            baseUrl: "https://api.x.ai/v1", // URL base opcional compartida de Responses de xAI
          },
        },
      },
    },
  },
}

​

Parámetros de x_search

​

Ejemplo de x_search

await x_search({
  query: "recetas para la cena",
  allowed_x_handles: ["nytfood"],
  from_date: "2026-03-01",
});

// Estadísticas por publicación: utilice la URL exacta del estado o el ID de estado cuando sea posible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

​

Ejemplos

// Búsqueda básica
await web_search({ query: "SDK de plugins de OpenClaw" });

// Búsqueda específica para alemán
await web_search({ query: "ver televisión en línea", country: "DE", language: "de" });

// Resultados recientes (última semana)
await web_search({ query: "avances en IA", freshness: "week" });

// Intervalo de fechas
await web_search({
  query: "investigación climática",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Filtrado de dominios (solo Perplexity)
await web_search({
  query: "reseñas de productos",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

​

Perfiles de herramientas

{
  tools: {
    allow: ["web_search", "x_search"],
    // o bien: allow: ["group:web"]  (incluye web_search, x_search y web_fetch)
  },
}

​

Temas relacionados

• Obtención web — obtiene una URL y extrae contenido legible
• Navegador web — automatización completa del navegador para sitios con uso intensivo de JS
• Búsqueda con Grok — Grok como proveedor web_search
• Búsqueda web de Ollama — búsqueda web sin clave mediante el host de Ollama