@jzakirov/internet-search 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamil Zakirov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# internet-search
+
+Web search for [OpenClaw](https://openclaw.dev) agents, backed by a self-hosted [SearXNG](https://searxng.github.io/searxng/) instance.
+
+Registers a single `internet-search` tool with category routing for general, news, academic, and social results.
+
+## Installation
+
+```bash
+openclaw plugins install @jzakirov/internet-search
+```
+
+Or from a local path (development):
+
+```bash
+openclaw plugins install ./internet-search
+```
+
+## Configuration
+
+Add to `openclaw.json` under `plugins.entries.internet-search.config`:
+
+```json
+{
+  "searxngUrl": "https://search.example.com/",
+  "searxngToken": "optional-bearer-token"
+}
+```
+
+| Field          | Required | Description                                   |
+|----------------|----------|-----------------------------------------------|
+| `searxngUrl`   | Yes      | Base URL of your SearXNG instance             |
+| `searxngToken` | No       | Token for SearXNG instances that require auth |
+
+## Replacing the built-in web search
+
+To use this plugin as the sole web search (disabling the default Brave/Perplexity `web_search` tool), set `tools.web.search.enabled` to `false`:
+
+```json5
+// openclaw.json
+{
+  "tools": {
+    "web": {
+      "search": {
+        "enabled": false   // disable built-in web_search tool
+      }
+    }
+  },
+  "plugins": {
+    "allow": ["internet-search"],
+    "entries": {
+      "internet-search": {
+        "enabled": true,
+        "config": {
+          "searxngUrl": "https://search.example.com/",
+          "searxngToken": "your-token"
+        }
+      }
+    }
+  }
+}
+```
+
+If you only want to add `internet-search` alongside the built-in tool (rather than replace it), omit the `tools.web.search.enabled` change.
+
+## Tool: `internet-search`
+
+```
+internet-search(query, count?, category?)
+```
+
+| Parameter  | Type   | Default   | Description                                      |
+|------------|--------|-----------|--------------------------------------------------|
+| `query`    | string | —         | Search query                                     |
+| `count`    | number | 5         | Number of results to return (1–20, capped at 10) |
+| `category` | string | `general` | Routing category (see below)                     |
+
+### Categories
+
+| Value      | Routes to                      |
+|------------|--------------------------------|
+| `general`  | All configured SearXNG engines |
+| `news`     | SearXNG news category          |
+| `academic` | arXiv, Google Scholar, PubMed  |
+| `social`   | Reddit                         |
+
+### Response
+
+```json
+{
+  "results": [
+    {
+      "title": "Example result",
+      "url": "https://example.com/article",
+      "snippet": "A short excerpt from the page..."
+    }
+  ]
+}
+```
+
+HTML tags are stripped from snippets automatically.
+
+## Requirements
+
+- OpenClaw ≥ 2025.0.0
+- A running SearXNG instance with JSON format enabled (`search.formats: [json]` in SearXNG config)
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,80 @@
+// internet-search plugin: SearXNG-backed search tool
+
+function stripHtml(input: string) {
+  return input
+    .replace(/<[^>]*>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// Maps category → SearXNG query params.
+// "general" uses all configured engines (no override).
+// Others route to specialist engines for better signal.
+const CATEGORY_ROUTING: Record<string, { categories?: string; engines?: string }> = {
+  general:  {},
+  news:     { categories: "news" },
+  academic: { engines: "arxiv,google scholar,pubmed" },
+  social:   { engines: "reddit" },
+};
+
+export default function (api: any) {
+  api.registerTool({
+    name: "internet-search",
+    description:
+      "Search the web using a SearXNG instance. Use this to gather news and learn new information. " +
+      "Use category='news' for recent events, 'academic' for research papers, 'social' for opinions/discussions.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        query: { type: "string" },
+        count: { type: "number", minimum: 1, maximum: 20, default: 5 },
+        category: {
+          type: "string",
+          enum: ["general", "news", "academic", "social"],
+          default: "general",
+          description:
+            "general=broad web search (default); news=recent news & events; " +
+            "academic=arxiv/Scholar/PubMed; social=Reddit discussions"
+        }
+      },
+      required: ["query"]
+    },
+    async execute(_id: string, params: any, signal: AbortSignal) {
+      const baseUrl = String(api.config?.searxngUrl ?? "").trim();
+      if (!baseUrl) {
+        throw new Error("searxngUrl is required in the internet-search plugin config");
+      }
+      const token = String(api.config?.searxngToken ?? "").trim();
+
+      const q = String(params.query ?? "").trim();
+      const count = Math.min(10, Math.max(1, Number(params.count ?? 5)));
+      const category = String(params.category ?? "general").trim();
+      const routing = CATEGORY_ROUTING[category] ?? {};
+
+      const url = new URL("/search", baseUrl);
+      url.searchParams.set("q", q);
+      url.searchParams.set("format", "json");
+      if (token) url.searchParams.set("token", token);
+      if (routing.categories) url.searchParams.set("categories", routing.categories);
+      if (routing.engines)    url.searchParams.set("engines", routing.engines);
+
+      const res = await fetch(url.toString(), { signal });
+      if (!res.ok) throw new Error(`SearXNG HTTP ${res.status}`);
+
+      const data: any = await res.json();
+      const results = Array.isArray(data?.results) ? data.results : [];
+      const mapped = results.slice(0, count).map((r: any) => ({
+        title: String(r?.title ?? "").trim(),
+        url: String(r?.url ?? "").trim(),
+        snippet: stripHtml(String(r?.content ?? r?.snippet ?? ""))
+      }));
+
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ results: mapped }, null, 2) }
+        ]
+      };
+    }
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "internet-search",
+  "kind": "web-search",
+  "name": "Internet Search",
+  "description": "Web search via SearXNG. Registers the internet-search tool.",
+  "version": "0.2.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "searxngUrl": { "type": "string" },
+      "searxngToken": { "type": "string" }
+    },
+    "required": ["searxngUrl"]
+  },
+  "uiHints": {
+    "searxngUrl": { "label": "SearXNG URL", "placeholder": "https://search.example.com/" },
+    "searxngToken": { "label": "SearXNG Token", "sensitive": true }
+  }
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@jzakirov/internet-search",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "SearXNG-backed internet search plugin for OpenClaw",
+  "license": "MIT",
+  "keywords": ["openclaw", "openclaw-plugin", "searxng", "search", "internet-search", "web-search"],
+  "files": ["index.ts", "openclaw.plugin.json", "skills", "README.md", "LICENSE"],
+  "peerDependencies": {
+    "openclaw": ">=2025.0.0"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  }
+}

package/skills/internet-search/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: internet-search
+description: "How to use the internet-search tool effectively — category routing, query formulation, and multi-search strategies. Use whenever web search is needed: current events, research papers, community opinions, or any information beyond training knowledge."
+---
+
+# Internet Search
+
+Queries a self-hosted SearXNG instance aggregating multiple search engines.
+
+## Category Routing
+
+Always set `category` based on the nature of the query.
+
+| Category   | When to use                                                         | Engines                                          |
+|------------|---------------------------------------------------------------------|--------------------------------------------------|
+| `general`  | Default. Facts, how-tos, products, people, broad web.               | Brave, Bing, DDG, Startpage, Qwant, Wikipedia…  |
+| `news`     | Recent events, breaking news, anything time-sensitive.              | Bing News, DDG News                              |
+| `academic` | Research papers, studies, medical literature, preprints.            | arXiv, Google Scholar, PubMed                    |
+| `social`   | Opinions, community recommendations, "what do people think about X".| Reddit                                           |
+
+## Query Formulation
+
+Write queries as a search engine expects — keywords, not full sentences:
+
+```
+# Bad
+"what is the fastest async runtime for rust"
+
+# Good
+"rust async runtime benchmarks 2025"
+```
+
+- **news**: include a time anchor — `"OpenAI o3 release 2025"` not just `"OpenAI o3"`
+- **academic**: use field terminology — `"transformer attention efficiency survey"`
+- **social**: phrase as community search — `"reddit best mechanical keyboard 2025"`
+
+## Count
+
+- `count=5` (default) — sufficient for most tasks
+- `count=10` — comparing many options, checking consensus
+- `count=3` — quick fact checks
+
+## Multi-Search Strategy
+
+Fire multiple focused searches rather than one broad one:
+
+```
+# Bad: one vague search
+internet-search("best way to deploy Node.js")
+
+# Good: three targeted searches
+internet-search("Node.js Docker deployment best practices 2025")
+internet-search("Node.js PM2 vs Docker production", category="social")
+internet-search("Node.js zero-downtime deployment strategies")
+```
+
+Combine `general` + `social` for factual + sentiment coverage:
+
+```
+internet-search("Bun runtime performance vs Node.js benchmarks")
+internet-search("Bun runtime production experience", category="social")
+```
+
+## When NOT to Use
+
+- Things you already know with high confidence
+- Stable API docs or well-known syntax — use training knowledge
+- Repeating a search that already answered the question
+
+## Common Mistakes
+
+| Mistake                                   | Fix                                           |
+|-------------------------------------------|-----------------------------------------------|
+| `general` for a research paper            | Use `category="academic"`                     |
+| Searching "what happened today"           | Use `category="news"` with a specific topic   |
+| One broad search for a multi-part question| Break into 2–3 focused searches               |
+| Repeating a failed search verbatim        | Rephrase with different keywords              |
+| `count=20` for a simple fact              | Default `count=5` is almost always enough     |