#23306: fix(web-search): hint at config validation failure in missing-key error

## 🤖 AI-Assisted Contribution This PR was created with AI assistance (Claude). The contributor fully understands the changes and has tested them thoroughly. --- ## Problem Users who have configured a Brave Search API key still get `missing_brave_api_key` with no explanation. This happens because: 1. If the config file has validation errors (e.g. unknown keys from an older version), `loadConfig()` catches the `INVALID_CONFIG` error and returns `{}` 2. `tools.web.search` becomes `undefined` 3. `resolveSearchApiKey(undefined)` returns `undefined` 4. `web_search` returns `missing_brave_api_key` — **a misleading error that points the user in the wrong direction** The user sees: ``` error: missing_brave_api_key message: web_search needs a Brave Search API key. Run `openclaw configure --section web`... ``` But the actual problem is a config validation failure (e.g. `Unrecognized key: "streamMode"`), not a missing key. ## Root Cause ```typescript // src/config/io.ts } catch (err) { if (error?.code === "INVALID_CONFIG") { return {}; // ← silent fallback to empty config } } ``` When config validation fails, `loadConfig()` silently returns `{}`. The web_search tool receives no config and cannot read the API key that was already configured. ## Solution Add a diagnostic hint to the `missing_brave_api_key` error message **only when** `search` config is entirely absent (indicating a possible config load failure), pointing the user to the gateway logs or `openclaw gateway status`. When the search config is present but the API key is simply missing, the original message is shown unchanged — no false alarms. **Before:** ```json { "error": "missing_brave_api_key", "message": "web_search needs a Brave Search API key. Run `openclaw configure --section web` to store it, or set BRAVE_API_KEY in the Gateway environment." } ``` **After (when search config is absent):** ```json { "error": "missing_brave_api_key", "message": "web_search needs a Brave Search API key. Run `openclaw configure --section web` to store it, or set BRAVE_API_KEY in the Gateway environment. If you have already configured a key, your config file may have validation errors preventing it from loading — check the gateway logs or run `openclaw gateway status`." } ``` ## Changes - `src/agents/tools/web-search.ts`: Add `searchConfigPresent` param to `missingSearchKeyPayload()`; append config validation hint only when `search === undefined` - `src/agents/tools/web-search.missing-key.test.ts`: 2 new tests covering both message variants ## Testing ``` ✓ src/agents/tools/web-search.missing-key.test.ts (2 tests) 3ms ``` Both cases verified: 1. Empty config (`{}`) → hint included ✅ 2. Search config present, no key → hint absent ✅ Fixes #23058 <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR improves error messaging when Brave Search API key is missing by adding a diagnostic hint that helps users identify config validation failures. When `loadConfig()` catches an `INVALID_CONFIG` error and returns `{}`, the web_search tool receives no config and cannot read the configured API key. The hint is conditionally shown only when the search config is completely absent (`search === undefined`), preventing false positives when users simply haven't configured a key yet. - Modified `missingSearchKeyPayload()` to accept `searchConfigPresent` boolean parameter - Added conditional config validation hint to Brave error message (only shown when `searchConfigPresent === false`) - Pass `search !== undefined` at call site (line 750) to determine config presence - Added comprehensive test coverage for both scenarios (config absent vs. present) <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with minimal risk - The changes are minimal, well-tested, and improve user experience without altering core logic. The implementation correctly identifies config load failures using `search !== undefined` check, and the conditional hint prevents false positives. Tests verify both scenarios (config absent vs. present). No security concerns, no breaking changes, and follows existing code patterns. - No files require special attention _{Last reviewed commit: 625e310} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->