Wann ein eigener web_search-Anbieter die erwachsene Wahl ist
Standardintegrationen optimieren für schnelles Hello-World. Sie kodieren selten Ihre Datenresidenz, Rechnungsdeckel oder die Forderung, dass jede Egress-IP des Agents von einer vorsichtigen Sicherheitsorganisation freigegeben wird. Der Wechsel zu einem eigenen Anbieter bedeutet bewusst: Sie wählen einen HTTP-Vertrag, hängen Authentifizierung an, die Ihr Secret-Store besitzt, und hängen Observability an, die Finanzcontrolling lesen kann.
Regulierte Organisationen verlangen häufig einen internen Retrieval-Dienst, der Dokument-ACLs bereits durchsetzt. Wenn tools.web.search auf diesen Dienst zeigt, wird Policy wiederverwendet statt parallel neu erfunden. Der Preis ist Engineering: stabile Schemas, veröffentlichte SLOs und klare Strategien bei Teilausfällen ohne stillen Fallback ins öffentliche Internet, sofern Policy das verbietet.
Kostenbewusste Teams sehen Vendor-429er durch Modell-Retries lange vor Token-Limits. Eigenes Routing erlaubt Sharding über Schlüssel, Team-Budgets oder Drosselung von Automationen, die bei jedem Werkzeugaufruf Suche spammen. Dokumentieren Sie diese Budgets neben CPU und RAM, denn sie verhalten sich wie versteckte Rechenleistung.
Verfügbarkeit muss Forward-Proxies und Split-Horizon-DNS einkalkulieren. Ein Gateway, das vendor.example vom Laptop auflöst, scheitert auf einem Server, der Traffic durch eine Inspektions-Proxy-Kette mit eigenen Wurzelzertifikaten zwingt. Validieren Sie vom selben POSIX-Benutzer, denselben Umgebungsdateien und derselben cgroup wie in Produktion.
Operative Symmetrie hilft: Wenn Sie für Telegram-Aussetzer bereits Status, Gateway, doctor und Logs schichten, nutzen Sie dieselbe Disziplin für Suche. Unterschiedliche Symptome, gleiche Leiter verhindert widersprüchliche Wikis im Incident.
Behandeln Sie Konfigurationsänderungen wie Code: Pull Requests, Reviewerinnen mit SSRF-Verständnis und JSON-Schema-Checks in CI. Der Artikel Produktions-Hardening mit Webhook-Fokus erklärt, warum ausgehender HTTP dieselbe Skepsis verdient wie eingehende Webhooks.
Runbooks benennen Genehmiger für Provider-URLs, Wartungsfenster für Gateway-Neustarts und Rollback-Verifikation nach Snapshot-Disziplin aus dem Leitfaden zu Updates und MCP-Plugins. Ohne Owner wird Suche zur Integration, die alle nutzen und niemand pflegt, bis Kontingente brennen.
Multi-Region-Deployments brauchen klare Antworten, ob jedes Gateway-Cluster denselben Such-Endpunkt oder regionale Spiegel spricht. Abweichende DNS-Antworten erzeugen Flakes, bei denen Tokio funktioniert und Dublin scheitert trotz identischer JSON-Datei, wenn Sie nicht pro Request den effektiven Endpunkt protokollieren.
Wechseln Modelle mitten im Incident Provider, kann Suchtraffic explodieren, weil Werkzeuge Fähigkeiten neu enumerieren. Begrenzen Sie parallele Tool-Discovery-Aufrufe, damit ein Modellausfall nicht durch Verstärkung zum Suchausfall wird.
Plugin-orientierte Suchpfade—wenn Ihre Distribution Plugin-Suche neben core-web_search anbietet—verlangen dieselbe Threat-Modellierung: Wer darf welche HTTP-Ziele sehen, und wie trennen Sie Test- von Produktions-Endpunkten? Dokumentieren Sie das neben Kanal- und MCP-Transportentscheidungen aus dem MCP-Stufenplan, damit Upgrades keine stillen Doppelpfade öffnen.
Datenschutzrechtlich gehört Such-Logging in die gleiche Matrix wie Chat-Protokolle: Welche Suchbegriffe enthalten personenbezogene Merkmale, wie lange werden Antwort-Snippets aufbewahrt, und wer darf Rohlogs einsehen? Ein interner Provider erleichtert Löschkonzepte, ersetzt aber keine Privacy Impact Assessment, wenn externe Modelle Snippets weiterverarbeiten.
Schließlich sollten Sie Onboarding-Material für Entwicklerinnen schreiben, die web_search mit „Google im Hinterkopf“ verwechseln: Erklären Sie explizit, dass jede Abfrage Budget, Compliance und Incident-Rotation berührt, nicht nur Modellkosten.
Schmerzpunkte zerlegen
Schmerz 1: Secret-Sprawl. API-Schlüssel in JSON, das gleichzeitig in Dotfile-Sync-Tools liegt, lecken schneller als SSH-Keys. Bevorzugen Sie Umgebungsindirektion und kurzlebige Tokens, wo der Identity-Provider mitspielt.
Schmerz 2: SSRF über Suchparameter. Wenn das Modell beliebige Query-Strings liefern darf und Ihr Backend naiv erste Treffer nachlädt, haben Sie SSRF neu erfunden. Erzwingen Sie serverseitige Allowlists und entfernen Sie interne URL-Muster.
Schmerz 3: Doctor-False-Negatives. Doctor prüft lokale Konsistenz, nicht Vendor-Gesundheit. Kombinieren Sie synthetische Canary-Queries und externe Blackbox-Monitore.
Schmerz 4: Hot Reload versus Kaltstart. Wie beim MCP-Lebenszyklus wenden manche Builds JSON nur teilweise an, bis der Gateway-Prozess rotiert. Im Zweifel sauber neu starten und Kindprozesse zählen.
Schmerz 5: Suche mit Scraping verwechseln. Massenabrufe gehören hinter dediziertes Fetch-Tooling mit Cache und robots-Bewusstsein, nicht hinter einen Schnellsuche-Hack, der Traffic vervielfacht.
Schmerz 6: Proxy-Auth vergessen. Unternehmensnetze verlangen manchmal SPNEGO oder Basic am Forward-Proxy. Ohne dokumentierte Variablen scheitert curl vom Dienstkonto trotz gültiger Upstream-Keys.
Schmerz 7: IPv6-Asymmetrie. Wenn AAAA-Einträge existieren, Firewall-Regeln aber nur IPv4 abdecken, wirkt Suche intermittierend kaputt. Prüfen Sie beide Familien oder deaktivieren Sie bewusst eine Richtung.
Anbieter-Entscheidungsmatrix
| Backend-Stil | Stärke | Kostentreiber | Sicherheitshinweis | Ideal für |
|---|---|---|---|---|
| Vendor-JSON-API | Schnellste Compliance, wenn bereits freigegeben | Abrechnung pro Query plus Burst-Strafen | Schlüssel quartalsweise rotieren; 401-Spikes überwachen | Teams mit bestehender Enterprise-Suche |
| Interner Retrieval-Proxy | ACL-sensible Snippets | Engineering-Pflege und Indexfrische | file:// und Metadaten-SSRF blockieren | Zero-Trust-Dokumentzugriff |
| Selbst gehostet (SearXNG-artig) | Kostenkontrolle, Air-Gap-Optionen | Betriebszeit und Hardware | Admin-Oberflächen separat härten | Labore und regulierte Enklaven |
| Plugin-Shim-Prozess | Eigene Transformationen ohne Core-Fork | Zusätzliches Binary zum Patchen | Wie MCP bei Upgrades behandeln | Legacy-SOAP- oder Host-Brücken |
Wählen Sie pro Umgebung ein primäres Backend, dokumentieren Sie Ausnahmen und prüfen Sie nach großen OpenClaw-Upgrades neu, weil Schema-Schlüssel sich verschieben können.
Konfigurationsskelett für tools.web.search
{
"tools": {
"web": {
"search": {
"provider": "customHttp",
"baseUrl": "https://search.corp.example/api/v1/query",
"auth": {
"type": "bearer",
"tokenEnv": "CORP_SEARCH_TOKEN"
},
"timeoutMs": 12000,
"maxResults": 8,
"allowedHosts": ["search.corp.example"]
}
}
}
}
Ersetzen Sie Feldnamen durch die Ihrer Release; dieser Block ist strukturelle Orientierung, kein Versprechen wörtlicher Schlüssel. Geheimnisse immer indirekt aus Umgebungsvariablen laden, niemals Inline-Bearer-Strings, die in Shell-Historie oder Screenshots landen.
Schritt 1 Snapshot von openclaw.json und Gateway-Benutzer notieren. Schritt 2 HTTP-Dienst mit mTLS oder Netzwerkrichtlinien ausrollen. Schritt 3 JSON anwenden, Gateway neu starten, openclaw doctor ausführen. Schritt 4 Canary-Query senden und Logs auf Info ohne Token in Zeilen. Schritt 5 Dashboards für Latenz und HTTP-Codes vor Team-Rollout aktivieren.
Messbare Leitplanken gegen Rechnungsüberraschungen
Messen Sie Queries pro Stunde, pro Automation und pro API-Key. Weiche Alarme bei siebzig Prozent des Tageskontingents, harte Stopps, die zuerst nichtkritische Agenten abschalten. Kombinieren Sie Volumen mit Modell-Retry-Zählern, weil Backoff-Schleifen HTTP-Aufrufe still multiplizieren.
Erfassen Sie p50 und p95 getrennt; Schwanzlatenz spiegelt DNS- oder TLS-Handshake-Probleme, die im Mittelwert unsichtbar bleiben. Gleichen Sie Hostuhren ab, damit Logs regional korreliert werden.
Protokollieren Sie Payload-Größen für das Modell. Zu große Snippets treiben Kontextkosten, selbst wenn Suche billig wirkt. Kürzen Sie aggressiv am Proxy, wenn Policy das erlaubt.
Pflegen Sie ein Incident-Notizbuch mit exakten curl-Reproduktionen und redigierten Headern, damit Bereitschaft nicht rät, ob OpenClaw, Proxy oder Vendor schuld ist.
Vierteljährlich Rechnungen mit internen Metriken abstimmen; Abweichungen verraten oft Schatten-Keys auf vergessenen Staging-Gateways.
Definieren Sie Fehlerbudgets: akzeptabler 5xx-Prozentsatz pro Tag, maximale Folgefehler vor Page, mediane Erholungszeit nach Vendor-Vorfällen. Postmortems für Suchausfälle hängen Gateway-Logs, Proxy-Logs und exakten JSON-Diff an.
Nacht-Automationen sollten schwere Indexjobs nicht gegen interaktive Keys laufen lassen. Trennen Sie Schlüssel für Mensch versus Bot, um Attribution und Retry-Stürme zu entkoppeln.
Dokumentieren Sie maximale Snippet-Länge und verbotene MIME-Typen am Proxy, damit Surprises nicht im Modellkontext landen. Das kostet wenig CPU gegenüber Token-Spend.
Ergänzen Sie Kapazitätsplanung: Wenn Marketing-Kampagnen gleichzeitig mit Release-Nächten Suchlast erzeugen, reservieren Sie Rate-Limits pro Kanal. Verknüpfen Sie das mit TLS- und Timeout-Empfehlungen aus dem Reverse-Proxy-Artikel, falls öffentliche und interne Pfade denselben Edge teilen.
Operational Excellence bedeutet auch Schulungen: Zeigen Sie Support-Teams, wie man 429 von 401 unterscheidet und wann ein Rollback laut Rollback-Leitfaden schneller ist als Debuggen in Produktion.
Ausgehende Sicherheit und SSRF-Grenzen
Suche ist ausgehender HTTP, steckt aber in derselben Vertrauensgeschichte wie Webhooks. Wenn Ihr Backend URLs aus Snippets nachlädt, müssen Schema und Host vor jedem Folge-Fetch validiert werden. Denken Sie wie im SSRF-Hardening-Leitfaden, auch wenn die Richtung anders ist.
Host-Allowlists in OpenClaw sind nötig, nicht hinreichend; erzwingen Sie erneut an der Firewall, damit schlechte Config nicht wandern kann. Loggen Sie blockierte Versuche mit Automation-IDs, um Prompt-Muster zu erkennen.
Trennen Sie Produktions- und Staging-Tokens physisch; geteilte Keys lassen Experimente Produktionskontingente leeren. Unterschiedliche baseUrl-Werte pro Umgebung reduzieren Bedienfehler.
Wenn TLS-Inspection-Proxies Zertifikate neu signieren, importieren Sie Wurzeln im Trust Store des Dienstbenutzers, nicht nur für Admins. Doctor kann grün sein, während Queries mit undurchsichtigen TLS-Fehlern sterben.
Dokumentieren Sie, welche Automationen Suche ohne Aufsicht nutzen dürfen versus solche mit Human-in-the-Loop. Die Grenze ist Policy, nicht nur Technik.
Ergänzen Sie egress policy reviews bei jedem größeren Modell-Upgrade: neue Tool-Calling-Muster können indirekt mehr HTTP auslösen. Verknüpfen Sie das mit Installations- und Compose-Pfaden aus dem Installationsleitfaden, damit Container-Netzwerke nicht heimlich breiter werden als gedacht.
Wie sich MCP, web_fetch und web_search praktisch unterscheiden
MCP erweitert Werkzeuge über Subprozesse oder HTTP-Transport mit eigenem Versionieren; siehe Lecks und Neustart-Stufenplan für Fallen. Stark, wenn lokale Dateisysteme oder Spezialbinaries nötig sind.
web_search soll eine dünne HTTP-Integration mit planbaren Kontingenten bleiben. Sie zu einem beliebigen URL-Fetcher umzubauen, erzeugt einen unüberwachten Crawler.
web_fetch, wo vorhanden, braucht Cache, robots.txt-Respekt und Größenlimits. Wenn Ihr Stack Fetch und Suche verschmilzt, dokumentieren Sie das kombinierte Threat-Modell.
Nach Änderungen: Kaltstart, doctor, Kanalprobe wie im Gateway-Betrieb beschrieben. TLS-Randfälle gehören in den Proxy-Leitfaden.
Organisatorisch: MCP-Owner und Search-Owner sollten nicht identisch sein, damit Zuständigkeiten klar bleiben, auch wenn beide JSON berühren.
Glossar zum Suchbetrieb
tools.web.search benennt den JSON-Teilbaum für HTTP-Suche in vielen OpenClaw-Distributionen.
Eigener Anbieter meint jedes Backend jenseits der Demo-Integration, betrieben oder eingekauft.
Bearer-Token ist ein Authorization-Geheimnis, das nie in argv-Listings oder öffentlichen Logs landen darf.
Canary-Query ist ein fester Teststring nach Deploys zur Latenz- und Auth-Prüfung ohne Nutzerdaten.
Kaltstart stoppt den Gateway-Prozess vollständig vor Neustart, um gecachte Integrationszustände zu leeren.
Doctor scannt Konfiguration und Umgebung auf bekannte Fußangeln; kein Live-Vendor-Monitor.
SSRF ist Server-Side-Request-Forgery-Risiko, wenn nutzergesteuerte Strings zu URLs werden.
Allowlist listet erlaubte Hostnamen oder CIDRs für Egress.
429 signalisiert Ratenbegrenzung; mit Backoff und Alarmen behandeln.
Split-Horizon-DNS löst denselben Namen intern anders als im öffentlichen Internet.
Forward-Proxy vermittelt ausgehenden HTTP mit Inspektion und Policy.
mTLS ergänzt Clientzertifikate für gegenseitige Authentifizierung zwischen Gateway und Such-API.
Kontingent deckelt Queries oder Spend pro Tag; wie CPU-Drosseln behandeln.
Retry-Sturm entsteht, wenn Modelle oder Clients transient wiederholen und HTTP multiplizieren.
Kontextinflation wächst Tokenverbrauch durch überdimensionale Snippets.
Staging-Parität verlangt gleiche Integrationsform wie Produktion, nur andere Endpunkte und Keys.
JSON-Schema-CI lintet Config vor Merge gegen Tippfehler.
Observability-Kardinalität bleibt handlich, wenn Metriken pro Umgebung statt pro Chat-Session labeln.
Incident-Reproducer ist ein curl mit redigierten Secrets, der die Fehlergrenze beweist.
Gehosteter Fern-Mac ist verwaltete Apple-Hardware für Gateways plus SFTP-getriebene Build-Auslieferung.
Egress-Policy beschreibt schriftlich erlaubte Hosts und Ports für Automation.
Token-Rotation ersetzt API-Geheimnisse rhythmisch ohne Ausfall bei Dual-Key-Schemata.
Schema-Drift entsteht, wenn Upgrades JSON-Schlüssel umbenennen; CI verhindert stilles Fehlverhalten.
Blackbox-Probe ist externes Synthetic-Monitoring über den öffentlichen Pfad, nicht nur localhost.
Automation-Budget begrenzt parallele Agenten mit Suchzugriff in Incidents.
Proxy-Auth umfasst Upstream-Benutzerpasswort oder SPNEGO-Schichten bis zum Internet.
Log-Redaction entfernt Tokens und personenbezogene Daten vor zentraler Aggregation.
Change-Advisory ist ein leichtes CAB-Protokoll für JSON-Änderungen mit Egress- oder Kontingentwirkung.
Vendor-SLA beschreibt vertragliche Verfügbarkeit; Doctor ersetzt sie nicht.
Plugin-Suche kann zusätzliche HTTP-Endpunkte aktivieren; gleiche Allowlist-Disziplin wie bei core-web_search.
Snippet-Truncation kürzt Antworttext am Proxy vor Modellübergabe.
Dual-Stack bedeutet paralleles IPv4 und IPv6; Firewall muss beides explizit erlauben oder gezielt sperren.
Servicekonto-Parität verlangt Tests mit demselben Benutzer wie der Daemon, nicht mit interaktiver Admin-Shell.
Gateway-Neustart flacht Kindprozesse und hängende Transports ab; dokumentieren Sie ihn im Runbook neben doctor.
Outbound-Trace verbindet Request-IDs über Proxy, Gateway und Such-API für End-to-End-Latenz.
Kostenattribution weist Abfragen Teams oder Projekten zu, nicht nur API-Keys.
FAQ und Fern-Mac-Brücke
Soll Suche Schlüssel mit LLM-Anbietern teilen?
Nein. Getrennte Schlüssel erleichtern Rotation, Abrechnungszuordnung und Blast-Radius-Isolation.
Brauche ich IPv6-Egress-Planung?
Wenn der Vendor IPv6 bevorzugt oder der Host es standardmäßig aktiviert, prüfen Sie Firewall-Symmetrie, sonst flattert Suche mysteriös.
Was tun bei rein on-prem Such-API?
Nutzen Sie dieselben Mesh- oder VPN-Pfade wie für SSH; dokumentieren Sie MTU und DNS neben den OpenClaw-Hinweisen im Installationsleitfaden.
Zusammenfassung: Eigenes web_search ist Konfiguration plus ausgehende Sicherheit plus Observability. Behandeln Sie es wie jede Produktionsintegration, nicht wie einen versteckten Browser-Tab.
Grenzen: Selbst betriebene Gateways stapeln Proxies, Tokens, Platten und Apple-taugliche Build-Hosts. SFTPMAC-gehosteter Fern-Mac bündelt Verfügbarkeit und Zugangsmuster für Artefakte, was gut zu dauerhaft laufenden OpenClaw-Gateways passt, während Such-Policies reifen.
Lesereihenfolge konsequent halten: Gateway-Leiter, dann MCP-Lebenszyklus, dann TLS-Edge, dann dieser Suchleitfaden, dann SSRF-Hardening. Beständigkeit schlägt Neuerung im Incident.
Prüfen Sie SFTPMAC-Tarife, wenn Sie stabile macOS-Gateways neben konformer Dateiauslieferung brauchen.