@openclaw/searxng-plugin 0.0.0 → 2026.6.11

package/README.md

@@ -1,3 +1,13 @@
-# @openclaw/searxng-plugin
+# SearXNG OpenClaw plugin
 
-Bootstrap reservation for the OpenClaw SearXNG plugin package.
+Official OpenClaw plugin for SearXNG.
+
+## Install
+
+```sh
+openclaw plugins install @openclaw/searxng-plugin
+```
+
+## Docs
+
+See `docs/tools/searxng-search.md` in the OpenClaw repository, or the published docs at `https://docs.openclaw.ai/tools/searxng-search`.

package/dist/index.js

@@ -0,0 +1,13 @@
+import { t as createSearxngWebSearchProvider } from "./searxng-search-provider-Da4Go6Vh.js";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+//#region extensions/searxng/index.ts
+var searxng_default = definePluginEntry({
+	id: "searxng",
+	name: "SearXNG Plugin",
+	description: "Bundled SearXNG web search plugin",
+	register(api) {
+		api.registerWebSearchProvider(createSearxngWebSearchProvider());
+	}
+});
+//#endregion
+export { searxng_default as default };

package/dist/searxng-client-BFVWmp9D.js

@@ -0,0 +1,219 @@
+import { DEFAULT_CACHE_TTL_MINUTES, DEFAULT_SEARCH_COUNT, normalizeCacheKey, readCache, readResponseText, resolveCacheTtlMs, resolveSearchCount, resolveSiteName, resolveTimeoutSeconds, withSelfHostedWebSearchEndpoint, withTrustedWebSearchEndpoint, wrapWebContent, writeCache } from "openclaw/plugin-sdk/provider-web-search";
+import { assertHttpUrlTargetsPrivateNetwork, isBlockedHostnameOrIp, isPrivateIpAddress, resolvePinnedHostnameWithPolicy } from "openclaw/plugin-sdk/ssrf-runtime";
+import { normalizeResolvedSecretInputString, normalizeSecretInput } from "openclaw/plugin-sdk/secret-input";
+//#region extensions/searxng/src/config.ts
+function normalizeConfiguredString(value, path) {
+	try {
+		return normalizeSecretInput(normalizeResolvedSecretInputString({
+			value,
+			path
+		}));
+	} catch {
+		return;
+	}
+}
+function readInlineEnvSecretRefValue(value, env) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const record = value;
+	if (record.source !== "env" || typeof record.id !== "string") return;
+	return normalizeSecretInput(env[record.id]);
+}
+function normalizeTrimmedString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function normalizeBaseUrl(value) {
+	return value?.replace(/\/+$/u, "") || void 0;
+}
+function resolveSearxngWebSearchConfig(config) {
+	const webSearch = (config?.plugins?.entries?.searxng?.config)?.webSearch;
+	if (webSearch && typeof webSearch === "object" && !Array.isArray(webSearch)) return webSearch;
+}
+function resolveSearxngBaseUrl(config, env = process.env) {
+	const webSearch = resolveSearxngWebSearchConfig(config);
+	return normalizeBaseUrl(normalizeConfiguredString(webSearch?.baseUrl, "plugins.entries.searxng.config.webSearch.baseUrl")) ?? normalizeBaseUrl(readInlineEnvSecretRefValue(webSearch?.baseUrl, env)) ?? normalizeBaseUrl(normalizeSecretInput(env.SEARXNG_BASE_URL));
+}
+function resolveSearxngCategories(config) {
+	return normalizeTrimmedString(resolveSearxngWebSearchConfig(config)?.categories);
+}
+function resolveSearxngLanguage(config) {
+	return normalizeTrimmedString(resolveSearxngWebSearchConfig(config)?.language);
+}
+//#endregion
+//#region extensions/searxng/src/searxng-client.ts
+const DEFAULT_TIMEOUT_SECONDS = 20;
+const MAX_RESPONSE_BYTES = 1e6;
+const SEARXNG_SEARCH_CACHE = /* @__PURE__ */ new Map();
+function normalizeSearxngResult(value) {
+	if (!value || typeof value !== "object") return null;
+	const candidate = value;
+	if (typeof candidate.url !== "string" || typeof candidate.title !== "string") return null;
+	return {
+		url: candidate.url,
+		title: candidate.title,
+		content: typeof candidate.content === "string" ? candidate.content : void 0,
+		img_src: typeof candidate.img_src === "string" ? candidate.img_src : void 0
+	};
+}
+function buildSearxngSearchUrl(params) {
+	const url = new URL(params.baseUrl);
+	url.pathname = url.pathname.endsWith("/") ? `${url.pathname}search` : `${url.pathname}/search`;
+	url.search = "";
+	url.searchParams.set("q", params.query);
+	url.searchParams.set("format", "json");
+	if (params.categories) url.searchParams.set("categories", params.categories);
+	if (params.language) url.searchParams.set("language", params.language);
+	return url.toString();
+}
+function shouldRetryEmptyCategorySearchWithGeneral(categories) {
+	if (!categories) return false;
+	const normalized = categories.split(",").map((category) => category.trim().toLowerCase()).filter((category) => category.length > 0);
+	return normalized.length > 0 && !normalized.includes("general");
+}
+async function searxngEndpointTargetsPrivateNetwork(url, lookupFn) {
+	if (isBlockedHostnameOrIp(url.hostname)) return true;
+	try {
+		return (await resolvePinnedHostnameWithPolicy(url.hostname, {
+			lookupFn,
+			policy: {
+				allowPrivateNetwork: true,
+				allowRfc2544BenchmarkRange: true
+			}
+		})).addresses.every((address) => isPrivateIpAddress(address));
+	} catch {
+		return false;
+	}
+}
+async function validateSearxngBaseUrl(baseUrl, lookupFn) {
+	let parsed;
+	try {
+		parsed = new URL(baseUrl);
+	} catch {
+		throw new Error("SearXNG base URL must be a valid http:// or https:// URL.");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error("SearXNG base URL must use http:// or https://.");
+	if (parsed.protocol === "http:") {
+		await assertHttpUrlTargetsPrivateNetwork(parsed.toString(), {
+			dangerouslyAllowPrivateNetwork: true,
+			lookupFn,
+			errorMessage: "SearXNG HTTP base URL must target a trusted private or loopback host. Use https:// for public hosts."
+		});
+		return "selfHosted";
+	}
+	return await searxngEndpointTargetsPrivateNetwork(parsed, lookupFn) ? "selfHosted" : "strict";
+}
+function parseSearxngResponseText(text, count) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new Error("SearXNG returned invalid JSON.");
+	}
+	if (!parsed || typeof parsed !== "object") return [];
+	const response = parsed;
+	const rawResults = Array.isArray(response.results) ? response.results : [];
+	const results = [];
+	for (const rawResult of rawResults) {
+		const result = normalizeSearxngResult(rawResult);
+		if (result) results.push(result);
+		if (results.length >= count) break;
+	}
+	return results;
+}
+async function fetchSearxngResults(params) {
+	const url = buildSearxngSearchUrl({
+		baseUrl: params.baseUrl,
+		query: params.query,
+		categories: params.categories,
+		language: params.language
+	});
+	return await (params.endpointMode === "selfHosted" ? withSelfHostedWebSearchEndpoint : withTrustedWebSearchEndpoint)({
+		url,
+		timeoutSeconds: params.timeoutSeconds,
+		init: {
+			method: "GET",
+			headers: { Accept: "application/json" }
+		}
+	}, async (response) => {
+		if (!response.ok) {
+			const detail = (await readResponseText(response, { maxBytes: 64e3 })).text;
+			throw new Error(`SearXNG search error (${response.status}): ${detail || response.statusText}`);
+		}
+		const body = await readResponseText(response, { maxBytes: MAX_RESPONSE_BYTES });
+		if (body.truncated) throw new Error("SearXNG response too large.");
+		return parseSearxngResponseText(body.text, params.count);
+	});
+}
+async function runSearxngSearch(params) {
+	const count = resolveSearchCount(params.count, DEFAULT_SEARCH_COUNT);
+	const categories = params.categories ?? resolveSearxngCategories(params.config);
+	const language = params.language ?? resolveSearxngLanguage(params.config);
+	const baseUrl = params.baseUrl ?? resolveSearxngBaseUrl(params.config);
+	const timeoutSeconds = resolveTimeoutSeconds(params.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS);
+	const cacheTtlMs = resolveCacheTtlMs(params.cacheTtlMinutes, DEFAULT_CACHE_TTL_MINUTES);
+	if (!baseUrl) throw new Error("SearXNG base URL is not configured. Set SEARXNG_BASE_URL or configure plugins.entries.searxng.config.webSearch.baseUrl.");
+	const endpointMode = await validateSearxngBaseUrl(baseUrl);
+	const cacheKey = normalizeCacheKey(JSON.stringify({
+		provider: "searxng",
+		query: params.query,
+		count,
+		categories: categories ?? "",
+		language: language ?? "",
+		baseUrl
+	}));
+	const cached = readCache(SEARXNG_SEARCH_CACHE, cacheKey);
+	if (cached) return {
+		...cached.value,
+		cached: true
+	};
+	const startedAt = Date.now();
+	let results = await fetchSearxngResults({
+		baseUrl,
+		query: params.query,
+		categories,
+		language,
+		timeoutSeconds,
+		count,
+		endpointMode
+	});
+	if (results.length === 0 && shouldRetryEmptyCategorySearchWithGeneral(categories)) results = await fetchSearxngResults({
+		baseUrl,
+		query: params.query,
+		categories: "general",
+		language,
+		timeoutSeconds,
+		count,
+		endpointMode
+	});
+	const payload = {
+		query: params.query,
+		provider: "searxng",
+		count: results.length,
+		tookMs: Date.now() - startedAt,
+		externalContent: {
+			untrusted: true,
+			source: "web_search",
+			provider: "searxng",
+			wrapped: true
+		},
+		results: results.map((result) => ({
+			title: wrapWebContent(result.title, "web_search"),
+			url: result.url,
+			snippet: result.content ? wrapWebContent(result.content, "web_search") : "",
+			siteName: resolveSiteName(result.url) || void 0,
+			img_src: result.img_src || void 0
+		}))
+	};
+	writeCache(SEARXNG_SEARCH_CACHE, cacheKey, payload, cacheTtlMs);
+	return payload;
+}
+const testing = {
+	buildSearxngSearchUrl,
+	normalizeSearxngResult,
+	parseSearxngResponseText,
+	shouldRetryEmptyCategorySearchWithGeneral,
+	validateSearxngBaseUrl,
+	SEARXNG_SEARCH_CACHE
+};
+//#endregion
+export { testing as __testing, testing, runSearxngSearch };

package/dist/searxng-search-provider-Da4Go6Vh.js

@@ -0,0 +1,80 @@
+import { readPositiveIntegerParam, readStringParam } from "openclaw/plugin-sdk/param-readers";
+import { createWebSearchProviderContractFields } from "openclaw/plugin-sdk/provider-web-search-contract";
+//#region extensions/searxng/src/searxng-search-provider.ts
+const SEARXNG_CREDENTIAL_PATH = "plugins.entries.searxng.config.webSearch.baseUrl";
+let searxngClientModulePromise;
+function loadSearxngClientModule() {
+	searxngClientModulePromise ??= import("./searxng-client-BFVWmp9D.js");
+	return searxngClientModulePromise;
+}
+const SearxngSearchSchema = {
+	type: "object",
+	properties: {
+		query: {
+			type: "string",
+			description: "Search query string."
+		},
+		count: {
+			type: "integer",
+			description: "Number of results to return (1-10).",
+			minimum: 1,
+			maximum: 10
+		},
+		categories: {
+			type: "string",
+			description: "Optional comma-separated search categories such as general, news, or science."
+		},
+		language: {
+			type: "string",
+			description: "Optional language code for results such as en, de, or fr."
+		}
+	},
+	additionalProperties: false
+};
+function createSearxngWebSearchProvider() {
+	return {
+		id: "searxng",
+		label: "SearXNG Search",
+		hint: "Self-hosted meta-search with no API key required",
+		onboardingScopes: ["text-inference"],
+		requiresCredential: true,
+		credentialLabel: "SearXNG Base URL",
+		envVars: ["SEARXNG_BASE_URL"],
+		placeholder: "http://localhost:8080",
+		signupUrl: "https://docs.searxng.org/",
+		autoDetectOrder: 200,
+		credentialPath: SEARXNG_CREDENTIAL_PATH,
+		...createWebSearchProviderContractFields({
+			credentialPath: SEARXNG_CREDENTIAL_PATH,
+			searchCredential: {
+				type: "scoped",
+				scopeId: "searxng"
+			},
+			configuredCredential: {
+				pluginId: "searxng",
+				field: "baseUrl"
+			},
+			selectionPluginId: "searxng"
+		}),
+		credentialNote: ["For the SearXNG JSON API to work, make sure your SearXNG instance", "has the json format enabled in its settings.yml under search.formats."].join("\n"),
+		createTool: (ctx) => ({
+			description: "Search the web using a self-hosted SearXNG instance. Returns titles, URLs, and snippets.",
+			parameters: SearxngSearchSchema,
+			execute: async (args) => {
+				const { runSearxngSearch } = await loadSearxngClientModule();
+				return await runSearxngSearch({
+					config: ctx.config,
+					query: readStringParam(args, "query", { required: true }),
+					count: readPositiveIntegerParam(args, "count", {
+						max: 10,
+						message: "count must be an integer from 1 to 10."
+					}),
+					categories: readStringParam(args, "categories"),
+					language: readStringParam(args, "language")
+				});
+			}
+		})
+	};
+}
+//#endregion
+export { createSearxngWebSearchProvider as t };

package/dist/web-search-provider.js

@@ -0,0 +1,2 @@
+import { t as createSearxngWebSearchProvider } from "./searxng-search-provider-Da4Go6Vh.js";
+export { createSearxngWebSearchProvider };

package/npm-shrinkwrap.json

@@ -0,0 +1,12 @@
+{
+  "name": "@openclaw/searxng-plugin",
+  "version": "2026.6.11",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@openclaw/searxng-plugin",
+      "version": "2026.6.11"
+    }
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,45 @@
+{
+  "id": "searxng",
+  "icon": "https://cdn.simpleicons.org/searxng",
+  "activation": {
+    "onStartup": false
+  },
+  "uiHints": {
+    "webSearch.baseUrl": {
+      "label": "SearXNG Base URL",
+      "help": "Base URL of your SearXNG instance, such as http://localhost:8080 or https://search.example.com/searxng."
+    },
+    "webSearch.categories": {
+      "label": "SearXNG Categories",
+      "help": "Optional comma-separated categories such as general, news, or science."
+    },
+    "webSearch.language": {
+      "label": "SearXNG Language",
+      "help": "Optional language code for results such as en, de, or fr."
+    }
+  },
+  "contracts": {
+    "webSearchProviders": ["searxng"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "webSearch": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "baseUrl": {
+            "type": ["string", "object"]
+          },
+          "categories": {
+            "type": "string"
+          },
+          "language": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,13 +1,51 @@
 {
   "name": "@openclaw/searxng-plugin",
-  "version": "0.0.0",
-  "description": "Bootstrap reservation for the OpenClaw SearXNG plugin package.",
+  "version": "2026.6.11",
+  "description": "OpenClaw SearXNG plugin",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@openclaw/searxng-plugin",
+      "npmSpec": "@openclaw/searxng-plugin",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.6.9",
+      "allowInvalidConfigRecovery": true
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.11"
+    },
+    "build": {
+      "openclawVersion": "2026.6.11",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    },
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ]
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/openclaw/openclaw.git"
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "files": [
+    "dist/**",
+    "openclaw.plugin.json",
+    "npm-shrinkwrap.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.6.11"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
   },
-  "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
-  }
+  "bundledDependencies": []
 }