Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix Feature: Add SearXNG as a web search provider option [4 comments, 4 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#43822•Fetched 2026-04-08 00:18:23
View on GitHub
Comments
4
Participants
4
Timeline
10
Reactions
3
Author
mbC6zCmbC6zC
Participants
gerritbgerritbjubnljubnlmbC6zCmbC6zCvincentkocvincentkoc
Timeline (top)
commented ×4subscribed ×4closed ×1locked ×1

Add SearXNG as an additional search provider option for the web_search tool, providing a free, self-hostable meta-search alternative to commercial APIs.

Error Message

  • Comprehensive error handling for API failures
  • Graceful error handling for network failures

Root Cause

Add SearXNG as an additional search provider option for the web_search tool, providing a free, self-hostable meta-search alternative to commercial APIs.

Code Example

# openclaw config
tools:
  web_search:
    provider: searxng
    searxng:
      baseUrl: http://localhost:8888  # or https://searxng.example.com
      fallbackOnBraveFailure: true     # optional: fallback to Brave if SearXNG fails

---

// Agent can override provider at runtime
{
  "tool": "web_search",
  "query": "latest AI developments",
  "provider": "searxng",
  "count": 5
}

---

{
  "content": "**Search Result Title**\nSnippet of content...\n\n**Another Result**\nMore content...",
  "citations": [
    "https://example.com/article1",
    "https://example.com/article2"
  ]
}

---

CRITICAL: Prioritize Brave and SearXNG (free) over Grok (paid API calls). 
Only use Grok provider when: (1) Brave is rate-limited OR (2) SearXNG returns 
insufficient results OR (3) user explicitly requests Grok.

---

# Existing configuration (still works)
tools:
  web_search:
    provider: brave
    brave:
      apiKey: xxx

# New configuration option
tools:
  web_search:
    provider: searxng  # or brave, perplexity, etc.
    searxng:
      baseUrl: http://localhost:8888
RAW_BUFFERClick to expand / collapse

Feature Request

Summary

Add SearXNG as an additional search provider option for the web_search tool, providing a free, self-hostable meta-search alternative to commercial APIs.

Motivation

While OpenClaw supports multiple search providers (Brave, Perplexity, Grok, Gemini, Kimi), they all require API keys and have associated costs. SearXNG offers:

  • Free to use: No API key requirements
  • Self-hostable: Can be deployed on own infrastructure
  • Privacy-focused: Meta-search engine that doesn't track users
  • Flexible: Aggregates results from multiple search engines
  • Cost-effective: Zero incremental cost per search

Proposed Solution

Add searxng as a new search provider option that:

  1. Configurable base URL (default: http://localhost:8888)
  2. Supports standard SearXNG JSON API format
  3. Returns search results with titles, URLs, and content snippets
  4. Integrates seamlessly with existing web_search tool interface
  5. Supports customizable engine selection (Google, Bing, DuckDuckGo, etc.)

Configuration

# openclaw config
tools:
  web_search:
    provider: searxng
    searxng:
      baseUrl: http://localhost:8888  # or https://searxng.example.com
      fallbackOnBraveFailure: true     # optional: fallback to Brave if SearXNG fails

Runtime Usage

// Agent can override provider at runtime
{
  "tool": "web_search",
  "query": "latest AI developments",
  "provider": "searxng",
  "count": 5
}

Benefits

  • Cost Reduction: Eliminate API costs for web search operations
  • Privacy: No third-party tracking or rate limiting
  • Reliability: Self-hosted means no external dependency failures
  • Flexibility: Choose which search engines to aggregate
  • Control: Full control over search results and ranking

Implementation Details

The implementation includes:

  • New runSearXNGSearch() function for SearXNG API integration
  • Configuration schema updates for searxng provider settings
  • Support for dynamic provider selection at runtime
  • Comprehensive error handling for API failures
  • Result parsing and citation extraction
  • Integration with existing search caching mechanism

Response Format

{
  "content": "**Search Result Title**\nSnippet of content...\n\n**Another Result**\nMore content...",
  "citations": [
    "https://example.com/article1",
    "https://example.com/article2"
  ]
}

Use Cases

  1. Development/Testing: Free local search for development environments
  2. Cost Optimization: Reduce commercial API usage for high-volume scenarios
  3. Privacy-Sensitive Applications: Organizations requiring data sovereignty
  4. Offline/Restricted Networks: Self-hosted instances in air-gapped environments
  5. Custom Search: Tailored search results for specific domains/topics

Comparison with Existing Providers

ProviderAPI Key RequiredCostPrivacySelf-Hostable
BraveYesFree tier ✓Medium✗
PerplexityYesPaidMedium✗
GrokYesPaidLow✗
GeminiYesPaidMedium✗
KimiYesPaidMedium✗
SearXNGNoFreeHigh✓

Fallback Behavior

The tool intelligently prioritizes free providers:

CRITICAL: Prioritize Brave and SearXNG (free) over Grok (paid API calls). 
Only use Grok provider when: (1) Brave is rate-limited OR (2) SearXNG returns 
insufficient results OR (3) user explicitly requests Grok.

Technical Notes

  • Uses SearXNG's JSON API format (format=json)
  • Default engine selection: Google, Bing, DuckDuckGo
  • Respects count, timeout, and cache parameters
  • Graceful error handling for network failures
  • Maintains compatibility with existing web_search tool interface

Migration Guide

No breaking changes. Existing configurations continue to work:

# Existing configuration (still works)
tools:
  web_search:
    provider: brave
    brave:
      apiKey: xxx

# New configuration option
tools:
  web_search:
    provider: searxng  # or brave, perplexity, etc.
    searxng:
      baseUrl: http://localhost:8888

Additional Context

SearXNG is particularly valuable for:

  • Users in regions with limited API access
  • Cost-conscious deployments with high search volumes
  • Privacy-focused applications requiring data control
  • Educational/research environments with budget constraints
  • Organizations preferring self-hosted infrastructure

The implementation maintains full backward compatibility while adding a powerful new option for cost-effective, privacy-respecting web search.

extent analysis

Problem Summary

Add SearXNG as a new web_search provider that can be selected via configuration or at runtime, returning results in the same shape as the existing providers.

Root Cause Analysis

The current web_search implementation only knows about providers that require API keys (Brave, Perplexity, etc.). There is no handler for the free, self‑hosted SearXNG JSON API, so requests with provider: "searxng" fail with unknown provider errors.

Fix Plan

1. Extend the configuration schema

// src/config/schema.ts
export const WebSearchProviderSchema = z.union([
  z.literal('brave'),
  z.literal('perplexity'),
  z.literal('grok'),
  z.literal('gemini'),
  z.literal('kimi'),
  z.literal('searxng'),          // ← new value
]);

export const SearXNGConfigSchema = z.object({
  baseUrl: z.string().url().default('http://localhost:8888'),
  fallbackOnBraveFailure: z.boolean().default(false),
});

Add the nested block to the overall config type:

export interface WebSearchConfig {
  provider: WebSearchProvider;
  brave?: BraveConfig;
  perplexity?: PerplexityConfig;
  // …
  searxng?: SearXNGConfig;   // ← new
}

2. Implement the SearXNG client

// src/tools/web_search/searxng.ts
import fetch from 'node-fetch';
import { SearchResult, SearchResponse } from '../types';

export interface SearXNGOptions {
  baseUrl: string;
  timeoutMs?: number;
}

/**
 * Calls SearXNG `/search` endpoint.
 * Docs: https://github.com/searxng/searxng/wiki/JSON-API
 */
export async function runSearXNGSearch(
  query: string,
  count: number,
  opts: SearXNGOptions,
): Promise<SearchResponse

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#optimization#permission error#memory optimization#batch processing

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix Feature: Add SearXNG as a web search provider option [4 comments, 4 participants]