feat: add web tools

2026-01-15 04:07:29 +00:00
parent 31d3aef8d6
commit f275cc180b
18 changed files with 736 additions and 165 deletions
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -0,0 +1,103 @@
+---
+summary: "Web search + fetch tools (Brave Search API)"
+read_when:
+  - You want to enable web_search or web_fetch
+  - You need Brave Search API key setup
+---
+
+# Web tools
+
+Clawdbot ships two lightweight web tools:
+
+- `web_search` — Brave Search API queries (fast, structured results).
+- `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).
+
+These are **not** browser automation. For JS-heavy sites or logins, use the
+[Browser tool](/tools/browser).
+
+## How it works
+
+- `web_search` calls Brave’s Search API and returns structured results
+  (title, URL, snippet). No browser is involved.
+- Results are cached by query for 15 minutes (configurable).
+- `web_fetch` does a plain HTTP GET and extracts readable content
+  (HTML → markdown/text). It does **not** execute JavaScript.
+- In sandboxed sessions, `web_fetch` is enabled automatically (unless explicitly disabled).
+
+## web_search
+
+Search the web with Brave’s API.
+
+### Requirements
+
+- `tools.web.search.enabled: true`
+- Brave API key via `BRAVE_API_KEY` **or** `tools.web.search.apiKey`
+
+### Config
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        apiKey: "BRAVE_API_KEY_HERE", // optional if BRAVE_API_KEY is set
+        maxResults: 5,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15
+      }
+    }
+  }
+}
+```
+
+### Tool parameters
+
+- `query` (required)
+- `count` (1–10; default from config)
+
+## web_fetch
+
+Fetch a URL and extract readable content.
+
+### Requirements
+
+- `tools.web.fetch.enabled: true`
+
+### Config
+
+```json5
+{
+  tools: {
+    web: {
+      fetch: {
+        enabled: true,
+        maxChars: 50000,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+        userAgent: "clawdbot/2026.1.14"
+      }
+    }
+  }
+}
+```
+
+### Tool parameters
+
+- `url` (required, http/https only)
+- `extractMode` (`markdown` | `text`)
+- `maxChars` (truncate long pages)
+
+Notes:
+- `web_fetch` is best-effort extraction; some sites will need the browser tool.
+- Responses are cached (default 15 minutes) to reduce repeated fetches.
+- If you use tool profiles/allowlists, add `web_search`/`web_fetch` or `group:web`.
+
+## Getting a Brave API key
+
+1) Create a Brave Search API account at https://brave.com/search/api/
+2) Generate an API key in the dashboard.
+3) Set `BRAVE_API_KEY` in your environment or paste it into `tools.web.search.apiKey`.
+
+Brave provides a free tier plus paid plans; check the Brave API portal for the
+current limits and pricing.