From 2e70c3ceabdb001216317652871335f6c35e06d7 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 05:35:22 +0000
Subject: [PATCH] fix: return setup hint when web_search lacks key

---
 CHANGELOG.md                  |  1 +
 docs/tools/web.md             |  1 +
 src/agents/tools/web-tools.ts | 15 +++++++++++++--
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c7510ff9..6b8f915b0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@
 - Security: add detect-secrets CI scan and baseline guidance. (#227) — thanks @Hyaxia.
 - Tools: add `web_search`/`web_fetch` (Brave API), auto-enable `web_fetch` for sandboxed sessions, and remove the `brave-search` skill.
 - CLI/Docs: add a web tools configure section for storing Brave API keys and update onboarding tips.
+- Tools: return a setup hint (docs link) when web_search runs without a Brave API key.
 - Browser: add Chrome extension relay takeover mode (toolbar button), plus `clawdbot browser extension install/path` and remote browser control via `clawdbot browser serve` + `browser.controlToken`.
 
 ### Fixes
diff --git a/docs/tools/web.md b/docs/tools/web.md
index 850ed5e39..eb0b8e968 100644
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -110,3 +110,4 @@ 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`.
+ - If the Brave key is missing, `web_search` returns a short setup hint with a docs link.
diff --git a/src/agents/tools/web-tools.ts b/src/agents/tools/web-tools.ts
index a07a4488e..53370478f 100644
--- a/src/agents/tools/web-tools.ts
+++ b/src/agents/tools/web-tools.ts
@@ -110,6 +110,15 @@ function resolveSearchApiKey(search?: WebSearchConfig): string | undefined {
   return fromConfig || fromEnv || undefined;
 }
 
+function missingSearchKeyPayload() {
+  return {
+    error: "missing_brave_api_key",
+    message:
+      "web_search needs a Brave Search API key. Run `clawdbot configure --section web` to store it, or set BRAVE_API_KEY in the Gateway environment.",
+    docs: "https://docs.clawd.bot/tools/web",
+  };
+}
+
 function resolveSearchProvider(search?: WebSearchConfig): (typeof SEARCH_PROVIDERS)[number] {
   const raw =
     search && "provider" in search && typeof search.provider === "string"
@@ -412,8 +421,6 @@ export function createWebSearchTool(options?: {
 }): AnyAgentTool | null {
   const search = resolveSearchConfig(options?.config);
   if (!resolveSearchEnabled({ search, sandboxed: options?.sandboxed })) return null;
-  const apiKey = resolveSearchApiKey(search);
-  if (!apiKey) return null;
   return {
     label: "Web Search",
     name: "web_search",
@@ -421,6 +428,10 @@ export function createWebSearchTool(options?: {
       "Search the web using Brave Search API. Returns titles, URLs, and snippets for fast research.",
     parameters: WebSearchSchema,
     execute: async (_toolCallId, args) => {
+      const apiKey = resolveSearchApiKey(search);
+      if (!apiKey) {
+        return jsonResult(missingSearchKeyPayload());
+      }
       const params = args as Record<string, unknown>;
       const query = readStringParam(params, "query", { required: true });
       const count =