Web search in OpenClaw

Search is the tool most agents reach for first, and it is also the one most likely to be wired to whatever key happens to be lying around. OpenClaw treats it as a normalised interface rather than a passthrough: results from every bundled and external plugin provider are reshaped at the core tool boundary, so a caller always receives exactly one of a small set of closed shapes. Provider choice is explicit or auto-detected, never accidental. The same care extends to the trust markers on returned prose and to what the fetch path is allowed to reach.

Three tools, one boundary

• Web search queries the configured provider and returns normalised results cached by query for 15 minutes by default, while OpenClaw also bundles an X post search and a lightweight fetch, with the fetch always running locally and the X post search always going through xAI Responses.
• Structured providers return a results shape carrying a title, a URL and an optional snippet, published date and site name, synthesised providers return an answer shape with content and optional citations, and external plugin payloads matching neither pass through verbatim as a raw shape.
• Provider-specific extras such as raw scores, excerpts, related searches, inline-citation offsets, model identifiers and session metadata are dropped on the normalised branches, so a provider dedicated tool is the way to keep its richer response.
• Citation and result URLs must parse as http or https, published dates must be ISO-date shaped, URLs are emitted canonicalised, and a payload carrying an error key is always reported as an error with the raw provider code preserved inside the wrapped message.

An explicitly selected provider does not use automatic fallback.

How a provider is chosen

Provider lists in the documentation and the setup flows are alphabetical, but auto-detection uses a separate, fixed precedence order. It only picks a provider that needs a credential when it finds one configured, so an empty install does not silently start searching. API-backed providers come first, in the order Brave, MiniMax, Gemini, Grok, Kimi, Perplexity, Firecrawl, Exa, Tavily and Parallel, with the self-hosted SearXNG endpoint considered after all of them. If an auto-detected provider fails, OpenClaw tries the next eligible one, and if every attempt fails it reports the first provider error so the primary failure is the one you see. Key-free providers such as the free Parallel search, DuckDuckGo, Ollama web search and Codex Hosted Search never win auto-detection even though they carry an internal order value; they are used only when you select them explicitly. Direct OpenAI Responses models are the exception, using the hosted OpenAI search while no managed provider is pinned, and the Codex app-server runtime does the same with its own hosted tool. Native hosted search and the managed tool are mutually exclusive, so managed search cannot bypass native domain restrictions. A configured provider name is validated against the provider identifiers declared by bundled and installed plugin manifests, so a typo fails config validation instead of quietly falling back to auto-detection.

Parameters and provider limits

• The shared parameters cover the query, a result count between one and ten defaulting to five, country and language codes, a freshness filter of day, week, month or year, explicit after and before dates, and a Perplexity-only domain allowlist or denylist.
• Not every parameter works everywhere: the Brave llm-context mode rejects the UI language parameter, a before date also needs an after date because Brave custom freshness ranges require both a start and an end, and Firecrawl and Tavily support only the query and the count through the shared tool.
• Gemini, Grok and Kimi return one synthesised answer with citations and accept a count only for shared-tool compatibility, and Gemini treats day freshness as a recency hint while wider freshness values and explicit dates set Google Search grounding time ranges.

The two halves of this page have separate reference pages: Web search for the search tool and its providers, and Web fetch for pulling a specific URL and extracting readable content. Fetch provider selection is separate from search provider selection, and sandboxed fetches allow bundled providers and verified official plugin installs but exclude third-party external plugins.

Why normalise at the boundary

Normalising at the core boundary is what makes the trust marker meaningful. Provider prose, meaning titles, snippets, site names, answer content, citation titles and error messages, is stripped of any pre-existing envelope lines and re-wrapped exactly once, so no provider metadata can spoof the marker. Raw passthrough payloads keep whatever markers the provider set, which is the honest cost of supporting plugin providers that fit neither normalised shape. The same reasoning limits the network: managed search calls use the OpenClaw guarded fetch path scoped to the current provider own hostname, and only for that hostname does it allow the fake-IP DNS answers that Surge, Clash and sing-box return, while other private, loopback, link-local and metadata destinations remain blocked. That allowance does not apply to arbitrary fetch URLs, which need their own explicit policy options before a trusted proxy synthetic ranges are permitted. Search is also deliberately lightweight, an HTTP tool rather than browser automation, so JS-heavy sites and logins belong in Web browser instead. And because every result lands in the model window, the cache lifetime and the result count are as much a Context management decision as a cost one.

On Diali

On Diali, Hosted OpenClaw on Diali runs as one assistant per customer, with the runtime configuration generated from the dashboard and replaced at each release. State lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). Plan details are on Diali pricing.

• One tool, closed result shapes, and a trust marker applied at the boundary.
• Auto-detection picks only a provider whose credential is already configured.
• Key-free providers are opt-in; they never win auto-detection.