Background

Currently, tools.web.search.provider accepts a single provider. If no provider is explicitly configured, OpenClaw auto-detects the first provider that appears to be ready.

That works for normal cases, but API-based search providers often fail temporarily at runtime even when they are correctly configured and auto-detectable. Common examples:

• Free monthly quota or trial credits are exhausted
• 429 rate limit / quota exceeded responses
• Temporary network errors, DNS/proxy issues, connection timeouts
• Provider-side 5xx errors

These are not permanent configuration errors. In many setups, users already have multiple search providers configured and expect OpenClaw to try another configured provider instead of failing immediately.

Requested feature

Please add a web_search provider fallback / failover chain.

Expected behavior:

1. Use the explicitly configured provider, or the first provider selected by auto-detection.
2. If that provider fails with a recoverable runtime error, try the next configured fallback provider.
3. Use key-free DuckDuckGo only as the final fallback.
4. If all providers fail, return an aggregated error explaining which providers were tried and why each one failed.

Example use case

A user has Brave, Perplexity, Tavily, and DuckDuckGo available:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        fallbacks: ["perplexity", "tavily", "duckduckgo"]
      }
    }
  }
}

If Brave runs out of free credits or returns 429, OpenClaw should try Perplexity. If Perplexity has a temporary network error, OpenClaw should try Tavily. DuckDuckGo should be used only after the configured higher-quality providers fail.

A possible auto mode could also build a fallback chain from already configured providers:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "auto",
        fallbackConfiguredProviders: true,
        fallbackToDuckDuckGo: true
      }
    }
  }
}

Suggested recoverable errors

Fallback should be attempted for errors such as:

• 408 / timeout
• 429 / rate limit / quota exceeded / free quota exhausted
• 502 / 503 / 504
• Network errors such as DNS failures, ECONNRESET, ETIMEDOUT, or fetch failed

Fallback should probably not be attempted for:

• 400 bad request
• 401 / 403 authentication or permission errors
• Missing provider configuration
• Deterministic provider-specific parameter errors

Why DuckDuckGo should be the final fallback

DuckDuckGo is useful as a key-free fallback, but it should not be used too early when the user has already configured multiple paid or higher-quality providers.

Desired order for many users:

1. Use the preferred high-quality API provider.
2. If it temporarily fails, try other configured high-quality API providers.
3. Only if all configured API providers fail, fall back to DuckDuckGo.

Related issue

There was a similar historical request in #35647, which was closed as stale. This issue is intended to restate the latest use case more concretely: when free quota is exhausted, rate limits are hit, or temporary network errors occur, web_search should try other configured channels before finally falling back to DuckDuckGo.

Suggested acceptance criteria

• Support an explicit fallback chain, for example tools.web.search.fallbacks.
• Support auto mode fallback to other already configured providers.
• Recoverable runtime errors trigger fallback; authentication and deterministic parameter errors do not.
• Logs record each fallback attempt, including provider and reason.
• The final error aggregates all attempted providers and failure reasons.
• Backward compatibility is preserved: if no fallback chain is configured, current single-provider behavior remains unchanged.