SearXNG search

기준일: 2026-07-26
난이도: 중급
공식 기준: SearXNG search

개요

이 페이지는 OpenClaw SearXNG search 도구(파라미터, 권한, 설정, CLI)를 공식 문서 기준으로 정리합니다.

공식 요약: SearXNG web search -- self-hosted, key-free meta-search provider

도구 가시성은 profile / allow·deny policy / sandbox / channel 권한에 따라 달라집니다. 최신 스키마는 항상 공식 문서를 우선합니다.

공식 문서 기반 상세

아래는 공식 tools/searxng-search 문서를 정리한 내용입니다. 코드 블록, 파라미터 이름, 기본값은 원문 그대로입니다.

OpenClaw supports SearXNG as a self-hosted, key-free web_search provider. SearXNG is an open-source meta-search engine that aggregates results from Google, Bing, DuckDuckGo, and other sources.

Advantages:

• Free and unlimited -- no API key or commercial subscription required
• Privacy / air-gap -- queries never leave your network
• Works anywhere -- no region restrictions on commercial search APIs

설정

Install the plugin

```bash
openclaw plugins install @openclaw/searxng-plugin
```

Run a SearXNG instance

```bash
docker run -d -p 8888:8080 searxng/searxng
```

Or use any existing SearXNG deployment you have access to. See the
[SearXNG documentation](https://docs.searxng.org/) for production setup.

Configure

```bash
openclaw configure --section web
# Select "searxng" as the provider
```

Or set the env var and let auto-detection find it:

```bash
export SEARXNG_BASE_URL="http://localhost:8888"
```

Config

{
  tools: {
    web: {
      search: {
        provider: "searxng",
      },
    },
  },
}

Plugin-level settings for the SearXNG instance:

{
  plugins: {
    entries: {
      searxng: {
        config: {
          webSearch: {
            baseUrl: "http://localhost:8888",
            categories: "general,news", // optional
            language: "en", // optional
          },
        },
      },
    },
  },
}

baseUrl also accepts a SecretRef object (for example { source: "env", id: "SEARXNG_BASE_URL" }).

환경 변수

Set SEARXNG_BASE_URL as an alternative to config:

export SEARXNG_BASE_URL="http://localhost:8888"

Resolution order: configured baseUrl string, then an inline env SecretRef on baseUrl, then SEARXNG_BASE_URL. When none of the config paths are set and SEARXNG_BASE_URL is present with no explicit provider chosen, auto-detection picks SearXNG.

Plugin config reference

Field	Description
baseUrl	Base URL of your SearXNG instance (required)
categories	Comma-separated categories such as general, news, or science
language	Language code for results such as en, de, or fr

The web_search tool call also accepts count (1-10 results), categories, and language as per-call overrides.

참고

• JSON API -- uses SearXNG's native format=json endpoint, not HTML scraping
• Image result URLs -- image-category results include img_src when SearXNG returns a direct image URL
• No API key -- works with any SearXNG instance out of the box
• Base URL validation -- baseUrl must be a valid http:// or https:// URL
• Network guard -- http:// base URLs must target a trusted private or loopback host (public hosts must use https://); https:// base URLs that resolve to a private/internal address get the same self-hosted allowance, while https:// base URLs that resolve publicly keep strict SSRF protection
• Auto-detection order -- SearXNG requires a configured baseUrl (order 200 among providers that already have their required credential). Key-free providers such as DuckDuckGo or Ollama Web Search never win auto-detection implicitly; they only activate on an explicit provider choice
• Self-hosted -- you control the instance, queries, and upstream search engines
• Categories default to general when not configured
• Category fallback -- if a non-general category request succeeds but returns zero results, OpenClaw retries the same query once with general before returning an empty result set
• Result caching -- identical queries (same query, count, categories, language, and base URL) are cached in-process for a short TTL
• Version requirement -- the plugin declares minHostVersion: >=2026.6.9

For SearXNG JSON API to work, make sure your SearXNG instance has the json format enabled in its settings.yml under search.formats.

관련 문서

• Web Search overview -- all providers and auto-detection
• DuckDuckGo Search -- another key-free provider
• Brave Search -- structured results with free tier

검증 체크리스트

• 해당 tool이 활성 profile/policy에서 허용되는지 확인
• sandbox / elevated / host 실행 경로 정책을 이해했는지 확인
• 채널·에이전트 권한과 충돌하지 않는지 확인
• 공식 CLI/--help와 문서 옵션이 버전과 맞는지 확인

관련

• Tools 목록 인덱스
• 공식: Tools overview, Tools and custom providers