Web-Tools

OpenClaw liefert zwei leichtgewichtige Web-Tools mit:

• web_search — Web-Suche über Brave Search API, Gemini mit Google Search Grounding, Grok, Kimi oder Perplexity Search API.
• web_fetch — HTTP-Fetch + lesbare Extraktion (HTML → Markdown/Text).

Das ist keine Browser-Automatisierung. Für JS-lastige Seiten oder Logins verwende das Browser-Tool.

Wie es funktioniert

• web_search ruft deinen konfigurierten Provider auf und gibt Ergebnisse zurück.
• Ergebnisse werden 15 Minuten lang per Query gecacht (konfigurierbar).
• web_fetch macht einen einfachen HTTP GET und extrahiert lesbaren Inhalt (HTML → Markdown/Text). Es führt kein JavaScript aus.
• web_fetch ist standardmäßig aktiviert (es sei denn, explizit deaktiviert).

Siehe Brave Search Setup und Perplexity Search Setup für provider-spezifische Details.

Einen Such-Provider wählen

Auto-Erkennung

Die Tabelle oben ist alphabetisch. Wenn kein provider explizit gesetzt ist, prüft die Runtime-Auto-Erkennung Provider in dieser Reihenfolge:

1. Brave — BRAVE_API_KEY Env-Variable oder tools.web.search.apiKey Config
2. Gemini — GEMINI_API_KEY Env-Variable oder tools.web.search.gemini.apiKey Config
3. Grok — XAI_API_KEY Env-Variable oder tools.web.search.grok.apiKey Config
4. Kimi — KIMI_API_KEY / MOONSHOT_API_KEY Env-Variable oder tools.web.search.kimi.apiKey Config
5. Perplexity — PERPLEXITY_API_KEY, OPENROUTER_API_KEY oder tools.web.search.perplexity.apiKey Config

Wenn keine Keys gefunden werden, fällt es auf Brave zurück (du bekommst einen Fehler mit fehlendem Key und der Aufforderung, einen zu konfigurieren).

SecretRef-Verhalten zur Runtime:

• Web-Tool-SecretRefs werden beim Gateway-Start/Reload atomar aufgelöst.
• Im Auto-Detect-Modus löst OpenClaw nur den Key des ausgewählten Providers auf. Nicht ausgewählte Provider-SecretRefs bleiben inaktiv, bis sie ausgewählt werden.
• Wenn der SecretRef des ausgewählten Providers nicht aufgelöst werden kann und kein Provider-Env-Fallback existiert, scheitert der Start/Reload sofort.

Web-Suche einrichten

Verwende openclaw configure --section web, um deinen API-Key einzurichten und einen Provider zu wählen.

Brave Search

1. Erstelle ein Brave Search API-Konto auf brave.com/search/api
2. Wähle im Dashboard den Search-Plan und generiere einen API-Key.
3. Führe openclaw configure --section web aus, um den Key in der Config zu speichern, oder setze BRAVE_API_KEY in deiner Umgebung.

Jeder Brave-Plan enthält $5/Monat an kostenlosem Guthaben (erneuernd). Der Search-Plan kostet $5 pro 1.000 Anfragen, das Guthaben deckt also 1.000 Abfragen/Monat ab. Setze dein Nutzungslimit im Brave-Dashboard, um unerwartete Kosten zu vermeiden. Siehe das Brave API-Portal für aktuelle Pläne und Preise.

Perplexity Search

1. Erstelle ein Perplexity-Konto auf perplexity.ai/settings/api
2. Generiere einen API-Key im Dashboard
3. Führe openclaw configure --section web aus, um den Key in der Config zu speichern, oder setze PERPLEXITY_API_KEY in deiner Umgebung.

Für Legacy-Sonar/OpenRouter-Kompatibilität setze stattdessen OPENROUTER_API_KEY oder konfiguriere tools.web.search.perplexity.apiKey mit einem sk-or-...-Key. Das Setzen von tools.web.search.perplexity.baseUrl oder model wechselt Perplexity ebenfalls zurück auf den Chat-Completions-Kompatibilitätspfad.

Siehe Perplexity Search API Docs für weitere Details.

Wo den Key speichern

Via Config: Führe openclaw configure --section web aus. Es speichert den Key unter dem provider-spezifischen Config-Pfad:

• 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

Alle diese Felder unterstützen auch SecretRef-Objekte.

Via Umgebung: Setze Provider-Env-Variablen in der Gateway-Prozessumgebung:

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

Für eine Gateway-Installation platziere diese in ~/.openclaw/.env (oder deiner Service-Umgebung). Siehe Env-Variablen.

Konfigurationsbeispiele

Brave Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // optional wenn BRAVE_API_KEY gesetzt // pragma: allowlist secret
      },
    },
  },
}

Brave LLM Context-Modus:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // optional wenn BRAVE_API_KEY gesetzt // pragma: allowlist secret
        brave: {
          mode: "llm-context",
        },
      },
    },
  },
}

llm-context gibt extrahierte Seiten-Chunks für Grounding zurück statt Standard-Brave-Snippets. In diesem Modus funktionieren country und language / search_lang weiterhin, aber ui_lang, freshness, date_after und date_before werden abgelehnt.

Perplexity Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // optional wenn PERPLEXITY_API_KEY gesetzt
        },
      },
    },
  },
}

Perplexity via OpenRouter / Sonar-Kompatibilität:

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

Gemini verwenden (Google Search Grounding)

Gemini-Modelle unterstützen eingebautes Google Search Grounding, das KI-synthetisierte Antworten liefert, gestützt auf Live-Google-Suchergebnisse mit Zitaten.

Einen Gemini API-Key erhalten

1. Gehe zu Google AI Studio
2. Erstelle einen API-Key
3. Setze GEMINI_API_KEY in der Gateway-Umgebung oder konfiguriere tools.web.search.gemini.apiKey

Gemini-Suche einrichten

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // API-Key (optional wenn GEMINI_API_KEY gesetzt)
          apiKey: "AIza...",
          // Modell (Standard "gemini-2.5-flash")
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

Umgebungsalternative: Setze GEMINI_API_KEY in der Gateway-Umgebung. Für eine Gateway-Installation platziere ihn in ~/.openclaw/.env.

Hinweise

• Zitat-URLs aus Gemini Grounding werden automatisch von Googles Redirect-URLs zu direkten URLs aufgelöst.
• Die Redirect-Auflösung verwendet den SSRF-Schutzpfad (HEAD + Redirect-Checks + http/https-Validierung) vor der Rückgabe der endgültigen Zitat-URL.
• Die Redirect-Auflösung verwendet strenge SSRF-Defaults, daher werden Redirects zu privaten/internen Zielen blockiert.
• Das Standardmodell (gemini-2.5-flash) ist schnell und kosteneffektiv. Jedes Gemini-Modell, das Grounding unterstützt, kann verwendet werden.

web_search

Das Web mit deinem konfigurierten Provider durchsuchen.

Voraussetzungen

• tools.web.search.enabled darf nicht false sein (Standard: aktiviert)
• API-Key für deinen gewählten Provider:
  • Brave: BRAVE_API_KEY oder tools.web.search.apiKey
  • Gemini: GEMINI_API_KEY oder tools.web.search.gemini.apiKey
  • Grok: XAI_API_KEY oder tools.web.search.grok.apiKey
  • Kimi: KIMI_API_KEY, MOONSHOT_API_KEY oder tools.web.search.kimi.apiKey
  • Perplexity: PERPLEXITY_API_KEY, OPENROUTER_API_KEY oder tools.web.search.perplexity.apiKey
• Alle oben genannten Provider-Key-Felder unterstützen SecretRef-Objekte.

Konfiguration

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // optional wenn BRAVE_API_KEY gesetzt
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

Tool-Parameter

Alle Parameter funktionieren für Brave und die native Perplexity Search API, sofern nicht anders angegeben.

Der OpenRouter / Sonar-Kompatibilitätspfad von Perplexity unterstützt nur query und freshness. Wenn du tools.web.search.perplexity.baseUrl / model setzt, OPENROUTER_API_KEY verwendest oder einen sk-or-...-Key konfigurierst, geben Search-API-only-Filter explizite Fehler zurück.

Beispiele:

// Deutschlandspezifische Suche
await web_search({
  query: "TV online schauen",
  country: "DE",
  language: "de",
});

// Aktuelle Ergebnisse (letzte Woche)
await web_search({
  query: "TMBG interview",
  freshness: "week",
});

// Datumsbereich-Suche
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Domain-Filterung (nur Perplexity)
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// Domains ausschließen (nur Perplexity)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// Mehr Content-Extraktion (nur Perplexity)
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

Wenn der Brave llm-context-Modus aktiviert ist, werden ui_lang, freshness, date_after und date_before nicht unterstützt. Verwende den Brave web-Modus für diese Filter.

web_fetch

Eine URL abrufen und lesbaren Inhalt extrahieren.

web_fetch-Voraussetzungen

• tools.web.fetch.enabled darf nicht false sein (Standard: aktiviert)
• Optionaler Firecrawl-Fallback: setze tools.web.fetch.firecrawl.apiKey oder FIRECRAWL_API_KEY.
• tools.web.fetch.firecrawl.apiKey unterstützt SecretRef-Objekte.

web_fetch-Konfiguration

{
  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", // optional wenn FIRECRAWL_API_KEY gesetzt
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1 Tag)
          timeoutSeconds: 60,
        },
      },
    },
  },
}

web_fetch Tool-Parameter

• url (erforderlich, nur http/https)
• extractMode (markdown | text)
• maxChars (lange Seiten kürzen)

Hinweise:

• web_fetch verwendet zuerst Readability (Hauptinhalt-Extraktion), dann Firecrawl (wenn konfiguriert). Wenn beides fehlschlägt, gibt das Tool einen Fehler zurück.
• Firecrawl-Anfragen verwenden Bot-Umgehungsmodus und cachen Ergebnisse standardmäßig.
• Firecrawl-SecretRefs werden nur aufgelöst, wenn Firecrawl aktiv ist (tools.web.fetch.enabled !== false und tools.web.fetch.firecrawl.enabled !== false).
• Wenn Firecrawl aktiv ist und sein SecretRef nicht aufgelöst werden kann und kein FIRECRAWL_API_KEY-Fallback existiert, scheitert der Start/Reload sofort.
• web_fetch sendet standardmäßig einen Chrome-ähnlichen User-Agent und Accept-Language; überschreibe userAgent bei Bedarf.
• web_fetch blockiert private/interne Hostnamen und prüft Redirects erneut (begrenzen mit maxRedirects).
• maxChars wird auf tools.web.fetch.maxCharsCap begrenzt.
• web_fetch begrenzt die heruntergeladene Antwort-Body-Größe auf tools.web.fetch.maxResponseBytes vor dem Parsen; übergroße Antworten werden gekürzt und enthalten eine Warnung.
• web_fetch ist Best-Effort-Extraktion; einige Seiten brauchen das Browser-Tool.
• Siehe Firecrawl für Key-Setup und Service-Details.
• Antworten werden gecacht (Standard 15 Minuten), um wiederholte Abrufe zu reduzieren.
• Wenn du Tool-Profile/Allowlists verwendest, füge web_search/web_fetch oder group:web hinzu.
• Wenn der API-Key fehlt, gibt web_search einen kurzen Setup-Hinweis mit einem Docs-Link zurück.