From 2e0325e3bf4465928471e5ec77716f1ee974b31d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 04:25:19 +0000
Subject: [PATCH] feat: add web search hint to onboarding

---
 docs/start/wizard.md                           |  4 ++++
 docs/tools/web.md                              | 18 +++++++++---------
 src/commands/onboard-non-interactive/local.ts  |  6 ++++++
 src/commands/onboard-non-interactive/remote.ts |  3 +++
 src/wizard/onboarding.ts                       |  8 ++++++++
 5 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/docs/start/wizard.md b/docs/start/wizard.md
index 2cb90f641..bc62f7913 100644
--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@@ -24,6 +24,10 @@ Follow‑up reconfiguration:
 clawdbot configure
 ```
 
+Recommended: set up a Brave Search API key so the agent can use `web_search`
+(`web_fetch` works without a key). Set `BRAVE_API_KEY` or
+`tools.web.search.apiKey`. Docs: [Web tools](/tools/web).
+
 ## QuickStart vs Advanced
 
 The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
diff --git a/docs/tools/web.md b/docs/tools/web.md
index 4d17561d1..d837d1069 100644
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -24,6 +24,15 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
   (HTML → markdown/text). It does **not** execute JavaScript.
 - In sandboxed sessions, `web_fetch` is enabled automatically (unless explicitly disabled).
 
+## 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.
+
 ## web_search
 
 Search the web with Brave’s API.
@@ -92,12 +101,3 @@ 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.
diff --git a/src/commands/onboard-non-interactive/local.ts b/src/commands/onboard-non-interactive/local.ts
index a46c1bbab..5027ab69f 100644
--- a/src/commands/onboard-non-interactive/local.ts
+++ b/src/commands/onboard-non-interactive/local.ts
@@ -110,4 +110,10 @@ export async function runNonInteractiveOnboardingLocal(params: {
     skipSkills: Boolean(opts.skipSkills),
     skipHealth: Boolean(opts.skipHealth),
   });
+
+  if (!opts.json) {
+    runtime.log(
+      "Tip: set BRAVE_API_KEY (or tools.web.search.apiKey) to enable web_search. Docs: https://docs.clawd.bot/tools/web",
+    );
+  }
 }
diff --git a/src/commands/onboard-non-interactive/remote.ts b/src/commands/onboard-non-interactive/remote.ts
index fed65368c..ab2e01e40 100644
--- a/src/commands/onboard-non-interactive/remote.ts
+++ b/src/commands/onboard-non-interactive/remote.ts
@@ -44,5 +44,8 @@ export async function runNonInteractiveOnboardingRemote(params: {
   } else {
     runtime.log(`Remote gateway: ${remoteUrl}`);
     runtime.log(`Auth: ${payload.auth}`);
+    runtime.log(
+      "Tip: set BRAVE_API_KEY (or tools.web.search.apiKey) to enable web_search. Docs: https://docs.clawd.bot/tools/web",
+    );
   }
 }
diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts
index 64ee88804..710b48b81 100644
--- a/src/wizard/onboarding.ts
+++ b/src/wizard/onboarding.ts
@@ -75,6 +75,14 @@ export async function runOnboardingWizard(
 ) {
   printWizardHeader(runtime);
   await prompter.intro("Clawdbot onboarding");
+  await prompter.note(
+    [
+      "Recommended: get a Brave Search API key to enable web_search.",
+      "Set BRAVE_API_KEY or tools.web.search.apiKey.",
+      "Docs: https://docs.clawd.bot/tools/web",
+    ].join("\n"),
+    "Web search (optional)",
+  );
   await requireRiskAcknowledgement({ opts, prompter });
 
   const snapshot = await readConfigFileSnapshot();