Websuche

web_search durchsucht das Web mit Ihrem konfigurierten Provider und gibt normalisierte Ergebnisse zurück, die pro Suchanfrage 15 Minuten lang zwischengespeichert werden (konfigurierbar). OpenClaw enthält außerdem x_search für Beiträge auf X (ehemals Twitter) und web_fetch für leichtgewichtige URL-Abrufe. web_fetch wird immer lokal ausgeführt; web_search wird über xAI Responses geleitet, wenn Grok der Provider ist, und x_search verwendet immer xAI Responses.

Schnellstart

openclaw configure --section web

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

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

Provider auswählen

Provider-Vergleich

Ergebnisstruktur

web_search normalisiert jeden integrierten und externen Plugin-Provider an der zentralen Tool-Grenze. Aufrufer erhalten genau eine dieser abgeschlossenen Strukturen:

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;    };

Strukturierte Provider verwenden kind: "results"; synthetisierende Provider verwenden kind: "answer". Externe Plugin-Provider, deren Nutzdaten keiner der beiden Strukturen entsprechen, werden aus Kompatibilitätsgründen unverändert als kind: "raw" durchgereicht. Providerspezifische Felder wie Rohbewertungen, Auszüge, verwandte Suchanfragen, Offsets für Inline-Quellenangaben, Modell-IDs oder Sitzungsmetadaten werden in normalisierten Zweigen nicht durchgereicht. Verwenden Sie das dedizierte Tool eines Providers, wenn dessen umfangreichere Antwort Teil Ihres Workflows ist.

externalContent.wrapped: true ist eine Vertrauensmarkierung, deren Wahrheitsgehalt die Grenze selbst sicherstellt: Provider-Prosa (title, snippet, siteName, content, Titel von Quellenangaben, Fehler-message) wird von bereits vorhandenen Umschlagzeilen bereinigt und an der zentralen Grenze genau einmal neu umschlossen, sodass keine Provider-Metadaten die Markierung fälschen können. query entspricht immer der angeforderten Suchanfrage, URLs von Quellenangaben und Ergebnissen müssen als http(s) geparst werden können, published muss dem ISO-Datumsformat entsprechen, URLs werden in kanonisierter Form ausgegeben und Nutzdaten mit einem Schlüssel error werden immer als kind: "error" gemeldet, wobei der ursprüngliche Provider-Code innerhalb der umschlossenen Meldung erhalten bleibt. Unverändert durchgereichte Nutzdaten behalten alle vom Provider gesetzten Markierungen bei.

Automatische Erkennung

Provider-Listen in der Dokumentation und in Einrichtungsabläufen sind alphabetisch sortiert. Die automatische Erkennung verwendet eine separate, feste Prioritätsreihenfolge und wählt einen Provider, der Anmeldedaten benötigt (requiresCredential !== false), nur dann aus, wenn konfigurierte Anmeldedaten gefunden werden. Wenn kein provider festgelegt ist, prüft OpenClaw die Provider in dieser Reihenfolge und verwendet den ersten einsatzbereiten Provider:

Zuerst API-gestützte Provider:

1. Brave -- BRAVE_API_KEY oder plugins.entries.brave.config.webSearch.apiKey (Reihenfolge 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY oder plugins.entries.minimax.config.webSearch.apiKey (Reihenfolge 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY oder models.providers.google.apiKey (Reihenfolge 20)
4. Grok -- xAI OAuth, XAI_API_KEY oder plugins.entries.xai.config.webSearch.apiKey (Reihenfolge 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY oder plugins.entries.moonshot.config.webSearch.apiKey (Reihenfolge 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY oder plugins.entries.perplexity.config.webSearch.apiKey (Reihenfolge 50)
7. Firecrawl -- FIRECRAWL_API_KEY oder plugins.entries.firecrawl.config.webSearch.apiKey (Reihenfolge 60)
8. Exa -- EXA_API_KEY oder plugins.entries.exa.config.webSearch.apiKey; optional überschreibt plugins.entries.exa.config.webSearch.baseUrl den Exa-Endpunkt (Reihenfolge 65)
9. Tavily -- TAVILY_API_KEY oder plugins.entries.tavily.config.webSearch.apiKey (Reihenfolge 70)
10. Parallel -- kostenpflichtige Parallel Search API über PARALLEL_API_KEY oder plugins.entries.parallel.config.webSearch.apiKey; optional überschreibt plugins.entries.parallel.config.webSearch.baseUrl den Endpunkt (Reihenfolge 75)

Danach konfigurierte Endpunkt-Provider:

11. SearXNG -- SEARXNG_BASE_URL oder plugins.entries.searxng.config.webSearch.baseUrl (Reihenfolge 200)

Provider ohne Schlüssel wie Parallel Search (Free), DuckDuckGo, Ollama Web Search und Codex Hosted Search werden bei der automatischen Erkennung nie ausgewählt, obwohl sie einen internen Reihenfolgewert besitzen. Sie werden nur verwendet, wenn Sie sie explizit mit tools.web.search.provider oder über openclaw configure --section web auswählen. OpenClaw sendet verwaltete web_search-Abfragen nicht allein deshalb an einen Provider ohne Schlüssel, weil kein API-gestützter Provider konfiguriert ist.

OpenAI-Responses-Modelle bilden eine Ausnahme: Solange tools.web.search.provider nicht festgelegt ist, verwenden sie statt der oben genannten verwalteten Provider die native Websuche von OpenAI (siehe unten). Setzen Sie tools.web.search.provider auf parallel-free (oder einen anderen Provider), um sie stattdessen über den verwalteten Pfad zu leiten.

Native OpenAI-Websuche

Direkte OpenAI-Responses-Modelle (api: "openai-responses", Provider openai, keine Basis-URL oder eine offizielle OpenAI-API-Basis-URL) verwenden automatisch das von OpenAI gehostete web_search-Tool, wenn die OpenClaw-Websuche aktiviert und kein verwalteter Provider fest vorgegeben ist. Dieses Verhalten gehört dem Provider im mitgelieferten OpenAI-Plugin und gilt nicht für OpenAI-kompatible Proxy-Basis-URLs oder Azure- Routen. Setzen Sie tools.web.search.provider auf einen anderen Provider wie brave, um das verwaltete web_search-Tool für OpenAI-Modelle beizubehalten, oder setzen Sie tools.web.search.enabled: false, um sowohl die verwaltete Suche als auch die native OpenAI-Suche zu deaktivieren.

Native Codex-Websuche

Die Codex-App-Server-Laufzeit verwendet automatisch das von Codex gehostete web_search-Tool, wenn die Websuche aktiviert und kein verwalteter Provider ausgewählt ist. Die native gehostete Suche und das dynamische verwaltete web_search-Tool von OpenClaw schließen sich gegenseitig aus, sodass die verwaltete Suche native Domainbeschränkungen nicht umgehen kann. OpenClaw verwendet das verwaltete Tool, wenn die gehostete Suche nicht verfügbar oder explizit deaktiviert ist oder durch einen ausgewählten verwalteten Provider ersetzt wurde. OpenClaw lässt die eigenständige web.run-Erweiterung von Codex deaktiviert (features.standalone_web_search: false), da der App-Server-Verkehr in der Produktion ihren benutzerdefinierten web- Namensraum ablehnt.

• Konfigurieren Sie die native Suche unter tools.web.search.openaiCodex
• Setzen Sie tools.web.search.provider: "codex", um Codex Hosted Search als verwalteten web_search-Provider für ein beliebiges übergeordnetes Modell bereitzustellen. Jeder Aufruf führt einen begrenzten flüchtigen Codex-App-Server-Durchlauf aus und schlägt fehl, wenn Codex kein gehostetes webSearch-Element ausgibt.
• mode: "cached" ist die Standardeinstellung, Codex löst sie jedoch für uneingeschränkte App-Server-Durchläufe in einen externen Live-Zugriff auf; setzen Sie "live", um den Live-Zugriff explizit anzufordern
• Setzen Sie tools.web.search.provider auf einen verwalteten Provider wie brave, um stattdessen das verwaltete web_search von OpenClaw zu verwenden
• Setzen Sie tools.web.search.openaiCodex.enabled: false, um die von Codex gehostete Suche abzulehnen; andere verwaltete Provider bleiben verfügbar
• Eine Beschränkung der nativen Codex-Tool-Oberfläche hält auch das verwaltete web_search verfügbar
• Wenn allowedDomains festgelegt ist, schlägt der automatische verwaltete Fallback geschlossen fehl, falls die gehostete Suche nicht verfügbar ist, sodass die native Zulassungsliste nicht umgangen werden kann
• LLM-reine Durchläufe mit deaktivierten Tools deaktivieren sowohl die native als auch die verwaltete Suche
• tools.web.search.enabled: false deaktiviert sowohl die verwaltete als auch die native Suche

Dauerhafte Änderungen an der effektiven Codex-Suchrichtlinie starten einen neuen gebundenen Thread, damit ein bereits geladener App-Server-Thread keinen veralteten Zugriff auf die gehostete Suche beibehalten kann. Vorübergehende Einschränkungen pro Durchlauf verwenden einen temporären eingeschränkten Thread und bewahren die vorhandene Bindung für eine spätere Wiederaufnahme.

Direkter OpenAI-ChatGPT-Responses-Verkehr kann ebenfalls das von OpenAI gehostete web_search-Tool verwenden. Dieser separate Pfad muss weiterhin über tools.web.search.openaiCodex.enabled: true explizit aktiviert werden und gilt nur für geeignete openai/*-Modelle, die api: "openai-chatgpt-responses" verwenden.

{  tools: {    web: {      search: {        enabled: true,        // Optional: Codex Hosted Search auch von übergeordneten Nicht-Codex-Modellen verwenden.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

Für Laufzeiten und Provider, die die native Codex-Suche nicht unterstützen, kann Codex den verwalteten web_search-Fallback über den dynamischen Tool-Namensraum von OpenClaw verwenden. Verwenden Sie einen expliziten verwalteten Provider, wenn Sie statt der von Codex gehosteten Suche die providerspezifischen Netzwerksteuerungen von OpenClaw benötigen.

Die Auswahl von provider: "codex" aktiviert das mitgelieferte codex-Plugin und verwendet dieselben oben dargestellten tools.web.search.openaiCodex-Beschränkungen. Authentifizieren Sie zuerst den Codex-App-Server mit openclaw models auth login --provider openai. Der übergeordnete Agent kann ein beliebiges Modell oder eine beliebige Laufzeit verwenden; nur der begrenzte Such-Worker wird über Codex ausgeführt.

Netzwerksicherheit

Verwaltete HTTP-Aufrufe an web_search-Provider verwenden den geschützten Abrufpfad von OpenClaw, der auf den eigenen Hostnamen des aktuellen Providers beschränkt ist. Ausschließlich für diesen Hostnamen erlaubt OpenClaw Fake-IP-DNS-Antworten von Surge, Clash und sing-box in 198.18.0.0/15 und fc00::/7. Andere private, Loopback-, Link-Local- und Metadatenziele bleiben blockiert. Codex Hosted Search bildet die Ausnahme: Sein begrenzter Worker delegiert den Netzwerkzugriff an das gehostete web_search-Tool des Codex-App-Servers.

Diese automatische Zulassung gilt nicht für beliebige web_fetch-URLs. Aktivieren Sie für web_fetch die Optionen tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange und tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange nur dann explizit, wenn Ihr vertrauenswürdiger Proxy diese synthetischen Bereiche kontrolliert.

Konfiguration

{  tools: {    web: {      search: {        enabled: true, // Standardwert: true        provider: "brave", // oder für die automatische Erkennung weglassen        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

Providerspezifische Konfigurationen (API-Schlüssel, Basis-URLs, Modi) befinden sich unter plugins.entries.<plugin>.config.webSearch.*. Gemini kann außerdem models.providers.google.apiKey und models.providers.google.baseUrl als Fallbacks mit niedrigerer Priorität nach seiner dedizierten Websuchkonfiguration und GEMINI_API_KEY wiederverwenden. Beispiele finden Sie auf den Provider-Seiten. Grok kann außerdem ein xAI-OAuth-Authentifizierungsprofil aus openclaw models auth login --provider xai --method oauth wiederverwenden; die API-Schlüsselkonfiguration bleibt der Fallback.

tools.web.search.provider wird anhand der Websuch-Provider-IDs validiert, die in den Manifesten mitgelieferter und installierter Plugins deklariert sind. Ein Tippfehler wie "brvae" führt zum Fehlschlagen der Konfigurationsvalidierung, statt stillschweigend auf die automatische Erkennung zurückzufallen. Wenn für einen konfigurierten Provider nur veraltete Plugin-Nachweise vorhanden sind, beispielsweise ein übrig gebliebener plugins.entries.<plugin>-Block nach der Deinstallation eines Drittanbieter-Plugins, bleibt der Start von OpenClaw robust und es wird eine Warnung ausgegeben, sodass Sie das Plugin neu installieren oder openclaw doctor --fix ausführen können, um die veraltete Konfiguration zu bereinigen.

Die Auswahl des web_fetch-Fallback-Providers erfolgt separat:

• Wählen Sie ihn mit tools.web.fetch.provider aus
• oder lassen Sie dieses Feld weg und OpenClaw erkennt anhand der konfigurierten Anmeldedaten automatisch den ersten einsatzbereiten Webabruf- Provider
• Nicht in einer Sandbox ausgeführtes web_fetch kann installierte Plugin-Provider verwenden, die contracts.webFetchProviders deklarieren; Sandbox-Abrufe erlauben mitgelieferte Provider und verifizierte offizielle Plugin-Installationen, schließen jedoch externe Drittanbieter-Plugins aus
• Das offizielle Firecrawl-Plugin ist derzeit der einzige mitgelieferte webFetchProviders- Beitrag und wird unter plugins.entries.firecrawl.config.webFetch.* konfiguriert

Wenn Sie während openclaw onboard oder openclaw configure --section web Kimi auswählen, kann OpenClaw außerdem Folgendes abfragen:

• die Moonshot-API-Region (https://api.moonshot.ai/v1 oder https://api.moonshot.cn/v1)
• das standardmäßige Kimi-Websuchmodell (Standardwert: kimi-k2.6)

Konfigurieren Sie für x_search die Option plugins.entries.xai.config.xSearch.*. Sie verwendet dasselbe xAI-Authentifizierungsprofil wie der Chat oder die XAI_API_KEY- bzw. Plugin-Websuch- Anmeldedaten, die von der Grok-Websuche verwendet werden. Die veraltete tools.web.x_search.*-Konfiguration wird von openclaw doctor --fix automatisch migriert. Wenn Sie Grok während openclaw onboard oder openclaw configure --section web auswählen, bietet OpenClaw außerdem eine optionale Einrichtung von x_search mit denselben Anmeldedaten an, unmittelbar nachdem die Grok-Einrichtung abgeschlossen ist. Dies ist ein separater Folgeschritt innerhalb des Grok- Pfads und keine separate Websuch-Provider-Auswahl auf oberster Ebene. Wenn Sie einen anderen Provider auswählen, zeigt OpenClaw die Eingabeaufforderung x_search nicht an.

API-Schlüssel speichern

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

export BRAVE_API_KEY="YOUR_KEY"

Tool-Parameter

x_search

x_search durchsucht mit xAI Beiträge auf X (ehemals Twitter) und gibt KI-synthetisierte Antworten mit Quellenangaben zurück. Es akzeptiert natürlichsprachliche Anfragen und optionale strukturierte Filter. OpenClaw erstellt das integrierte xAI-Tool x_search für jede Anfrage neu, statt es dauerhaft zu registrieren. Daher ist es nur für den Turn aktiv, in dem es tatsächlich aufgerufen wird.

x_search-Konfiguration

Wenn enabled nicht angegeben ist, wird x_search nur bereitgestellt, wenn der Provider des aktiven Modells xai ist und xAI-Anmeldedaten aufgelöst werden können. Legen Sie bei einem aktiven Modell mit bekanntem Nicht-xAI-Provider plugins.entries.xai.config.xSearch.enabled auf true fest, um die Provider-übergreifende Nutzung zu aktivieren. Wenn der Provider des aktiven Modells fehlt oder nicht aufgelöst werden kann, bleibt das Tool ausgeblendet. Legen Sie enabled auf false fest, um es für jeden Provider zu deaktivieren. xAI-Anmeldedaten sind immer erforderlich.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // für einen bekannten Nicht-xAI-Modell-Provider erforderlich            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // optional, überschreibt webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // optional, wenn ein xAI-Authentifizierungsprofil oder XAI_API_KEY festgelegt ist            baseUrl: "https://api.x.ai/v1", // optionale gemeinsam genutzte Basis-URL für xAI Responses          },        },      },    },  },}

x_search sendet Anfragen an <baseUrl>/responses, wenn plugins.entries.xai.config.xSearch.baseUrl festgelegt ist. Wenn dieses Feld nicht angegeben ist, wird zunächst auf plugins.entries.xai.config.webSearch.baseUrl und anschließend auf den öffentlichen xAI-Endpunkt (https://api.x.ai/v1) zurückgegriffen.

x_search-Parameter

allowed_x_handles und excluded_x_handles schließen sich gegenseitig aus.

x_search-Beispiel

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

// Statistiken pro Beitrag: Verwenden Sie nach Möglichkeit die genaue Status-URL oder Status-IDawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Beispiele

// Einfache Sucheawait web_search({ query: "OpenClaw Plugin SDK" }); // Deutschlandspezifische Sucheawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Aktuelle Ergebnisse (vergangene Woche)await web_search({ query: "KI-Entwicklungen", freshness: "week" }); // Datumsbereichawait web_search({  query: "Klimaforschung",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Domainfilterung (nur Perplexity)await web_search({  query: "Produktbewertungen",  domain_filter: ["-reddit.com", "-pinterest.com"],});

Tool-Profile

Wenn Sie Tool-Profile oder Zulassungslisten verwenden, fügen Sie web_search, x_search oder group:web hinzu:

{  tools: {    allow: ["web_search", "x_search"],    // oder: allow: ["group:web"]  (enthält web_search, x_search und web_fetch)  },}

Verwandte Themen

• Web Fetch – eine URL abrufen und lesbaren Inhalt extrahieren
• Webbrowser – vollständige Browserautomatisierung für Websites mit intensiver JavaScript-Nutzung
• Grok-Suche – Grok als web_search-Provider
• Ollama-Websuche – schlüsselfreie Websuche über Ihren Ollama-Host