feat(brave) add brave search API key catalog entry (#1416)

St0rmz1 · web-flow · commit ff0ba336e1cb · 2026-03-23T10:32:56.000-07:00
## Summary - Brave Search API removed their free tier — OpenClaw's web_search tool now requires an API key - Adds a brave-search entry to the Secret Catalog so users can configure their Brave Search API key through the Settings UI - The key is delivered as BRAVE_API_KEY env var to the container, which OpenClaw reads natively — no config-writer or image changes needed Files changed (8): - kiloclaw/packages/secret-catalog/src/catalog.ts — new brave-search catalog entry - kiloclaw/packages/secret-catalog/src/types.ts — add 'brave' to icon key schema - src/app/(app)/claw/components/icons/BraveSearchIcon.tsx — Brave lion logo SVG (from Simple Icons) - src/app/(app)/claw/components/secret-ui-adapter.ts — icon + description mapping - src/app/(app)/claw/components/SettingsTab.tsx — "Search" section above Developer Tools - src/app/(app)/claw/components/changelog-data.ts — changelog entry - kiloclaw/packages/secret-catalog/src/__tests__/catalog.test.ts — catalog test updates - kiloclaw/src/routes/kiloclaw.test.ts — buildConfiguredSecrets test updates ## Verification - pnpm --filter @kilocode/kiloclaw-secret-catalog test — 56/56 passed - pnpm --filter kiloclaw test — 956/956 passed - pnpm run format — clean - pnpm run typecheck — clean - Manual e2e test: Added a real Brave API key via the Settings UI, redeployed instance, confirmed web_search tool works with Brave Search ## Visual Changes - New Search section appears in Settings tab above Developer Tools - Shows Brave lion icon, "Brave Search" label, and single API Key field - Validation: keys must start with BSA followed by 20+ alphanumeric/underscore/hyphen characters - Changelog entry added for the feature <img width="969" height="535" alt="Screenshot 2026-03-23 at 10 17 39 AM" src="https://github.com/user-attachments/assets/4c8705c6-9a97-4376-8c5f-662d5fc46656" /> ## Reviewer Notes - Validation pattern ^BSA[A-Za-z0-9_-]{20,}$ was verified against a real Brave API key — third-party secret scanners (GitGuardian) suggested BSAI prefix but real keys show the 4th char varies - Env var is BRAVE_API_KEY (not BRAVE_SEARCH_API_KEY) — this is what OpenClaw's built-in web_search tool reads - No image rebuild required — the bootstrap generically decrypts all KILOCLAW_ENC_* vars - The some + filter pattern in SettingsTab matches existing sections (github, agentcard, onepassword) — kept consistent rather than introducing a new pattern - Brave lion logo SVG sourced from Simple Icons project, consistent with other branded icons (Discord, Slack, GitHub) in the same directory
diff --git a/kiloclaw/packages/secret-catalog/src/__tests__/catalog.test.ts b/kiloclaw/packages/secret-catalog/src/__tests__/catalog.test.ts
@@ -45,6 +45,7 @@ describe('Secret Catalog', () => {
         'github',
         'credit-card',
         'lock',
+        'brave',
       ]);
       for (const entry of SECRET_CATALOG) {
         expect(validIcons.has(entry.icon)).toBe(true);
@@ -119,6 +120,7 @@ describe('Secret Catalog', () => {
         'GITHUB_TOKEN',
         'GITHUB_USERNAME',
         'GITHUB_EMAIL',
+        'BRAVE_API_KEY',
       ]);
 
       const catalogEnvVars = new Set(FIELD_KEY_TO_ENV_VAR.values());
@@ -136,6 +138,7 @@ describe('Secret Catalog', () => {
       expect(FIELD_KEY_TO_ENV_VAR.get('githubToken')).toBe('GITHUB_TOKEN');
       expect(FIELD_KEY_TO_ENV_VAR.get('githubUsername')).toBe('GITHUB_USERNAME');
       expect(FIELD_KEY_TO_ENV_VAR.get('githubEmail')).toBe('GITHUB_EMAIL');
+      expect(FIELD_KEY_TO_ENV_VAR.get('braveSearchApiKey')).toBe('BRAVE_API_KEY');
     });
 
     it('ENV_VAR_TO_FIELD_KEY is the exact reverse of FIELD_KEY_TO_ENV_VAR', () => {
@@ -153,6 +156,7 @@ describe('Secret Catalog', () => {
       expect(ENV_VAR_TO_FIELD_KEY.get('GITHUB_TOKEN')).toBe('githubToken');
       expect(ENV_VAR_TO_FIELD_KEY.get('GITHUB_USERNAME')).toBe('githubUsername');
       expect(ENV_VAR_TO_FIELD_KEY.get('GITHUB_EMAIL')).toBe('githubEmail');
+      expect(ENV_VAR_TO_FIELD_KEY.get('BRAVE_API_KEY')).toBe('braveSearchApiKey');
     });
   });
 
@@ -194,10 +198,11 @@ describe('Secret Catalog', () => {
 
     it('returns all tool entries sorted by order', () => {
       const tools = getEntriesByCategory('tool');
-      expect(tools.length).toBe(3);
+      expect(tools.length).toBe(4);
       expect(tools[0].id).toBe('github');
       expect(tools[1].id).toBe('agentcard');
       expect(tools[2].id).toBe('onepassword');
+      expect(tools[3].id).toBe('brave-search');
     });
 
     it('returns empty array for categories with no entries', () => {
@@ -223,7 +228,8 @@ describe('Secret Catalog', () => {
       expect(keys).toContain('githubEmail');
       expect(keys).toContain('agentcardApiKey');
       expect(keys).toContain('onepasswordServiceAccountToken');
-      expect(keys.size).toBe(5);
+      expect(keys).toContain('braveSearchApiKey');
+      expect(keys.size).toBe(6);
     });
 
     it('returns empty set for categories with no entries', () => {
@@ -360,6 +366,21 @@ describe('Secret Catalog', () => {
       expect(validateFieldValue('invalid', pattern)).toBe(false);
     });
 
+    it('accepts valid Brave Search API keys', () => {
+      const pattern = '^BSA[A-Za-z0-9_-]{20,}$';
+      // Real key format: BSA + mixed alphanumeric, ~30 chars total
+      expect(validateFieldValue('BSAq2h7cYupyy704DHyXPFlUx8SinqK', pattern)).toBe(true);
+      expect(validateFieldValue('BSA' + 'A'.repeat(20), pattern)).toBe(true);
+      expect(validateFieldValue('BSAIabcDEF_123-456abcDEF1234', pattern)).toBe(true);
+    });
+
+    it('rejects invalid Brave Search API keys', () => {
+      const pattern = '^BSA[A-Za-z0-9_-]{20,}$';
+      expect(validateFieldValue('invalid', pattern)).toBe(false);
+      expect(validateFieldValue('BSAshort', pattern)).toBe(false);
+      expect(validateFieldValue('bsa' + 'A'.repeat(20), pattern)).toBe(false);
+    });
+
     it('rejects empty strings', () => {
       const pattern = '^\\d{8,}:[A-Za-z0-9_-]{30,50}$';
       expect(validateFieldValue('', pattern)).toBe(false);
diff --git a/kiloclaw/packages/secret-catalog/src/catalog.ts b/kiloclaw/packages/secret-catalog/src/catalog.ts
@@ -176,6 +176,27 @@ const SECRET_CATALOG_RAW = [
     helpText: 'Create a service account at 1password.com with access to a dedicated vault.',
     helpUrl: 'https://developer.1password.com/docs/service-accounts/get-started/',
   },
+  {
+    id: 'brave-search',
+    label: 'Brave Search',
+    category: 'tool',
+    icon: 'brave',
+    order: 4,
+    fields: [
+      {
+        key: 'braveSearchApiKey',
+        label: 'API Key',
+        placeholder: 'BSA...',
+        placeholderConfigured: 'Enter new key to replace',
+        envVar: 'BRAVE_API_KEY',
+        validationPattern: '^BSA[A-Za-z0-9_-]{20,}$',
+        validationMessage: 'Brave Search keys start with BSA followed by 20 or more characters.',
+        maxLength: 200,
+      },
+    ],
+    helpText: 'Get an API key from the Brave Search dashboard.',
+    helpUrl: 'https://brave.com/search/api/',
+  },
 ] as const satisfies readonly SecretCatalogEntry[];
 
 // Runtime validation — fails fast at module load if catalog data is malformed
diff --git a/kiloclaw/packages/secret-catalog/src/types.ts b/kiloclaw/packages/secret-catalog/src/types.ts
@@ -12,6 +12,7 @@ export const SecretIconKeySchema = z.enum([
   'github',
   'credit-card',
   'lock',
+  'brave',
 ]);
 
 /**
diff --git a/kiloclaw/src/routes/kiloclaw.test.ts b/kiloclaw/src/routes/kiloclaw.test.ts
@@ -18,6 +18,7 @@ describe('buildConfiguredSecrets', () => {
       github: false,
       agentcard: false,
       onepassword: false,
+      'brave-search': false,
     });
   });
 
@@ -112,7 +113,8 @@ describe('buildConfiguredSecrets', () => {
     expect(keys).toContain('discord');
     expect(keys).toContain('slack');
     expect(keys).toContain('onepassword');
-    expect(keys).toHaveLength(6);
+    expect(keys).toContain('brave-search');
+    expect(keys).toHaveLength(7);
   });
 
   it('treats null values as not configured', () => {
diff --git a/src/app/(app)/claw/components/SettingsTab.tsx b/src/app/(app)/claw/components/SettingsTab.tsx
@@ -731,6 +731,27 @@ export function SettingsTab({
         </div>
       </div>
 
+      {/* ── Search ── */}
+      {toolEntries.some(e => e.id === 'brave-search') && (
+        <div>
+          <h2 className="text-foreground mb-3 text-base font-semibold">Search</h2>
+          <div className="space-y-3">
+            {toolEntries
+              .filter(e => e.id === 'brave-search')
+              .map(entry => (
+                <SecretEntrySection
+                  key={entry.id}
+                  entry={entry}
+                  configured={configuredSecrets[entry.id] ?? false}
+                  mutations={mutations}
+                  onSecretsChanged={onSecretsChanged}
+                  isDirty={dirtySecrets.has(entry.id)}
+                />
+              ))}
+          </div>
+        </div>
+      )}
+
       {/* ── Developer Tools ── */}
       {toolEntries.some(e => e.id === 'github') && (
         <div>
diff --git a/src/app/(app)/claw/components/changelog-data.ts b/src/app/(app)/claw/components/changelog-data.ts
@@ -10,6 +10,13 @@ export type ChangelogEntry = {
 
 // Newest entries first. Developers add new entries to the top of this array.
 export const CHANGELOG_ENTRIES: ChangelogEntry[] = [
+  {
+    date: '2026-03-23',
+    description:
+      'Added Brave Search integration. Connect your Brave Search API key in Settings to enable the web_search tool. Brave Search removed their free tier, so an API key is now required.',
+    category: 'feature',
+    deployHint: 'redeploy_suggested',
+  },
   {
     date: '2026-03-19',
     description:
diff --git a/src/app/(app)/claw/components/icons/BraveSearchIcon.tsx b/src/app/(app)/claw/components/icons/BraveSearchIcon.tsx
@@ -0,0 +1,10 @@
+export function BraveSearchIcon({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 24 24" className={className} xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M15.68 0l2.096 2.38s1.84-.512 2.709.358c.868.87 1.584 1.638 1.584 1.638l-.562 1.381.715 2.047s-2.104 7.98-2.35 8.955c-.486 1.919-.818 2.66-2.198 3.633-1.38.972-3.884 2.66-4.293 2.916-.409.256-.92.692-1.38.692-.46 0-.97-.436-1.38-.692a185.796 185.796 0 01-4.293-2.916c-1.38-.973-1.712-1.714-2.197-3.633-.247-.975-2.351-8.955-2.351-8.955l.715-2.047-.562-1.381s.716-.768 1.585-1.638c.868-.87 2.708-.358 2.708-.358L8.321 0h7.36zm-3.679 14.936c-.14 0-1.038.317-1.758.69-.72.373-1.242.637-1.409.742-.167.104-.065.301.087.409.152.107 2.194 1.69 2.393 1.866.198.175.489.464.687.464.198 0 .49-.29.688-.464.198-.175 2.24-1.759 2.392-1.866.152-.108.254-.305.087-.41-.167-.104-.689-.368-1.41-.741-.72-.373-1.617-.69-1.757-.69zm0-11.278s-.409.001-1.022.206-1.278.46-1.584.46c-.307 0-2.581-.434-2.581-.434S4.119 7.152 4.119 7.849c0 .697.339.881.68 1.243l2.02 2.149c.192.203.59.511.356 1.066-.235.555-.58 1.26-.196 1.977.384.716 1.042 1.194 1.464 1.115.421-.08 1.412-.598 1.776-.834.364-.237 1.518-1.19 1.518-1.554 0-.365-1.193-1.02-1.413-1.168-.22-.15-1.226-.725-1.247-.95-.02-.227-.012-.293.284-.851.297-.559.831-1.304.742-1.8-.089-.495-.95-.753-1.565-.986-.615-.232-1.799-.671-1.947-.74-.148-.068-.11-.133.339-.175.448-.043 1.719-.212 2.292-.052.573.16 1.552.403 1.632.532.079.13.149.134.067.579-.081.445-.5 2.581-.541 2.96-.04.38-.12.63.288.724.409.094 1.097.256 1.333.256s.924-.162 1.333-.256c.408-.093.329-.344.288-.723-.04-.38-.46-2.516-.541-2.961-.082-.445-.012-.45.067-.579.08-.129 1.059-.372 1.632-.532.573-.16 1.845.009 2.292.052.449.042.487.107.339.175-.148.069-1.332.508-1.947.74-.615.233-1.476.49-1.565.986-.09.496.445 1.241.742 1.8.297.558.304.624.284.85-.02.226-1.026.802-1.247.95-.22.15-1.413.804-1.413 1.169 0 .364 1.154 1.317 1.518 1.554.364.236 1.355.755 1.776.834.422.079 1.08-.4 1.464-1.115.384-.716.039-1.422-.195-1.977-.235-.555.163-.863.355-1.066l2.02-2.149c.341-.362.68-.546.68-1.243 0-.697-2.695-3.96-2.695-3.96s-2.274.436-2.58.436c-.307 0-.972-.256-1.585-.461-.613-.205-1.022-.206-1.022-.206z"
+        fill="#FB542B"
+      />
+    </svg>
+  );
+}
diff --git a/src/app/(app)/claw/components/secret-ui-adapter.ts b/src/app/(app)/claw/components/secret-ui-adapter.ts
@@ -6,6 +6,7 @@ import { DiscordIcon } from './icons/DiscordIcon';
 import { SlackIcon } from './icons/SlackIcon';
 import { GitHubIcon } from './icons/GitHubIcon';
 import { AgentCardIcon } from './icons/AgentCardIcon';
+import { BraveSearchIcon } from './icons/BraveSearchIcon';
 
 const ICON_MAP: Record<SecretIconKey, React.ComponentType<{ className?: string }>> = {
   send: TelegramIcon,
@@ -15,6 +16,7 @@ const ICON_MAP: Record<SecretIconKey, React.ComponentType<{ className?: string }
   github: GitHubIcon,
   'credit-card': AgentCardIcon,
   lock: Lock,
+  brave: BraveSearchIcon,
 };
 
 export function getIcon(iconKey: SecretIconKey): React.ComponentType<{ className?: string }> {
@@ -29,6 +31,7 @@ const DESCRIPTION_MAP: Record<string, string> = {
   github: 'Connect a GitHub account for code operations',
   agentcard: 'Give your bot virtual debit cards for spending',
   onepassword: 'Look up credentials and manage vault items via the op CLI',
+  'brave-search': 'Add a Brave Search API key for web search',
 };
 
 export function getDescription(entryId: string): string {
