ocsmarttools 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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
+- Expanded auto-routing trigger intents in managed `AGENTS.md` policy to cover:
+  - research/evidence
+  - reporting/writing
+  - coding/engineering
+  - data/extraction
+  - risk/compliance
+- Expanded built-in `tool_search` keyword coverage across runtime, filesystem, web, browser, and session tools for broader intent matching.
+- Improved `tool_search` scoring tokenization so punctuation-heavy terms (for example `CI/CD`) match more reliably.
+
 ## [0.1.9] - 2026-02-22
 
 ### Changed

package/README.md

@@ -15,7 +15,9 @@ OCSmartTools helps reduce latency and token cost by routing multi-step work thro
   - `tool_result_get`
 - 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 tasks (no per-prompt guardrails needed)
+- 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,11 +98,26 @@ 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:
+- research/evidence (sources, benchmarks, case studies, latest/news)
+- reporting/writing (reports, briefs, proposals, plans, emails, docs/specs)
+- coding/engineering (build, debug, fix, test, refactor, deploy, migration)
+- data/extraction (scrape/fetch/parse/aggregate/rank/CSV/JSON/ETL)
+- risk/compliance (security/privacy/legal/audit requests)
+
 ## Skills and Blocked Sites
 
 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.9",
+  "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

@@ -6,6 +6,15 @@ import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk";
 const BLOCK_START = "<!-- OCSMARTTOOLS_ROUTING_START -->";
 const BLOCK_END = "<!-- OCSMARTTOOLS_ROUTING_END -->";
 
+const AUTO_TRIGGER_LINES = [
+  "Auto-route trigger intents (use routing tools by default when tools are needed):",
+  "- Research and evidence: research, investigate, analyze, benchmark, compare, evaluate, market intelligence, trends, latest, news, sources, citations, references, case study, due diligence.",
+  "- Reporting and writing: report, summary, brief, memo, presentation, plan, proposal, recommendation, email, RFC, PRD, specification, documentation, SOP.",
+  "- Coding and engineering: code, implement, build, website, app, script, debug, fix, bug, stack trace, test, lint, refactor, optimize, compile, deploy, CI/CD, migration, release notes.",
+  "- Data and extraction: scrape, crawl, fetch, parse, transform, aggregate, rank, classify, table, CSV, JSON, dataset, ETL.",
+  "- Risk and compliance: risk register, security review, privacy, legal, policy, SOC 2, GDPR, HIPAA, audit.",
+];
+
 function buildRoutingBlock(strictRouting: boolean): string {
   const body = strictRouting
     ? [
@@ -22,8 +31,12 @@ function buildRoutingBlock(strictRouting: boolean): string {
         "6. Avoid direct native tool calls unless routing tools are unavailable due to runtime/tool-policy constraints.",
         "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`.",
+        "",
+        ...AUTO_TRIGGER_LINES,
       ].join("\n")
     : [
         "## OCSmartTools Routing Policy (Auto-Managed)",
@@ -38,8 +51,12 @@ function buildRoutingBlock(strictRouting: boolean): string {
         "6. Use direct native tool calls only for simple one-shot small-output actions.",
         "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`.",
+        "",
+        ...AUTO_TRIGGER_LINES,
       ].join("\n");
 
   return `${BLOCK_START}

package/src/lib/tool-catalog.ts

@@ -9,34 +9,184 @@ export type ToolEntry = {
   source: "builtin" | "policy" | "live";
 };
 
+const RESEARCH_KEYWORDS = [
+  "research",
+  "investigate",
+  "analyze",
+  "analysis",
+  "benchmark",
+  "compare",
+  "evaluate",
+  "market intelligence",
+  "trend",
+  "latest",
+  "news",
+  "evidence",
+  "sources",
+  "citations",
+  "references",
+  "case study",
+  "due diligence",
+];
+
+const REPORT_KEYWORDS = [
+  "report",
+  "summary",
+  "brief",
+  "memo",
+  "recommendation",
+  "proposal",
+  "plan",
+  "writeup",
+  "presentation",
+  "email",
+  "documentation",
+  "spec",
+  "rfc",
+  "prd",
+];
+
+const CODING_KEYWORDS = [
+  "code",
+  "implement",
+  "build",
+  "website",
+  "app",
+  "script",
+  "debug",
+  "fix",
+  "bug",
+  "stack trace",
+  "test",
+  "lint",
+  "refactor",
+  "optimize",
+  "compile",
+  "deploy",
+  "ci",
+  "cd",
+  "migration",
+];
+
+const DATA_KEYWORDS = [
+  "extract",
+  "scrape",
+  "crawl",
+  "parse",
+  "transform",
+  "aggregate",
+  "rank",
+  "classify",
+  "csv",
+  "json",
+  "dataset",
+  "etl",
+  "table",
+];
+
+const BROWSER_KEYWORDS = [
+  "playwright",
+  "stealth",
+  "anti-bot",
+  "captcha",
+  "dynamic site",
+  "javascript page",
+  "login wall",
+  "rendered page",
+  "automation",
+];
+
 const BUILTIN: ToolEntry[] = [
   {
     name: "exec",
     group: "runtime",
     description: "Run shell commands.",
     paramsHint: "{ command }",
-    keywords: ["script", "python", "node", "playwright", "stealth", "scrape"],
+    keywords: [
+      "shell",
+      "terminal",
+      "command line",
+      "python",
+      "node",
+      "npm",
+      "git",
+      "build",
+      "run tests",
+      "start server",
+      ...CODING_KEYWORDS,
+      ...DATA_KEYWORDS,
+      ...BROWSER_KEYWORDS,
+    ],
+    source: "builtin",
+  },
+  {
+    name: "bash",
+    group: "runtime",
+    description: "Alias for exec in many contexts.",
+    paramsHint: "{ command }",
+    keywords: ["shell", "terminal", "script", ...CODING_KEYWORDS],
+    source: "builtin",
+  },
+  {
+    name: "process",
+    group: "runtime",
+    description: "Manage background command sessions.",
+    paramsHint: "{ action, sessionId? }",
+    keywords: ["long running", "background job", "watch logs", "daemon", "worker", "server process", "job status"],
+    source: "builtin",
+  },
+  {
+    name: "read",
+    group: "fs",
+    description: "Read files.",
+    paramsHint: "{ path }",
+    keywords: ["open file", "inspect file", "view logs", "read config", "read docs", "audit code", ...REPORT_KEYWORDS],
+    source: "builtin",
+  },
+  {
+    name: "write",
+    group: "fs",
+    description: "Write files.",
+    paramsHint: "{ path, content }",
+    keywords: ["create file", "save output", "generate report", "draft", "write docs", "export", ...REPORT_KEYWORDS],
+    source: "builtin",
+  },
+  {
+    name: "edit",
+    group: "fs",
+    description: "Patch file text by replacement.",
+    paramsHint: "{ path, oldText, newText }",
+    keywords: ["modify file", "update code", "refactor file", "fix snippet", ...CODING_KEYWORDS],
+    source: "builtin",
+  },
+  {
+    name: "apply_patch",
+    group: "fs",
+    description: "Apply unified-style file patch.",
+    paramsHint: "{ input }",
+    keywords: ["multi-file patch", "diff", "code patch", "batch edits", "surgical edit", ...CODING_KEYWORDS],
+    source: "builtin",
+  },
+  { name: "sessions_list", group: "sessions", description: "List sessions.", paramsHint: "{ ... }", keywords: ["session", "agents", "workers"], source: "builtin" },
+  { name: "sessions_history", group: "sessions", description: "Read session history.", paramsHint: "{ sessionKey? }", keywords: ["conversation history", "chat log", "audit trail"], source: "builtin" },
+  { name: "sessions_send", group: "sessions", description: "Send to another session.", paramsHint: "{ ... }", keywords: ["delegate", "handoff", "subtask"], source: "builtin" },
+  { name: "sessions_spawn", group: "sessions", description: "Spawn subagent session.", paramsHint: "{ prompt, ... }", keywords: ["spawn agent", "parallel agent", "subagent", "delegate"], source: "builtin" },
+  { name: "session_status", group: "sessions", description: "Show current session status.", paramsHint: "{}", keywords: ["status", "health", "progress"], source: "builtin" },
+  {
+    name: "memory_search",
+    group: "memory",
+    description: "Search memory snippets.",
+    paramsHint: "{ query }",
+    keywords: ["recall", "memory", "previous notes", "past decisions", "context lookup"],
     source: "builtin",
   },
-  { name: "bash", group: "runtime", description: "Alias for exec in many contexts.", paramsHint: "{ command }", source: "builtin" },
-  { name: "process", group: "runtime", description: "Manage background command sessions.", paramsHint: "{ action, sessionId? }", source: "builtin" },
-  { name: "read", group: "fs", description: "Read files.", paramsHint: "{ path }", source: "builtin" },
-  { name: "write", group: "fs", description: "Write files.", paramsHint: "{ path, content }", source: "builtin" },
-  { name: "edit", group: "fs", description: "Patch file text by replacement.", paramsHint: "{ path, oldText, newText }", source: "builtin" },
-  { name: "apply_patch", group: "fs", description: "Apply unified-style file patch.", paramsHint: "{ input }", source: "builtin" },
-  { name: "sessions_list", group: "sessions", description: "List sessions.", paramsHint: "{ ... }", source: "builtin" },
-  { name: "sessions_history", group: "sessions", description: "Read session history.", paramsHint: "{ sessionKey? }", source: "builtin" },
-  { name: "sessions_send", group: "sessions", description: "Send to another session.", paramsHint: "{ ... }", source: "builtin" },
-  { name: "sessions_spawn", group: "sessions", description: "Spawn subagent session.", paramsHint: "{ prompt, ... }", source: "builtin" },
-  { name: "session_status", group: "sessions", description: "Show current session status.", paramsHint: "{}", source: "builtin" },
-  { name: "memory_search", group: "memory", description: "Search memory snippets.", paramsHint: "{ query }", source: "builtin" },
-  { name: "memory_get", group: "memory", description: "Read memory entries.", paramsHint: "{ key }", source: "builtin" },
+  { name: "memory_get", group: "memory", description: "Read memory entries.", paramsHint: "{ key }", keywords: ["memory key", "stored context", "knowledge"], source: "builtin" },
   {
     name: "web_search",
     group: "web",
     description: "Search the web.",
     paramsHint: "{ query }",
-    keywords: ["research", "discover", "find"],
+    keywords: ["discover", "find", "lookup", ...RESEARCH_KEYWORDS, ...REPORT_KEYWORDS],
     source: "builtin",
   },
   {
@@ -44,7 +194,7 @@ const BUILTIN: ToolEntry[] = [
     group: "web",
     description: "Fetch and extract web page content.",
     paramsHint: "{ url }",
-    keywords: ["read page", "extract", "html"],
+    keywords: ["read page", "fetch url", "extract", "html", "article text", "content extraction", ...DATA_KEYWORDS, ...RESEARCH_KEYWORDS],
     source: "builtin",
   },
   {
@@ -52,14 +202,14 @@ const BUILTIN: ToolEntry[] = [
     group: "ui",
     description: "Browser automation.",
     paramsHint: "{ action, ... }",
-    keywords: ["playwright", "stealth", "anti-bot", "captcha", "dynamic site", "javascript page"],
+    keywords: [...BROWSER_KEYWORDS, "web navigation", "click", "form fill", "screenshot", "scrape dynamic"],
     source: "builtin",
   },
-  { name: "canvas", group: "ui", description: "Canvas/artifact rendering actions.", paramsHint: "{ action, ... }", source: "builtin" },
-  { name: "cron", group: "automation", description: "Manage scheduled jobs.", paramsHint: "{ action, ... }", source: "builtin" },
-  { name: "gateway", group: "automation", description: "Gateway control-plane actions.", paramsHint: "{ action, ... }", source: "builtin" },
-  { name: "message", group: "messaging", description: "Message actions across channels.", paramsHint: "{ action, ... }", source: "builtin" },
-  { name: "nodes", group: "nodes", description: "Invoke node-side capabilities.", paramsHint: "{ action, ... }", source: "builtin" },
+  { name: "canvas", group: "ui", description: "Canvas/artifact rendering actions.", paramsHint: "{ action, ... }", keywords: ["diagram", "visual", "chart", "artifact"], source: "builtin" },
+  { name: "cron", group: "automation", description: "Manage scheduled jobs.", paramsHint: "{ action, ... }", keywords: ["schedule", "recurring", "automation", "job timer"], source: "builtin" },
+  { name: "gateway", group: "automation", description: "Gateway control-plane actions.", paramsHint: "{ action, ... }", keywords: ["gateway control", "restart", "config patch", "service"], source: "builtin" },
+  { name: "message", group: "messaging", description: "Message actions across channels.", paramsHint: "{ action, ... }", keywords: ["notify", "chat", "post update", "send message"], source: "builtin" },
+  { name: "nodes", group: "nodes", description: "Invoke node-side capabilities.", paramsHint: "{ action, ... }", keywords: ["device", "camera", "screen", "location", "node action"], source: "builtin" },
 ];
 
 const GROUP_NAMES = new Set([
@@ -328,6 +478,10 @@ function score(query: string, entry: ToolEntry): number {
   const d = entry.description.toLowerCase();
   const g = entry.group.toLowerCase();
   const keywords = (entry.keywords ?? []).map((v) => v.toLowerCase());
+  const tokens = q
+    .split(/[^a-z0-9]+/)
+    .map((t) => t.trim())
+    .filter(Boolean);
 
   let s = 0;
   if (n === q) s += 100;
@@ -337,7 +491,7 @@ function score(query: string, entry: ToolEntry): number {
   if (d.includes(q)) s += 10;
   if (keywords.includes(q)) s += 25;
 
-  for (const token of q.split(/\s+/).filter(Boolean)) {
+  for (const token of tokens) {
     if (n.includes(token)) s += 12;
     if (d.includes(token)) s += 4;
     if (g.includes(token)) s += 4;

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({