searxng-web-search

# SearXNG Web Search

Privacy-respecting web search skill powered by SearXNG, a free metasearch engine
that aggregates results from 243+ search services without tracking users.

Rewritten from PulseBot's built-in web search skill to use SearXNG as the backend,
packaged as a standalone agentskills.io skill.

## Prerequisites

1. A running SearXNG instance (self-hosted or accessible endpoint)
2. JSON format must be enabled in your SearXNG `settings.yml`:

```yaml
search:
  formats:
    - html
    - json
```

3. Python `requests` library installed

## Configuration

The skill uses environment variables for configuration:

| Variable | Default | Description |
|---|---|---|
| `SEARXNG_BASE_URL` | `http://localhost:8080` | SearXNG instance URL |
| `SEARXNG_MAX_RESULTS` | `10` | Maximum results to return |
| `SEARXNG_LANGUAGE` | `all` | Default search language (e.g. `en`, `zh`, `all`) |
| `SEARXNG_SAFESEARCH` | `0` | Safe search level: 0=off, 1=moderate, 2=strict |
| `SEARXNG_TIMEOUT` | `15` | Request timeout in seconds |
| `SEARXNG_CATEGORIES` | `general` | Default categories (comma-separated) |

## Usage

Run the search script:

```bash
python scripts/searxng_search.py "your search query"
```

With options:

```bash
python scripts/searxng_search.py "latest AI news" \
  --categories news \
  --language en \
  --time-range day \
  --max-results 5
```

### Output Format

The script outputs JSON to stdout with the following structure:

```json
{
  "query": "search query",
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Text snippet from the page...",
      "engines": ["google", "bing"],
      "score": 9.0,
      "category": "general",
      "published_date": "2025-01-01T00:00:00"
    }
  ],
  "suggestions": ["related query 1", "related query 2"],
  "answers": ["direct answer if available"],
  "total_results": 10,
  "error": null
}
```

If an error occurs, `results` will be empty and `error` will contain the message....

# searxng-web-search

[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-compatible-blue)](https://agentskills.io)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](LICENSE)
[![ClawHub](https://img.shields.io/badge/ClawHub-published-orange)](https://clawhub.ai)

A privacy-respecting web search skill for AI agents, powered by [SearXNG](https://docs.searxng.org/) metasearch engine. Follows the [agentskills.io](https://agentskills.io) standard.

Rewritten from [PulseBot](https://github.com/timeplus-io/PulseBot)'s built-in `web_search` skill to use SearXNG as a self-hosted, privacy-first search backend.

## Features

- **Privacy-first**: SearXNG aggregates 243+ search engines without tracking users
- **Self-hosted**: Full control over your search infrastructure
- **Multi-category**: Search general web, news, images, IT, science, and more
- **Structured output**: JSON results with title, URL, snippet, score, and engine attribution
- **Agent-ready**: Works with PulseBot, Claude Code, OpenClaw, GitHub Copilot, and any agentskills.io-compatible agent
- **Robust error handling**: Graceful failures with structured error responses

## Quick Start

### 1. Install the Skill

**Via ClawHub CLI:**

```bash
npm i -g clawhub
clawhub install searxng-web-search
```

**Via Git:**

```bash
git clone https://github.com/timeplus-io/searxng-web-search.git
cp -r searxng-web-search ~/.openclaw/workspace/skills/
# or for Claude Code:
cp -r searxng-web-search .claude/skills/
```

### 2. Start SearXNG

```bash
docker run -d --name searxng -p 8080:8080 \
  -v "$(pwd)/searxng:/etc/searxng" searxng/searxng:latest
```

> **Important**: Enable JSON API in your SearXNG `settings.yml` — see [references/REFERENCE.md](references/REFERENCE.md).

### 3. Install Python Dependency

```bash
pip install requests
```

### 4. Search

```bash
# CLI
python scripts/searxng_search.py "latest streaming SQL developments"

# Human-readable output
python scripts/searxng_search.py "SearXNG...