ocsmarttools 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `ocsmarttools` are documented here.
 
+## [0.1.11] - 2026-02-22
+
+### Changed
+- Defaulted `strictRouting` to `true` for new installs/bootstrap paths.
+- Added blocked-site fallback path for `web_fetch` failures:
+  - detect anti-bot/rate-limit/access-denied failures
+  - attempt browser fallback (`start` -> `open`/`navigate` -> `snapshot`)
+  - return native-handoff guidance for browser/skill workflows if fallback fails
+- Added new config keys:
+  - `webFetchFallback.enabled`
+  - `webFetchFallback.browserTarget`
+  - `webFetchFallback.snapshotFormat`
+  - `webFetchFallback.snapshotLimit`
+- Updated routing policy to explicitly allow browser/skill-guided recovery on blocked pages.
+
 ## [0.1.10] - 2026-02-22
 
 ### Changed

package/README.md

@@ -16,6 +16,8 @@ OCSmartTools helps reduce latency and token cost by routing multi-step work thro
 - Built-in metrics for success/failure/timeout, latency, and estimated savings
 - Skill-compatible (including browser/Playwright-style workflows)
 - Auto-managed routing guidance for research/report/coding/data tasks (no per-prompt guardrails needed)
+- Strict routing is default-on for new installs
+- Auto fallback for blocked pages: `web_fetch` -> browser snapshot path
 
 ## Install
 
@@ -96,6 +98,12 @@ Example:
 - `safe`: requires sandbox and blocks control-plane dispatch
 - `strictRouting=true`: enforces plugin-managed routing guidance and keeps routing block synced
 
+Web fetch fallback defaults:
+- `webFetchFallback.enabled=true`
+- `webFetchFallback.browserTarget=auto`
+- `webFetchFallback.snapshotFormat=ai`
+- `webFetchFallback.snapshotLimit=12000`
+
 ## Auto Trigger Intents
 
 When tools are needed, routing is auto-biased toward `tool_dispatch` / `tool_batch` for these intent families:
@@ -109,7 +117,7 @@ When tools are needed, routing is auto-biased toward `tool_dispatch` / `tool_bat
 
 Skills in OpenClaw are instruction layers, not separate execution engines. OCSmartTools can still dispatch/batch the underlying tools used by skills.
 
-For websites that block plain fetch, use browser-based flows via installed skills/plugins; OCSmartTools can orchestrate those tool calls with the same metrics and shaping behavior.
+For websites that block plain fetch, OCSmartTools now tries browser fallback automatically. If that also fails, it returns a native-handoff recommendation so OpenClaw can continue with browser tools or skill-guided Playwright/stealth workflows.
 
 ## Safety Notes
 

package/openclaw.plugin.json

@@ -19,6 +19,16 @@
       "resultSampleItems": { "type": "integer", "minimum": 1, "maximum": 50 },
       "requireSandbox": { "type": "boolean" },
       "denyControlPlane": { "type": "boolean" },
+      "webFetchFallback": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "browserTarget": { "type": "string", "enum": ["auto", "sandbox", "host", "node"] },
+          "snapshotFormat": { "type": "string", "enum": ["ai", "aria"] },
+          "snapshotLimit": { "type": "integer", "minimum": 1000, "maximum": 50000 }
+        }
+      },
       "toolSearch": {
         "type": "object",
         "additionalProperties": false,
@@ -44,6 +54,10 @@
     "resultSampleItems": { "label": "Result Sample Items", "advanced": true },
     "requireSandbox": { "label": "Require Sandbox", "advanced": true },
     "denyControlPlane": { "label": "Deny Control Plane", "advanced": true },
+    "webFetchFallback.enabled": { "label": "Enable Web Fetch Fallback" },
+    "webFetchFallback.browserTarget": { "label": "Fallback Browser Target", "advanced": true },
+    "webFetchFallback.snapshotFormat": { "label": "Fallback Snapshot Format", "advanced": true },
+    "webFetchFallback.snapshotLimit": { "label": "Fallback Snapshot Limit", "advanced": true },
     "toolSearch.enabled": { "label": "Enable Tool Search" },
     "toolSearch.defaultLimit": { "label": "Tool Search Default Limit", "advanced": true },
     "toolSearch.useLiveRegistry": { "label": "Use Live Tool Registry", "advanced": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocsmarttools",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Provider-agnostic advanced tool orchestration plugin for OpenClaw with search, dispatch, and batching",
   "type": "module",
   "scripts": {

package/src/commands/operations.ts

@@ -32,6 +32,10 @@ const CONFIG_SPECS: Record<string, ConfigSpec> = {
   resultSampleItems: { kind: "integer", min: 1, max: 50 },
   requireSandbox: { kind: "boolean" },
   denyControlPlane: { kind: "boolean" },
+  "webFetchFallback.enabled": { kind: "boolean" },
+  "webFetchFallback.browserTarget": { kind: "enum", values: ["auto", "sandbox", "host", "node"] },
+  "webFetchFallback.snapshotFormat": { kind: "enum", values: ["ai", "aria"] },
+  "webFetchFallback.snapshotLimit": { kind: "integer", min: 1000, max: 50000 },
   "toolSearch.enabled": { kind: "boolean" },
   "toolSearch.defaultLimit": { kind: "integer", min: 1, max: 50 },
   "toolSearch.useLiveRegistry": { kind: "boolean" },
@@ -52,6 +56,10 @@ const DEFAULT_BY_KEY: Record<string, boolean | number | string> = {
   resultSampleItems: DEFAULT_SETTINGS.resultSampleItems,
   requireSandbox: DEFAULT_SETTINGS.requireSandbox,
   denyControlPlane: DEFAULT_SETTINGS.denyControlPlane,
+  "webFetchFallback.enabled": DEFAULT_SETTINGS.webFetchFallback.enabled,
+  "webFetchFallback.browserTarget": DEFAULT_SETTINGS.webFetchFallback.browserTarget,
+  "webFetchFallback.snapshotFormat": DEFAULT_SETTINGS.webFetchFallback.snapshotFormat,
+  "webFetchFallback.snapshotLimit": DEFAULT_SETTINGS.webFetchFallback.snapshotLimit,
   "toolSearch.enabled": DEFAULT_SETTINGS.toolSearch.enabled,
   "toolSearch.defaultLimit": DEFAULT_SETTINGS.toolSearch.defaultLimit,
   "toolSearch.useLiveRegistry": DEFAULT_SETTINGS.toolSearch.useLiveRegistry,
@@ -183,6 +191,8 @@ export function renderHelp(): string {
     "",
     "Quick examples:",
     "- /ocsmarttools status",
+    "- /ocsmarttools config set webFetchFallback.enabled true",
+    "- /ocsmarttools config set webFetchFallback.browserTarget auto",
     "- /ocsmarttools config set maxResultChars 120000",
     "- /ocsmarttools strict on",
     "- /ocsmarttools stats",
@@ -253,6 +263,10 @@ export function renderConfig(api: OpenClawPluginApi): string {
     `- resultSampleItems: ${s.resultSampleItems}`,
     `- requireSandbox: ${s.requireSandbox}`,
     `- denyControlPlane: ${s.denyControlPlane}`,
+    `- webFetchFallback.enabled: ${s.webFetchFallback.enabled}`,
+    `- webFetchFallback.browserTarget: ${s.webFetchFallback.browserTarget}`,
+    `- webFetchFallback.snapshotFormat: ${s.webFetchFallback.snapshotFormat}`,
+    `- webFetchFallback.snapshotLimit: ${s.webFetchFallback.snapshotLimit}`,
     `- toolSearch.enabled: ${s.toolSearch.enabled}`,
     `- toolSearch.defaultLimit: ${s.toolSearch.defaultLimit}`,
     `- toolSearch.useLiveRegistry: ${s.toolSearch.useLiveRegistry}`,
@@ -375,7 +389,7 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
 
   pluginCfg.enabled = true;
   pluginCfg.mode = mode;
-  pluginCfg.strictRouting = false;
+  pluginCfg.strictRouting = true;
   pluginCfg.autoInjectRoutingGuide = true;
   pluginCfg.maxSteps = DEFAULT_SETTINGS.maxSteps;
   pluginCfg.maxForEach = DEFAULT_SETTINGS.maxForEach;
@@ -386,6 +400,12 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   pluginCfg.resultSampleItems = DEFAULT_SETTINGS.resultSampleItems;
   pluginCfg.requireSandbox = mode === "safe";
   pluginCfg.denyControlPlane = true;
+  pluginCfg.webFetchFallback = {
+    enabled: DEFAULT_SETTINGS.webFetchFallback.enabled,
+    browserTarget: DEFAULT_SETTINGS.webFetchFallback.browserTarget,
+    snapshotFormat: DEFAULT_SETTINGS.webFetchFallback.snapshotFormat,
+    snapshotLimit: DEFAULT_SETTINGS.webFetchFallback.snapshotLimit,
+  };
   pluginCfg.toolSearch = {
     enabled: true,
     defaultLimit: DEFAULT_SETTINGS.toolSearch.defaultLimit,
@@ -401,7 +421,7 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   );
 
   await writeConfig(api, next);
-  const sync = await syncRoutingGuide(api, next, { strictRouting: false });
+  const sync = await syncRoutingGuide(api, next, { strictRouting: true });
   const syncLine = sync.error
     ? `- routing guide sync skipped: ${sync.error}`
     : `- routing guide ${sync.changed ? "synced" : "already up to date"} (${sync.filePath ?? "AGENTS.md"})`;
@@ -409,6 +429,7 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   return [
     "OCSmartTools setup applied.",
     `- mode: ${mode}`,
+    "- strictRouting: true",
     "- autoInjectRoutingGuide: true",
     syncLine,
     `- ensured tools.allow includes: ${ADVTOOLS_TOOL_NAMES.join(", ")}`,

package/src/lib/bootstrap.ts

@@ -57,6 +57,42 @@ export async function autoBootstrap(api: OpenClawPluginApi): Promise<{ changed:
   setDefault("resultSampleItems", DEFAULT_SETTINGS.resultSampleItems);
   setDefault("requireSandbox", DEFAULT_SETTINGS.requireSandbox);
   setDefault("denyControlPlane", DEFAULT_SETTINGS.denyControlPlane);
+  if (pluginCfg.webFetchFallback === undefined) {
+    pluginCfg.webFetchFallback = {
+      enabled: DEFAULT_SETTINGS.webFetchFallback.enabled,
+      browserTarget: DEFAULT_SETTINGS.webFetchFallback.browserTarget,
+      snapshotFormat: DEFAULT_SETTINGS.webFetchFallback.snapshotFormat,
+      snapshotLimit: DEFAULT_SETTINGS.webFetchFallback.snapshotLimit,
+    };
+    changed = true;
+    notes.push("set default webFetchFallback");
+  } else {
+    const wf = asObj(pluginCfg.webFetchFallback);
+    if (pluginCfg.webFetchFallback !== wf) {
+      pluginCfg.webFetchFallback = wf;
+      changed = true;
+    }
+    if (wf.enabled === undefined) {
+      wf.enabled = DEFAULT_SETTINGS.webFetchFallback.enabled;
+      changed = true;
+      notes.push("set default webFetchFallback.enabled");
+    }
+    if (wf.browserTarget === undefined) {
+      wf.browserTarget = DEFAULT_SETTINGS.webFetchFallback.browserTarget;
+      changed = true;
+      notes.push("set default webFetchFallback.browserTarget");
+    }
+    if (wf.snapshotFormat === undefined) {
+      wf.snapshotFormat = DEFAULT_SETTINGS.webFetchFallback.snapshotFormat;
+      changed = true;
+      notes.push("set default webFetchFallback.snapshotFormat");
+    }
+    if (wf.snapshotLimit === undefined) {
+      wf.snapshotLimit = DEFAULT_SETTINGS.webFetchFallback.snapshotLimit;
+      changed = true;
+      notes.push("set default webFetchFallback.snapshotLimit");
+    }
+  }
   if (pluginCfg.toolSearch === undefined) {
     pluginCfg.toolSearch = {
       enabled: DEFAULT_SETTINGS.toolSearch.enabled,

package/src/lib/plugin-config.ts

@@ -16,6 +16,12 @@ export type AdvToolsSettings = {
   resultSampleItems: number;
   requireSandbox: boolean;
   denyControlPlane: boolean;
+  webFetchFallback: {
+    enabled: boolean;
+    browserTarget: "auto" | "sandbox" | "host" | "node";
+    snapshotFormat: "ai" | "aria";
+    snapshotLimit: number;
+  };
   toolSearch: {
     enabled: boolean;
     defaultLimit: number;
@@ -27,7 +33,7 @@ export type AdvToolsSettings = {
 export const DEFAULT_SETTINGS: AdvToolsSettings = {
   enabled: true,
   mode: "standard",
-  strictRouting: false,
+  strictRouting: true,
   autoInjectRoutingGuide: true,
   maxSteps: 25,
   maxForEach: 20,
@@ -38,6 +44,12 @@ export const DEFAULT_SETTINGS: AdvToolsSettings = {
   resultSampleItems: 8,
   requireSandbox: false,
   denyControlPlane: true,
+  webFetchFallback: {
+    enabled: true,
+    browserTarget: "auto",
+    snapshotFormat: "ai",
+    snapshotLimit: 12000,
+  },
   toolSearch: {
     enabled: true,
     defaultLimit: 8,
@@ -67,12 +79,33 @@ function asMode(value: unknown, fallback: AdvToolsMode): AdvToolsMode {
   return value === "safe" || value === "standard" ? value : fallback;
 }
 
+function asBrowserTarget(
+  value: unknown,
+  fallback: AdvToolsSettings["webFetchFallback"]["browserTarget"],
+): AdvToolsSettings["webFetchFallback"]["browserTarget"] {
+  if (value === "auto" || value === "sandbox" || value === "host" || value === "node") {
+    return value;
+  }
+  return fallback;
+}
+
+function asSnapshotFormat(
+  value: unknown,
+  fallback: AdvToolsSettings["webFetchFallback"]["snapshotFormat"],
+): AdvToolsSettings["webFetchFallback"]["snapshotFormat"] {
+  if (value === "ai" || value === "aria") {
+    return value;
+  }
+  return fallback;
+}
+
 export function resolveSettings(api: OpenClawPluginApi, cfg: OpenClawConfig = api.config): AdvToolsSettings {
   const plugins = asObj((cfg as Record<string, unknown>).plugins);
   const entries = asObj(plugins.entries);
   const entry = asObj(entries[api.id]);
   const pluginCfg = asObj(entry.config ?? api.pluginConfig);
   const ts = asObj(pluginCfg.toolSearch);
+  const wf = asObj(pluginCfg.webFetchFallback);
 
   const strictRouting = asBool(pluginCfg.strictRouting, DEFAULT_SETTINGS.strictRouting);
   const autoInjectRoutingGuide = strictRouting
@@ -103,6 +136,23 @@ export function resolveSettings(api: OpenClawPluginApi, cfg: OpenClawConfig = ap
     ),
     requireSandbox: asBool(pluginCfg.requireSandbox, DEFAULT_SETTINGS.requireSandbox),
     denyControlPlane: asBool(pluginCfg.denyControlPlane, DEFAULT_SETTINGS.denyControlPlane),
+    webFetchFallback: {
+      enabled: asBool(wf.enabled, DEFAULT_SETTINGS.webFetchFallback.enabled),
+      browserTarget: asBrowserTarget(
+        wf.browserTarget,
+        DEFAULT_SETTINGS.webFetchFallback.browserTarget,
+      ),
+      snapshotFormat: asSnapshotFormat(
+        wf.snapshotFormat,
+        DEFAULT_SETTINGS.webFetchFallback.snapshotFormat,
+      ),
+      snapshotLimit: asInt(
+        wf.snapshotLimit,
+        DEFAULT_SETTINGS.webFetchFallback.snapshotLimit,
+        1000,
+        50000,
+      ),
+    },
     toolSearch: {
       enabled: asBool(ts.enabled, DEFAULT_SETTINGS.toolSearch.enabled),
       defaultLimit: asInt(ts.defaultLimit, DEFAULT_SETTINGS.toolSearch.defaultLimit, 1, 50),

package/src/lib/routing-guide.ts

@@ -32,6 +32,7 @@ function buildRoutingBlock(strictRouting: boolean): string {
         "7. Do not present citations/sources unless they came from successful tool calls in the current run.",
         "8. If required retrieval fails, return a clear partial/failure report instead of fabricated evidence.",
         "9. Treat trigger intents below as routing-required unless the request is clearly a no-tool task.",
+        "10. If `web_fetch` is blocked (anti-bot/captcha), prefer browser fallback; if fallback also fails, allow native browser/skill-guided flows (for example Playwright stealth skills).",
         "",
         "Common large/noisy tools: `web_fetch`, `read` (large files), `exec`, `process`, `browser`, `nodes`.",
         "",
@@ -51,6 +52,7 @@ function buildRoutingBlock(strictRouting: boolean): string {
         "7. Do not include citations/sources that were not retrieved by tools in the current run.",
         "8. If retrieval fails, explicitly report the gap.",
         "9. Treat trigger intents below as strong routing signals unless the task is clearly no-tool.",
+        "10. For blocked `web_fetch` pages, allow browser/skill-guided fallback paths.",
         "",
         "Common large/noisy tools: `web_fetch`, `read` (large files), `exec`, `process`, `browser`, `nodes`.",
         "",

package/src/lib/web-fetch-fallback.ts

@@ -0,0 +1,181 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { AdvToolsSettings } from "./plugin-config.js";
+import type { InvokeResult } from "./invoke.js";
+import { invokeToolViaGateway } from "./invoke.js";
+
+const BLOCKED_STATUSES = new Set([401, 403, 406, 409, 410, 412, 418, 425, 429, 451, 503]);
+const BLOCKED_HINTS = [
+  "access denied",
+  "forbidden",
+  "blocked",
+  "bot",
+  "captcha",
+  "cloudflare",
+  "challenge",
+  "javascript required",
+  "enable javascript",
+  "rate limit",
+  "too many requests",
+];
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function toLowerBlob(value: unknown): string {
+  try {
+    return JSON.stringify(value).toLowerCase();
+  } catch {
+    return String(value ?? "").toLowerCase();
+  }
+}
+
+function isLikelyBlockedFailure(result: InvokeResult): boolean {
+  if (BLOCKED_STATUSES.has(result.status)) {
+    return true;
+  }
+  const msg = `${result.error?.message ?? ""}\n${toLowerBlob(result.error?.details ?? "")}`.toLowerCase();
+  return BLOCKED_HINTS.some((hint) => msg.includes(hint));
+}
+
+function withBrowserTarget(
+  args: Record<string, unknown>,
+  target: AdvToolsSettings["webFetchFallback"]["browserTarget"],
+): Record<string, unknown> {
+  if (target === "auto") {
+    return args;
+  }
+  return { ...args, target };
+}
+
+type BrowserFallbackAttempt = {
+  attempted: true;
+  ok: boolean;
+  status: number;
+  latencyMs: number;
+  error?: InvokeResult["error"];
+  result?: unknown;
+};
+
+export type WebFetchFallbackResult =
+  | { attempted: false }
+  | ({
+      strategy: "web_fetch_browser_snapshot_v1";
+      primaryStatus: number;
+      url: string;
+      nativeHandoffRecommended: boolean;
+      nativeHandoffReason: string;
+    } & BrowserFallbackAttempt);
+
+type AttemptParams = {
+  cfg: OpenClawConfig;
+  settings: AdvToolsSettings;
+  toolName: string;
+  args: Record<string, unknown>;
+  primary: InvokeResult;
+  sessionKey?: string;
+  channel?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+};
+
+export async function maybeAttemptWebFetchFallback(params: AttemptParams): Promise<WebFetchFallbackResult> {
+  const { settings, toolName, args, primary } = params;
+  if (!settings.webFetchFallback.enabled || toolName !== "web_fetch" || primary.ok) {
+    return { attempted: false };
+  }
+
+  const url = typeof args.url === "string" ? args.url.trim() : "";
+  if (!url || !isLikelyBlockedFailure(primary)) {
+    return { attempted: false };
+  }
+
+  const startedAt = Date.now();
+  const browserTarget = settings.webFetchFallback.browserTarget;
+  const invokeCommon = {
+    sessionKey: params.sessionKey,
+    channel: params.channel,
+    accountId: params.accountId,
+    timeoutMs: params.timeoutMs,
+    signal: params.signal,
+  };
+
+  // Best-effort start; failures are tolerated because browser may already be running.
+  await invokeToolViaGateway(params.cfg, {
+    tool: "browser",
+    action: "start",
+    args: withBrowserTarget({}, browserTarget),
+    ...invokeCommon,
+  });
+
+  const open = await invokeToolViaGateway(params.cfg, {
+    tool: "browser",
+    action: "open",
+    args: withBrowserTarget({ url }, browserTarget),
+    ...invokeCommon,
+  });
+
+  if (!open.ok) {
+    // Retry via navigate in case the browser is up but open action is not supported by runtime/profile.
+    await invokeToolViaGateway(params.cfg, {
+      tool: "browser",
+      action: "navigate",
+      args: withBrowserTarget({ url }, browserTarget),
+      ...invokeCommon,
+    });
+  }
+
+  const snapshot = await invokeToolViaGateway(params.cfg, {
+    tool: "browser",
+    action: "snapshot",
+    args: withBrowserTarget(
+      {
+        format: settings.webFetchFallback.snapshotFormat,
+        limit: settings.webFetchFallback.snapshotLimit,
+      },
+      browserTarget,
+    ),
+    ...invokeCommon,
+  });
+
+  if (!snapshot.ok) {
+    return {
+      attempted: true,
+      ok: false,
+      status: snapshot.status,
+      latencyMs: Date.now() - startedAt,
+      strategy: "web_fetch_browser_snapshot_v1",
+      primaryStatus: primary.status,
+      url,
+      error: snapshot.error,
+      nativeHandoffRecommended: true,
+      nativeHandoffReason:
+        "Browser fallback failed. Allow native browser calls or skill-guided Playwright/stealth workflow.",
+    };
+  }
+
+  const snapshotObj = asObj(snapshot.result);
+  return {
+    attempted: true,
+    ok: true,
+    status: snapshot.status,
+    latencyMs: Date.now() - startedAt,
+    strategy: "web_fetch_browser_snapshot_v1",
+    primaryStatus: primary.status,
+    url,
+    nativeHandoffRecommended: false,
+    nativeHandoffReason: "",
+    result: {
+      url,
+      fallback: {
+        strategy: "web_fetch_blocked_to_browser_snapshot",
+        primaryStatus: primary.status,
+        primaryError: primary.error,
+      },
+      browserSnapshot: snapshotObj,
+    },
+  };
+}

package/src/tools/tool-batch.ts

@@ -1,4 +1,4 @@
-import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { AnyAgentTool, OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { jsonResult } from "openclaw/plugin-sdk";
 import { resolveSettings } from "../lib/plugin-config.js";
 import { invokeToolViaGateway } from "../lib/invoke.js";
@@ -6,6 +6,7 @@ import type { ResultStore } from "../lib/result-store.js";
 import { shapeToolResult } from "../lib/result-shaper.js";
 import { resolveValueTemplates } from "../lib/refs.js";
 import type { MetricsStore } from "../lib/metrics-store.js";
+import { maybeAttemptWebFetchFallback } from "../lib/web-fetch-fallback.js";
 
 const CONTROL_PLANE = new Set(["gateway", "cron"]);
 
@@ -82,7 +83,7 @@ function parseSteps(raw: unknown): BatchStep[] {
 
 async function runCall(params: {
   api: OpenClawPluginApi;
-  config: Record<string, unknown>;
+  config: OpenClawConfig;
   settings: ReturnType<typeof resolveSettings>;
   step: BatchStepCall;
   context: Record<string, unknown>;
@@ -159,6 +160,48 @@ async function runCall(params: {
       outcome: invoke.error?.type === "timeout" ? "timeout" : "failure",
       latencyMs: invoke.latencyMs,
     });
+
+    const fallback = await maybeAttemptWebFetchFallback({
+      cfg: config,
+      settings,
+      toolName,
+      args,
+      primary: invoke,
+      sessionKey,
+      channel,
+      accountId,
+      timeoutMs,
+      signal: params.signal,
+    });
+    if (fallback.attempted) {
+      params.metrics?.record({
+        tool: "browser",
+        outcome: fallback.ok ? "success" : "failure",
+        latencyMs: fallback.latencyMs,
+      });
+      if (fallback.ok) {
+        const shaped = shapeToolResult({
+          toolName: "browser",
+          value: fallback.result,
+          settings,
+          store: params.store,
+        });
+        return {
+          ok: true,
+          status: fallback.status,
+          tool: toolName,
+          fallbackUsed: "browser",
+          result: shaped,
+        };
+      }
+      return {
+        ok: false,
+        status: invoke.status,
+        tool: toolName,
+        error: invoke.error,
+        fallback,
+      };
+    }
     return {
       ok: false,
       status: invoke.status,

package/src/tools/tool-dispatch.ts

@@ -5,6 +5,7 @@ import { invokeToolViaGateway } from "../lib/invoke.js";
 import type { ResultStore } from "../lib/result-store.js";
 import { shapeToolResult } from "../lib/result-shaper.js";
 import type { MetricsStore } from "../lib/metrics-store.js";
+import { maybeAttemptWebFetchFallback } from "../lib/web-fetch-fallback.js";
 
 const CONTROL_PLANE = new Set(["gateway", "cron"]);
 const INTERNAL_LOOP_TOOLS = new Set(["tool_dispatch", "tool_batch"]);
@@ -122,11 +123,50 @@ export function createToolDispatchTool(
           outcome: result.error?.type === "timeout" ? "timeout" : "failure",
           latencyMs: result.latencyMs,
         });
-        return jsonResult({
-          ok: false,
-          status: result.status,
-          error: result.error,
+
+        const fallback = await maybeAttemptWebFetchFallback({
+          cfg: loaded,
+          settings,
+          toolName,
+          args: safeArgs as Record<string, unknown>,
+          primary: result,
+          sessionKey,
+          channel,
+          accountId,
+          timeoutMs: requestedTimeoutMs,
+          signal: signal as AbortSignal | undefined,
         });
+
+        if (fallback.attempted) {
+          options?.metrics?.record({
+            tool: "browser",
+            outcome: fallback.ok ? "success" : "failure",
+            latencyMs: fallback.latencyMs,
+          });
+          if (fallback.ok) {
+            const shaped = shapeToolResult({
+              toolName: "browser",
+              value: fallback.result,
+              settings,
+              store: options?.store,
+            });
+            return jsonResult({
+              ok: true,
+              status: fallback.status,
+              tool: toolName,
+              fallbackUsed: "browser",
+              result: shaped,
+            });
+          }
+          return jsonResult({
+            ok: false,
+            status: result.status,
+            error: result.error,
+            fallback,
+          });
+        }
+
+        return jsonResult({ ok: false, status: result.status, error: result.error });
       }
 
       const shaped = shapeToolResult({