@openclaw/brave-plugin 2026.5.1-beta.1 → 2026.5.2-beta.1

package/openclaw.plugin.json

@@ -16,6 +16,10 @@
     "webSearch.mode": {
       "label": "Brave Search Mode",
       "help": "Brave Search mode: web or llm-context."
+    },
+    "webSearch.baseUrl": {
+      "label": "Brave Search Base URL",
+      "help": "Optional Brave-compatible API base URL for trusted proxies. Defaults to https://api.search.brave.com."
     }
   },
   "contracts": {
@@ -38,6 +42,9 @@
           "mode": {
             "type": "string",
             "enum": ["web", "llm-context"]
+          },
+          "baseUrl": {
+            "type": ["string", "object"]
           }
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/brave-plugin",
-  "version": "2026.5.1-beta.1",
+  "version": "2026.5.2-beta.1",
   "description": "OpenClaw Brave plugin",
   "repository": {
     "type": "git",
@@ -20,10 +20,10 @@
       "minHostVersion": ">=2026.4.10"
     },
     "compat": {
-      "pluginApi": ">=2026.4.10"
+      "pluginApi": ">=2026.5.2-beta.1"
     },
     "build": {
-      "openclawVersion": "2026.5.1-beta.1"
+      "openclawVersion": "2026.5.2-beta.1"
     },
     "release": {
       "publishToClawHub": true,

package/src/brave-web-search-provider.runtime.ts

@@ -14,10 +14,18 @@ import {
   resolveSearchCount,
   resolveSearchTimeoutSeconds,
   resolveSiteName,
+  withSelfHostedWebSearchEndpoint,
   withTrustedWebSearchEndpoint,
   wrapWebContent,
   writeCachedSearchPayload,
 } from "openclaw/plugin-sdk/provider-web-search";
+import { createSubsystemLogger } from "openclaw/plugin-sdk/runtime-env";
+import {
+  assertHttpUrlTargetsPrivateNetwork,
+  isBlockedHostnameOrIp,
+  isPrivateIpAddress,
+  resolvePinnedHostnameWithPolicy,
+} from "openclaw/plugin-sdk/ssrf-runtime";
 import {
   type BraveLlmContextResponse,
   mapBraveLlmContextResults,
@@ -27,8 +35,11 @@ import {
   resolveBraveMode,
 } from "./brave-web-search-provider.shared.js";
 
-const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
-const BRAVE_LLM_CONTEXT_ENDPOINT = "https://api.search.brave.com/res/v1/llm/context";
+const DEFAULT_BRAVE_BASE_URL = "https://api.search.brave.com";
+const BRAVE_SEARCH_ENDPOINT_PATH = "/res/v1/web/search";
+const BRAVE_LLM_CONTEXT_ENDPOINT_PATH = "/res/v1/llm/context";
+const braveHttpLogger = createSubsystemLogger("brave/http");
+type BraveEndpointMode = "selfHosted" | "strict";
 
 type BraveSearchResult = {
   title?: string;
@@ -43,6 +54,33 @@ type BraveSearchResponse = {
   };
 };
 
+type BraveHttpDiagnostics = {
+  enabled?: boolean;
+};
+
+function logBraveHttp(
+  diagnostics: BraveHttpDiagnostics | undefined,
+  event: string,
+  meta?: Record<string, unknown>,
+): void {
+  if (!diagnostics?.enabled) {
+    return;
+  }
+  braveHttpLogger.info(`brave http ${event}`, meta);
+}
+
+function describeBraveRequestUrl(url: URL): {
+  url: string;
+  query: string;
+  params: Record<string, string>;
+} {
+  return {
+    url: url.toString(),
+    query: url.searchParams.get("q") ?? "",
+    params: Object.fromEntries(url.searchParams.entries()),
+  };
+}
+
 function resolveBraveApiKey(searchConfig?: SearchConfigRecord): string | undefined {
   return (
     readConfiguredSecretString(searchConfig?.apiKey, "tools.web.search.apiKey") ??
@@ -50,21 +88,83 @@ function resolveBraveApiKey(searchConfig?: SearchConfigRecord): string | undefin
   );
 }
 
+function resolveBraveBaseUrl(braveConfig: { baseUrl?: unknown } | undefined): string {
+  const configured = readConfiguredSecretString(
+    braveConfig?.baseUrl,
+    "plugins.entries.brave.config.webSearch.baseUrl",
+  );
+  return configured?.replace(/\/+$/u, "") || DEFAULT_BRAVE_BASE_URL;
+}
+
+function buildBraveEndpointUrl(params: { baseUrl: string; endpointPath: string }): URL {
+  const url = new URL(params.baseUrl);
+  const basePath = url.pathname.replace(/\/+$/u, "");
+  url.pathname = `${basePath}${params.endpointPath}`;
+  url.search = "";
+  return url;
+}
+
+async function braveEndpointTargetsPrivateNetwork(url: URL): Promise<boolean> {
+  if (isBlockedHostnameOrIp(url.hostname)) {
+    return true;
+  }
+  try {
+    const pinned = await resolvePinnedHostnameWithPolicy(url.hostname, {
+      policy: {
+        allowPrivateNetwork: true,
+        allowRfc2544BenchmarkRange: true,
+      },
+    });
+    return pinned.addresses.every((address) => isPrivateIpAddress(address));
+  } catch {
+    return false;
+  }
+}
+
+async function validateBraveBaseUrl(baseUrl: string): Promise<BraveEndpointMode> {
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new Error("Brave Search base URL must be a valid http:// or https:// URL.");
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Brave Search base URL must use http:// or https://.");
+  }
+
+  if (parsed.protocol === "http:") {
+    await assertHttpUrlTargetsPrivateNetwork(parsed.toString(), {
+      dangerouslyAllowPrivateNetwork: true,
+      errorMessage:
+        "Brave Search HTTP base URL must target a trusted private or loopback host. Use https:// for public hosts.",
+    });
+    return "selfHosted";
+  }
+
+  return (await braveEndpointTargetsPrivateNetwork(parsed)) ? "selfHosted" : "strict";
+}
+
 function missingBraveKeyPayload() {
   return {
     error: "missing_brave_api_key",
-    message: `web_search (brave) needs a Brave Search API key. Run \`${formatCliCommand("openclaw configure --section web")}\` to store it, or set BRAVE_API_KEY in the Gateway environment.`,
+    message: `web_search (brave) needs a Brave Search API key. Run \`${formatCliCommand("openclaw configure --section web")}\` to store it, or set BRAVE_API_KEY in the Gateway environment. If you do not want to configure a search API key, use web_fetch for a specific URL or the browser tool for interactive pages.`,
     docs: "https://docs.openclaw.ai/tools/web",
   };
 }
 
 async function runBraveLlmContextSearch(params: {
+  baseUrl: string;
+  endpointMode: BraveEndpointMode;
   query: string;
   apiKey: string;
   timeoutSeconds: number;
+  diagnostics?: BraveHttpDiagnostics;
   country?: string;
   search_lang?: string;
   freshness?: string;
+  dateAfter?: string;
+  dateBefore?: string;
 }): Promise<{
   results: Array<{
     url: string;
@@ -74,7 +174,10 @@ async function runBraveLlmContextSearch(params: {
   }>;
   sources?: BraveLlmContextResponse["sources"];
 }> {
-  const url = new URL(BRAVE_LLM_CONTEXT_ENDPOINT);
+  const url = buildBraveEndpointUrl({
+    baseUrl: params.baseUrl,
+    endpointPath: BRAVE_LLM_CONTEXT_ENDPOINT_PATH,
+  });
   url.searchParams.set("q", params.query);
   if (params.country) {
     url.searchParams.set("country", params.country);
@@ -84,9 +187,25 @@ async function runBraveLlmContextSearch(params: {
   }
   if (params.freshness) {
     url.searchParams.set("freshness", params.freshness);
+  } else if (params.dateAfter && params.dateBefore) {
+    url.searchParams.set("freshness", `${params.dateAfter}to${params.dateBefore}`);
+  } else if (params.dateAfter) {
+    url.searchParams.set(
+      "freshness",
+      `${params.dateAfter}to${new Date().toISOString().slice(0, 10)}`,
+    );
   }
 
-  return withTrustedWebSearchEndpoint(
+  logBraveHttp(params.diagnostics, "request", {
+    mode: "llm-context",
+    ...describeBraveRequestUrl(url),
+  });
+  const startedAt = Date.now();
+  const withEndpoint =
+    params.endpointMode === "selfHosted"
+      ? withSelfHostedWebSearchEndpoint
+      : withTrustedWebSearchEndpoint;
+  return withEndpoint(
     {
       url: url.toString(),
       timeoutSeconds: params.timeoutSeconds,
@@ -99,6 +218,12 @@ async function runBraveLlmContextSearch(params: {
       },
     },
     async (response) => {
+      logBraveHttp(params.diagnostics, "response", {
+        mode: "llm-context",
+        status: response.status,
+        ok: response.ok,
+        durationMs: Date.now() - startedAt,
+      });
       if (!response.ok) {
         const detail = await response.text();
         throw new Error(
@@ -113,10 +238,13 @@ async function runBraveLlmContextSearch(params: {
 }
 
 async function runBraveWebSearch(params: {
+  baseUrl: string;
+  endpointMode: BraveEndpointMode;
   query: string;
   count: number;
   apiKey: string;
   timeoutSeconds: number;
+  diagnostics?: BraveHttpDiagnostics;
   country?: string;
   search_lang?: string;
   ui_lang?: string;
@@ -124,7 +252,10 @@ async function runBraveWebSearch(params: {
   dateAfter?: string;
   dateBefore?: string;
 }): Promise<Array<Record<string, unknown>>> {
-  const url = new URL(BRAVE_SEARCH_ENDPOINT);
+  const url = buildBraveEndpointUrl({
+    baseUrl: params.baseUrl,
+    endpointPath: BRAVE_SEARCH_ENDPOINT_PATH,
+  });
   url.searchParams.set("q", params.query);
   url.searchParams.set("count", String(params.count));
   if (params.country) {
@@ -149,7 +280,16 @@ async function runBraveWebSearch(params: {
     url.searchParams.set("freshness", `1970-01-01to${params.dateBefore}`);
   }
 
-  return withTrustedWebSearchEndpoint(
+  logBraveHttp(params.diagnostics, "request", {
+    mode: "web",
+    ...describeBraveRequestUrl(url),
+  });
+  const startedAt = Date.now();
+  const withEndpoint =
+    params.endpointMode === "selfHosted"
+      ? withSelfHostedWebSearchEndpoint
+      : withTrustedWebSearchEndpoint;
+  return withEndpoint(
     {
       url: url.toString(),
       timeoutSeconds: params.timeoutSeconds,
@@ -162,6 +302,12 @@ async function runBraveWebSearch(params: {
       },
     },
     async (response) => {
+      logBraveHttp(params.diagnostics, "response", {
+        mode: "web",
+        status: response.status,
+        ok: response.ok,
+        durationMs: Date.now() - startedAt,
+      });
       if (!response.ok) {
         const detail = await response.text();
         throw new Error(
@@ -190,6 +336,9 @@ async function runBraveWebSearch(params: {
 export async function executeBraveSearch(
   args: Record<string, unknown>,
   searchConfig?: SearchConfigRecord,
+  options?: {
+    diagnosticsEnabled?: boolean;
+  },
 ): Promise<Record<string, unknown>> {
   const apiKey = resolveBraveApiKey(searchConfig);
   if (!apiKey) {
@@ -198,6 +347,8 @@ export async function executeBraveSearch(
 
   const braveConfig = resolveBraveConfig(searchConfig);
   const braveMode = resolveBraveMode(braveConfig);
+  const braveBaseUrl = resolveBraveBaseUrl(braveConfig);
+  const braveEndpointMode = await validateBraveBaseUrl(braveBaseUrl);
   const query = readStringParam(args, "query", { required: true });
   const count =
     readNumberParam(args, "count", { integer: true }) ?? searchConfig?.maxResults ?? undefined;
@@ -235,14 +386,6 @@ export async function executeBraveSearch(
   }
 
   const rawFreshness = readStringParam(args, "freshness");
-  if (rawFreshness && braveMode === "llm-context") {
-    return {
-      error: "unsupported_freshness",
-      message:
-        "freshness filtering is not supported by Brave llm-context mode. Remove freshness or use Brave web mode.",
-      docs: "https://docs.openclaw.ai/tools/web",
-    };
-  }
   const freshness = rawFreshness ? normalizeFreshness(rawFreshness, "brave") : undefined;
   if (rawFreshness && !freshness) {
     return {
@@ -262,15 +405,6 @@ export async function executeBraveSearch(
       docs: "https://docs.openclaw.ai/tools/web",
     };
   }
-  if ((rawDateAfter || rawDateBefore) && braveMode === "llm-context") {
-    return {
-      error: "unsupported_date_filter",
-      message:
-        "date_after/date_before filtering is not supported by Brave llm-context mode. Use Brave web mode for date filters.",
-      docs: "https://docs.openclaw.ai/tools/web",
-    };
-  }
-
   const parsedDateRange = parseIsoDateRange({
     rawDateAfter,
     rawDateBefore,
@@ -283,22 +417,62 @@ export async function executeBraveSearch(
   }
 
   const { dateAfter, dateBefore } = parsedDateRange;
-  const cacheKey = buildSearchCacheKey([
-    "brave",
-    braveMode,
-    query,
-    resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
-    country,
-    normalizedLanguage.search_lang,
-    normalizedLanguage.ui_lang,
-    freshness,
-    dateAfter,
-    dateBefore,
-  ]);
+  if (braveMode === "llm-context") {
+    const today = new Date().toISOString().slice(0, 10);
+    if (dateAfter && !dateBefore && dateAfter > today) {
+      return {
+        error: "invalid_date_range",
+        message: "date_after cannot be in the future for Brave llm-context mode.",
+        docs: "https://docs.openclaw.ai/tools/web",
+      };
+    }
+    if (dateBefore && !dateAfter) {
+      return {
+        error: "unsupported_date_filter",
+        message:
+          "Brave llm-context mode requires date_after when date_before is set. Use a bounded date range or freshness.",
+        docs: "https://docs.openclaw.ai/tools/web",
+      };
+    }
+  }
+  const llmContextDateEnd =
+    braveMode === "llm-context" && dateAfter
+      ? (dateBefore ?? new Date().toISOString().slice(0, 10))
+      : dateBefore;
+  const cacheKey = buildSearchCacheKey(
+    braveMode === "llm-context"
+      ? [
+          "brave",
+          braveMode,
+          braveBaseUrl,
+          query,
+          country,
+          normalizedLanguage.search_lang,
+          freshness,
+          dateAfter,
+          llmContextDateEnd,
+        ]
+      : [
+          "brave",
+          braveMode,
+          braveBaseUrl,
+          query,
+          resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
+          country,
+          normalizedLanguage.search_lang,
+          normalizedLanguage.ui_lang,
+          freshness,
+          dateAfter,
+          dateBefore,
+        ],
+  );
+  const diagnostics: BraveHttpDiagnostics = { enabled: options?.diagnosticsEnabled === true };
   const cached = readCachedSearchPayload(cacheKey);
   if (cached) {
+    logBraveHttp(diagnostics, "cache hit", { mode: braveMode, query, cacheKey });
     return cached;
   }
+  logBraveHttp(diagnostics, "cache miss", { mode: braveMode, query, cacheKey });
 
   const start = Date.now();
   const timeoutSeconds = resolveSearchTimeoutSeconds(searchConfig);
@@ -306,12 +480,17 @@ export async function executeBraveSearch(
 
   if (braveMode === "llm-context") {
     const { results, sources } = await runBraveLlmContextSearch({
+      baseUrl: braveBaseUrl,
+      endpointMode: braveEndpointMode,
       query,
       apiKey,
       timeoutSeconds,
+      diagnostics,
       country: country ?? undefined,
       search_lang: normalizedLanguage.search_lang,
       freshness,
+      dateAfter,
+      dateBefore,
     });
     const payload = {
       query,
@@ -334,14 +513,24 @@ export async function executeBraveSearch(
       sources,
     };
     writeCachedSearchPayload(cacheKey, payload, cacheTtlMs);
+    logBraveHttp(diagnostics, "cache write", {
+      mode: "llm-context",
+      query,
+      cacheKey,
+      ttlMs: cacheTtlMs,
+      count: results.length,
+    });
     return payload;
   }
 
   const results = await runBraveWebSearch({
+    baseUrl: braveBaseUrl,
+    endpointMode: braveEndpointMode,
     query,
     count: resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
     apiKey,
     timeoutSeconds,
+    diagnostics,
     country: country ?? undefined,
     search_lang: normalizedLanguage.search_lang,
     ui_lang: normalizedLanguage.ui_lang,
@@ -363,5 +552,12 @@ export async function executeBraveSearch(
     results,
   };
   writeCachedSearchPayload(cacheKey, payload, cacheTtlMs);
+  logBraveHttp(diagnostics, "cache write", {
+    mode: "web",
+    query,
+    cacheKey,
+    ttlMs: cacheTtlMs,
+    count: results.length,
+  });
   return payload;
 }

package/src/brave-web-search-provider.shared.ts

@@ -4,6 +4,7 @@ import {
 } from "openclaw/plugin-sdk/text-runtime";
 
 type BraveConfig = {
+  baseUrl?: unknown;
   mode?: string;
 };