From 1533868680a1e10ccdc8e6dffe9dbc32959b8c4c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 04:15:24 +0000
Subject: [PATCH] docs: add web search FAQ

---
 docs/start/faq.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/start/faq.md b/docs/start/faq.md
index b284514b3..72687a9b5 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -50,6 +50,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [I set `gateway.bind: "lan"` (or `"tailnet"`) and now nothing listens / the UI says unauthorized](#i-set-gatewaybind-lan-or-tailnet-and-now-nothing-listens-the-ui-says-unauthorized)
   - [Why do I need a token on localhost now?](#why-do-i-need-a-token-on-localhost-now)
   - [Do I have to restart after changing config?](#do-i-have-to-restart-after-changing-config)
+  - [How do I enable web search (and web fetch)?](#how-do-i-enable-web-search-and-web-fetch)
   - [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices)
   - [Can the Clawdbot browser run headless?](#can-the-clawdbot-browser-run-headless)
 - [Remote gateways + nodes](#remote-gateways-nodes)
@@ -558,6 +559,34 @@ The Gateway watches the config and supports hot‑reload:
 - `gateway.reload.mode: "hybrid"` (default): hot‑apply safe changes, restart for critical ones
 - `hot`, `restart`, `off` are also supported
 
+### How do I enable web search (and web fetch)?
+
+`web_fetch` works without an API key. `web_search` requires a Brave Search API
+key (`BRAVE_API_KEY` or `tools.web.search.apiKey`).
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        apiKey: "BRAVE_API_KEY_HERE", // or set BRAVE_API_KEY
+        maxResults: 5
+      },
+      fetch: {
+        enabled: true
+      }
+    }
+  }
+}
+```
+
+Notes:
+- If you use allowlists, add `web_search`/`web_fetch` or `group:web`.
+- In sandboxed sessions, `web_fetch` auto-enables unless explicitly disabled.
+
+Docs: [Web tools](/tools/web).
+
 ### How do I run a central Gateway with specialized workers across devices?
 
 The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**: