@swarmclawai/swarmclaw 1.5.46 → 1.5.47

package/README.md

@@ -396,6 +396,16 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.47 Highlights
+
+- **MCP injection for GitHub Copilot CLI and OpenAI Codex CLI agents**: agents using the `copilot-cli` or `codex-cli` providers now run with their assigned MCP servers attached at runtime. Copilot CLI receives the servers via `--additional-mcp-config @<tempfile>`; Codex CLI gets per-session `[mcp_servers.*]` TOML sections appended to a scoped `config.toml`. Stdio transports (command, args, env, cwd) and SSE / streamable-http transports (url, headers) are both supported. Skills assigned to the agent continue to be injected via the system prompt.
+- **Skills and MCP panel visible for copilot-cli and codex-cli in the agent editor**: the Advanced Settings section now opens for these two providers so you can attach skills and MCP servers from the UI. Routing, memory, and voice panels stay hidden since these providers are worker-only.
+- **Codex CLI approval policy change**: Codex CLI sessions now launch with `--dangerously-bypass-approvals-and-sandbox` instead of `--full-auto`. The old flag silently cancels MCP tool calls via Codex's approval gate, which is why MCP tool results were not landing. SwarmClaw itself runs in its own sandbox, so Codex's additional sandbox was not load-bearing, but be aware of the change if you were relying on it for a specific agent.
+- **Under the hood**: `~/.codex-sessions/<session.id>/` replaces `/tmp/swarmclaw-codex-*` as the per-session Codex config directory because Codex refuses to create helper binaries under `/tmp`. The Playwright MCP proxy now passes an explicit `cwd: process.cwd()` when spawning, so it no longer crashes with `uv_cwd ENOENT` when the server is restarted after a directory move.
+- **Exa as a new web search provider**: Settings > Web Search gains an Exa option alongside Tavily, Brave, SearXNG, DuckDuckGo, Google, and Bing. Exa uses neural search with AI-generated summaries and falls back to highlights, then raw text when summaries are unavailable. Configure the key via the UI, the `EXA_API_KEY` environment variable, or the secrets store. Requests carry an `x-exa-integration: swarmclaw` tracking header so usage attributed to SwarmClaw is visible to Exa.
+
+Thanks to [@borislavnnikolov](https://github.com/borislavnnikolov) and [@tgonzalezc5](https://github.com/tgonzalezc5) for the contributions.
+
 ### v1.5.46 Highlights
 
 - **Custom base URL for built-in OpenAI and Anthropic providers**: the Endpoint field in provider settings now works for the built-in OpenAI and Anthropic providers (marked as `optionalEndpoint`). Point them at a proxy, gateway, or self-hosted endpoint and the URL persists, auto-resolves on connection test, and flows through both the live chat path and the LangGraph agent path (`ChatAnthropic` now receives `anthropicApiUrl`). Existing installs with no custom URL keep using the defaults.
@@ -404,7 +414,7 @@ Operational docs: https://swarmclaw.ai/docs/observability
 - **Anthropic streaming refactor**: the streaming handler moved from Node's `https.request()` to `fetch()`. Same behavior, cleaner cancellation, and it now respects `session.apiEndpoint` as a full base URL instead of a hostname.
 - **Connection test body**: Ollama and OpenAI-compatible test requests now send `max_completion_tokens` instead of the legacy `max_tokens`, matching current OpenAI conventions and working correctly with reasoning models that reject `max_tokens`.
 
-Thanks to @Llugaes for the contribution.
+Thanks to [@Llugaes](https://github.com/Llugaes) for the contribution.
 
 ### v1.5.45 Highlights
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.46",
+  "version": "1.5.47",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/settings/route.ts

@@ -26,7 +26,7 @@ const TASK_QG_MIN_EVIDENCE_MIN = 0
 const TASK_QG_MIN_EVIDENCE_MAX = 8
 const SESSION_RESET_TIMEOUT_MIN = 0
 const SESSION_RESET_TIMEOUT_MAX = 365 * 24 * 60 * 60
-const SECRET_SETTING_KEYS = ['elevenLabsApiKey', 'tavilyApiKey', 'braveApiKey'] as const
+const SECRET_SETTING_KEYS = ['elevenLabsApiKey', 'tavilyApiKey', 'braveApiKey', 'exaApiKey'] as const
 
 function parseIntSetting(value: unknown, fallback: number, min: number, max: number): number {
   const parsed = typeof value === 'number'

package/src/components/agents/agent-sheet.tsx

@@ -12,7 +12,7 @@ import { toast } from 'sonner'
 import { ModelCombobox } from '@/components/shared/model-combobox'
 import type { ProviderType, ClaudeSkill, AgentPackManifest, AgentRoutingStrategy, AgentRoutingTarget } from '@/types'
 import { AVAILABLE_TOOLS, PLATFORM_TOOLS } from '@/lib/tool-definitions'
-import { NATIVE_CAPABILITY_PROVIDER_IDS, NON_LANGGRAPH_PROVIDER_IDS, WORKER_ONLY_PROVIDER_IDS } from '@/lib/provider-sets'
+import { MCP_INJECTION_PROVIDER_IDS, NATIVE_CAPABILITY_PROVIDER_IDS, NON_LANGGRAPH_PROVIDER_IDS, WORKER_ONLY_PROVIDER_IDS } from '@/lib/provider-sets'
 import { isOrchestratorProviderEligible } from '@/lib/orchestrator-config'
 import { AgentAvatar } from './agent-avatar'
 import { AgentPickerList } from '@/components/shared/agent-picker-list'
@@ -179,6 +179,7 @@ export function AgentSheet() {
   const dynamicSkills = useAppStore((s) => s.skills)
   const mcpServers = useAppStore((s) => s.mcpServers)
   const loadSkills = useAppStore((s) => s.loadSkills)
+  const loadMcpServersAction = useAppStore((s) => s.loadMcpServers)
   const [claudeSkills, setClaudeSkills] = useState<ClaudeSkill[]>([])
   const [claudeSkillsLoading, setClaudeSkillsLoading] = useState(false)
   const loadClaudeSkills = async () => {
@@ -390,6 +391,7 @@ export function AgentSheet() {
       loadGatewayProfiles()
       loadCredentials()
       loadSkills()
+      loadMcpServersAction()
       loadProjects()
       loadClaudeSkills()
       // Fetch enabled extension IDs so we can filter tool toggles
@@ -2007,13 +2009,14 @@ export function AgentSheet() {
         </SectionCard>
       )}
 
-      {!WORKER_ONLY_PROVIDER_IDS.has(provider) && (
+      {(!WORKER_ONLY_PROVIDER_IDS.has(provider) || MCP_INJECTION_PROVIDER_IDS.has(provider)) && (
       <AdvancedSettingsSection
         open={showAdvancedSettings}
         onToggle={() => setShowAdvancedSettings((current) => !current)}
         summary={advancedSummary}
         badges={agentAdvancedBadges}
       >
+      {!WORKER_ONLY_PROVIDER_IDS.has(provider) && (<>
       <SectionCard
         title="Context & Tool Access"
         description="Control how many tools are described in this agent's system prompt. Scoped (default) keeps the agent focused and saves ~3 k input tokens per turn; Universal gives it visibility into every built-in tool."
@@ -2450,6 +2453,7 @@ export function AgentSheet() {
         </div>
       )}
       </SectionCard>
+      </>)}
 
       <SectionCard
         title="Tools & Skills"
@@ -2539,13 +2543,13 @@ export function AgentSheet() {
             {provider === 'claude-cli'
               ? 'Claude CLI uses its own built-in capabilities — no additional local tool/platform configuration is needed.'
               : provider === 'codex-cli'
-                ? 'OpenAI Codex CLI uses its own built-in tools (shell, files, etc.) — no additional local tool configuration is needed.'
+                ? 'OpenAI Codex CLI uses its own built-in tools (shell, files, etc.). Skills and MCP servers assigned below will be injected at runtime.'
                 : provider === 'opencode-cli'
                   ? 'OpenCode CLI uses its own built-in tools (shell, files, etc.) — no additional local tool configuration is needed.'
                   : provider === 'gemini-cli'
                     ? 'Gemini CLI uses its own built-in tools and runtime — SwarmClaw does not inject local platform tools for it.'
                     : provider === 'copilot-cli'
-                      ? 'GitHub Copilot CLI uses its own built-in tools and runtime — SwarmClaw does not inject local platform tools for it.'
+                      ? 'GitHub Copilot CLI uses its own built-in tools and runtime. Skills and MCP servers assigned below will be injected at runtime.'
                       : provider === 'droid-cli'
                         ? 'Factory Droid CLI uses its own built-in tools and autonomy controls — SwarmClaw does not inject local platform tools for it.'
                         : provider === 'cursor-cli'

package/src/lib/provider-sets.ts

@@ -9,3 +9,6 @@ export const NATIVE_CAPABILITY_PROVIDER_IDS = new Set(['claude-cli', 'codex-cli'
 
 /** Providers that can only act as workers — no coordinator role, no heartbeat, no advanced settings. */
 export const WORKER_ONLY_PROVIDER_IDS = new Set(['claude-cli', 'codex-cli', 'opencode-cli', 'gemini-cli', 'copilot-cli', 'droid-cli', 'cursor-cli', 'qwen-code-cli', 'goose', 'openclaw', 'hermes'])
+
+/** CLI providers that support MCP server and skill injection at runtime (via provider-specific config mechanisms). */
+export const MCP_INJECTION_PROVIDER_IDS = new Set(['copilot-cli', 'codex-cli'])

package/src/lib/providers/codex-cli.ts

@@ -6,6 +6,8 @@ import type { StreamChatOptions } from './index'
 import { log } from '../server/logger'
 import { loadRuntimeSettings } from '@/lib/server/runtime/runtime-settings'
 import { resolveCliBinary, buildCliEnv, probeCliAuth, attachAbortHandler, symlinkConfigFiles, isStderrNoise } from './cli-utils'
+import { getAgent } from '@/lib/server/agents/agent-repository'
+import { loadMcpServers } from '@/lib/server/storage'
 
 const TAG = 'provider-codex'
 
@@ -31,7 +33,10 @@ export function streamCodexCliChat({ session, message, imagePath, systemPrompt,
     args.push('resume', session.codexThreadId)
   }
 
-  args.push('--json', '--full-auto', '--skip-git-repo-check')
+  // Use --dangerously-bypass-approvals-and-sandbox instead of --full-auto so that
+  // MCP tool calls are not silently cancelled by codex's approval gate.
+  // SwarmClaw runs in its own sandboxed environment so bypassing codex's sandbox is safe.
+  args.push('--json', '--dangerously-bypass-approvals-and-sandbox', '--skip-git-repo-check')
 
   if (session.model) args.push('-m', session.model)
   if (codexModelRequiresReasoningDowngrade(session.model)) {
@@ -64,19 +69,73 @@ export function streamCodexCliChat({ session, message, imagePath, systemPrompt,
     }
   }
 
-  // System prompt: write temp AGENTS.override.md in a temp CODEX_HOME
+  // System prompt + MCP injection: create a temp CODEX_HOME when needed
   // Symlink auth files from the real config dir so auth still works
   let tempCodexHome: string | null = null
-  if (systemPrompt && !session.codexThreadId) {
+  const agentForMcp = session.agentId ? getAgent(session.agentId as string) : null
+  const agentMcpServerIds: string[] = agentForMcp?.mcpServerIds || []
+  const needsTempHome = (systemPrompt && !session.codexThreadId) || agentMcpServerIds.length > 0
+  if (needsTempHome) {
     const realCodexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
-    tempCodexHome = path.join(os.tmpdir(), `swarmclaw-codex-${session.id}`)
+    // Use ~/.codex-sessions/ not /tmp — codex refuses to create helper binaries under /tmp
+    const sessionsDir = path.join(os.homedir(), '.codex-sessions')
+    tempCodexHome = path.join(sessionsDir, session.id)
     fs.mkdirSync(tempCodexHome, { recursive: true })
 
     // Symlink auth/config files from real CODEX_HOME into temp dir
     symlinkConfigFiles(realCodexHome, tempCodexHome)
 
-    // Write system prompt as AGENTS.override.md
-    fs.writeFileSync(path.join(tempCodexHome, 'AGENTS.override.md'), systemPrompt)
+    // Write system prompt as AGENTS.override.md (first turn only)
+    if (systemPrompt && !session.codexThreadId) {
+      fs.writeFileSync(path.join(tempCodexHome, 'AGENTS.override.md'), systemPrompt)
+    }
+
+    // Inject agent-assigned MCP servers into config.toml
+    if (agentMcpServerIds.length > 0) {
+      try {
+        const allMcpServers = loadMcpServers()
+        const tomlParts: string[] = []
+        for (const serverId of agentMcpServerIds) {
+          const config = allMcpServers[serverId]
+          if (!config) continue
+          const name = config.name.replace(/[^a-zA-Z0-9_]/g, '_')
+          if (config.transport === 'stdio' && config.command) {
+            tomlParts.push(`[mcp_servers.${name}]`)
+            tomlParts.push(`command = ${JSON.stringify(config.command)}`)
+            const argsStr = (config.args || []).map((a: string) => JSON.stringify(a)).join(', ')
+            tomlParts.push(`args = [${argsStr}]`)
+            if (config.cwd) tomlParts.push(`cwd = ${JSON.stringify(config.cwd)}`)
+            tomlParts.push('')
+            // Env vars go in a separate subsection: [mcp_servers.name.env]
+            if (config.env && Object.keys(config.env).length > 0) {
+              tomlParts.push(`[mcp_servers.${name}.env]`)
+              for (const [k, v] of Object.entries(config.env as Record<string, string>)) {
+                tomlParts.push(`${k} = ${JSON.stringify(v)}`)
+              }
+              tomlParts.push('')
+            }
+          } else if ((config.transport === 'sse' || config.transport === 'streamable-http') && config.url) {
+            tomlParts.push(`[mcp_servers.${name}]`)
+            tomlParts.push(`url = ${JSON.stringify(config.url)}`)
+            tomlParts.push('')
+          }
+        }
+        if (tomlParts.length > 0) {
+          const realConfigPath = path.join(realCodexHome, 'config.toml')
+          const existingConfig = fs.existsSync(realConfigPath)
+            ? fs.readFileSync(realConfigPath, 'utf-8')
+            : ''
+          const tempConfigPath = path.join(tempCodexHome, 'config.toml')
+          // Remove symlink created by symlinkConfigFiles before writing our own file
+          try { fs.unlinkSync(tempConfigPath) } catch { /* no symlink — ignore */ }
+          fs.writeFileSync(tempConfigPath, existingConfig + '\n' + tomlParts.join('\n'))
+          log.info('codex-cli', `Injecting ${agentMcpServerIds.length} MCP server(s) via config.toml`)
+        }
+      } catch (mcpErr) {
+        log.warn('codex-cli', `Failed to build MCP config: ${mcpErr}`)
+      }
+    }
+
     env.CODEX_HOME = tempCodexHome
   }
 

package/src/lib/providers/copilot-cli.ts

@@ -6,6 +6,8 @@ import type { StreamChatOptions } from './index'
 import { log } from '../server/logger'
 import { loadRuntimeSettings } from '@/lib/server/runtime/runtime-settings'
 import { resolveCliBinary, buildCliEnv, probeCliAuth, attachAbortHandler, symlinkConfigFiles, isStderrNoise } from './cli-utils'
+import { getAgent } from '@/lib/server/agents/agent-repository'
+import { loadMcpServers } from '@/lib/server/storage'
 
 /**
  * GitHub Copilot CLI provider — spawns `copilot -p <message> --output-format=json -s --yolo`.
@@ -65,6 +67,44 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
     env.COPILOT_HOME = tempCopilotHome
   }
 
+  // Inject agent-assigned MCP servers via --additional-mcp-config flag
+  let mcpAdditionalConfigPath: string | null = null
+  try {
+    const agentForMcp = session.agentId ? getAgent(session.agentId as string) : null
+    const agentMcpServerIds: string[] = agentForMcp?.mcpServerIds || []
+    if (agentMcpServerIds.length > 0) {
+      const allMcpServers = loadMcpServers()
+      const mcpServerEntries: Record<string, Record<string, unknown>> = {}
+      for (const serverId of agentMcpServerIds) {
+        const config = allMcpServers[serverId]
+        if (!config) continue
+        const name = config.name.replace(/[^a-zA-Z0-9_-]/g, '-')
+        if (config.transport === 'stdio' && config.command) {
+          mcpServerEntries[name] = {
+            command: config.command,
+            args: config.args || [],
+            ...(config.env && Object.keys(config.env).length > 0 ? { env: config.env } : {}),
+            ...(config.cwd ? { cwd: config.cwd } : {}),
+          }
+        } else if ((config.transport === 'sse' || config.transport === 'streamable-http') && config.url) {
+          mcpServerEntries[name] = {
+            type: config.transport,
+            url: config.url,
+            ...(config.headers && Object.keys(config.headers).length > 0 ? { headers: config.headers } : {}),
+          }
+        }
+      }
+      if (Object.keys(mcpServerEntries).length > 0) {
+        mcpAdditionalConfigPath = path.join(os.tmpdir(), `swarmclaw-copilot-mcp-${session.id}.json`)
+        fs.writeFileSync(mcpAdditionalConfigPath, JSON.stringify({ mcpServers: mcpServerEntries }))
+        args.push('--additional-mcp-config', `@${mcpAdditionalConfigPath}`)
+        log.info('copilot-cli', `Injecting ${Object.keys(mcpServerEntries).length} MCP server(s)`)
+      }
+    }
+  } catch (mcpErr) {
+    log.warn('copilot-cli', `Failed to build MCP config: ${mcpErr}`)
+  }
+
   log.info('copilot-cli', `Spawning: ${binary}`, {
     args: args.map((a) => a.length > 100 ? a.slice(0, 100) + '...' : a),
     cwd: session.cwd,
@@ -221,6 +261,9 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
       if (tempCopilotHome) {
         try { fs.rmSync(tempCopilotHome, { recursive: true }) } catch { /* ignore */ }
       }
+      if (mcpAdditionalConfigPath) {
+        try { fs.unlinkSync(mcpAdditionalConfigPath) } catch { /* ignore */ }
+      }
       if ((code ?? 0) !== 0 && !fullResponse.trim()) {
         const msg = stderrText.trim()
           ? `Copilot CLI exited with code ${code ?? 'unknown'}${sig ? ` (${sig})` : ''}: ${stderrText.trim().slice(0, 1200)}`
@@ -236,6 +279,9 @@ export function streamCopilotCliChat({ session, message, imagePath, systemPrompt
       if (tempCopilotHome) {
         try { fs.rmSync(tempCopilotHome, { recursive: true }) } catch { /* ignore */ }
       }
+      if (mcpAdditionalConfigPath) {
+        try { fs.unlinkSync(mcpAdditionalConfigPath) } catch { /* ignore */ }
+      }
       write(`data: ${JSON.stringify({ t: 'err', text: e.message })}\n\n`)
       resolve(fullResponse)
     })

package/src/lib/server/connectors/connector-inbound.ts

@@ -1,5 +1,6 @@
 import { log } from '@/lib/server/logger'
 import { genId } from '@/lib/id'
+import { NON_LANGGRAPH_PROVIDER_IDS } from '@/lib/provider-sets'
 import {
   loadConnectors,
   loadSession,
@@ -1022,6 +1023,8 @@ async function routeMessage(connector: Connector, msg: InboundMessage): Promise<
     }
   }
 
+
+
   // Build system prompt: [identity] \n\n [userPrompt] \n\n [soul] \n\n [systemPrompt]
   const settings = loadSettings()
   const promptParts: string[] = []
@@ -1196,7 +1199,7 @@ If media sending fails, report the exact error and retry with a corrected path/t
     const transcript = typeof params.transcript === 'string' ? params.transcript.trim() : ''
     if (transcript) currentChannelDeliveryRef.current?.transcripts.push(transcript)
   }
-  const hasTools = getEnabledCapabilityIds(session).length > 0 && session.provider !== 'claude-cli'
+  const hasTools = getEnabledCapabilityIds(session).length > 0 && !NON_LANGGRAPH_PROVIDER_IDS.has(session.provider as string)
   log.info(TAG, `Routing message to agent "${agent.name}" (${session.provider}/${session.model}), hasTools=${!!hasTools}`)
 
   if (hasTools) {

package/src/lib/server/playwright-proxy.mjs

@@ -33,10 +33,12 @@ const child = cliPath
   ? spawn(process.execPath, [cliPath], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: sanitizePlaywrightEnv(process.env),
+      cwd: process.cwd(),
     })
   : spawn('npx', ['@playwright/mcp@latest'], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: sanitizePlaywrightEnv(process.env),
+      cwd: process.cwd(),
     })
 
 // Graceful EPIPE handling — dev server restarts break stdio pipes

package/src/lib/server/session-tools/search-providers.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, beforeEach, afterEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+describe('getSearchProvider — exa', () => {
+  const originalEnv = process.env.EXA_API_KEY
+
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.EXA_API_KEY
+    else process.env.EXA_API_KEY = originalEnv
+  })
+
+  it('throws when no API key is available', async () => {
+    delete process.env.EXA_API_KEY
+    const { getSearchProvider } = await import('./search-providers')
+    await assert.rejects(
+      () => getSearchProvider({ webSearchProvider: 'exa' }),
+      (err: Error) => {
+        assert.match(err.message, /Exa requires an API key/)
+        return true
+      },
+    )
+  })
+
+  it('resolves an ExaProvider from EXA_API_KEY env var', async () => {
+    process.env.EXA_API_KEY = 'test-key-123'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa' })
+    assert.equal(provider.id, 'exa')
+    assert.equal(provider.name, 'Exa')
+  })
+
+  it('prefers settings key over env var', async () => {
+    process.env.EXA_API_KEY = 'env-key'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa', exaApiKey: 'settings-key' })
+    assert.equal(provider.id, 'exa')
+  })
+})
+
+describe('ExaProvider.search — response parsing', () => {
+  const FIXTURE = {
+    requestId: 'test-req-1',
+    results: [
+      {
+        title: 'Exa AI Search',
+        url: 'https://exa.ai',
+        publishedDate: '2024-01-15',
+        author: 'Exa Team',
+        text: 'Exa is a search engine for AI.',
+        highlights: ['Exa provides neural search.', 'Built for developers.'],
+        highlightScores: [0.95, 0.88],
+        summary: 'Exa is an AI-powered search engine built for developers.',
+      },
+      {
+        title: 'Getting Started with Exa',
+        url: 'https://docs.exa.ai/getting-started',
+        text: 'Learn how to integrate Exa into your application.',
+        highlights: [],
+        summary: '',
+      },
+      {
+        title: 'Minimal Result',
+        url: 'https://example.com/minimal',
+      },
+    ],
+  }
+
+  let originalFetch: typeof globalThis.fetch
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('parses a full API response into SearchResult[]', async () => {
+    globalThis.fetch = mock.fn(async () => new Response(JSON.stringify(FIXTURE), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })) as unknown as typeof globalThis.fetch
+
+    process.env.EXA_API_KEY = 'test-key'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa' })
+    const results = await provider.search('exa search', 10)
+
+    assert.equal(results.length, 3)
+    assert.equal(results[0].title, 'Exa AI Search')
+    assert.equal(results[0].url, 'https://exa.ai')
+    // Summary is preferred when available
+    assert.equal(results[0].snippet, 'Exa is an AI-powered search engine built for developers.')
+  })
+
+  it('falls back to text when summary and highlights are empty', async () => {
+    globalThis.fetch = mock.fn(async () => new Response(JSON.stringify(FIXTURE), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })) as unknown as typeof globalThis.fetch
+
+    process.env.EXA_API_KEY = 'test-key'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa' })
+    const results = await provider.search('exa search', 10)
+
+    // Second result has empty summary and empty highlights, should fall back to text
+    assert.equal(results[1].snippet, 'Learn how to integrate Exa into your application.')
+  })
+
+  it('returns empty snippet when no content fields are present', async () => {
+    globalThis.fetch = mock.fn(async () => new Response(JSON.stringify(FIXTURE), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })) as unknown as typeof globalThis.fetch
+
+    process.env.EXA_API_KEY = 'test-key'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa' })
+    const results = await provider.search('exa search', 10)
+
+    // Third result has no summary, no highlights, no text
+    assert.equal(results[2].snippet, '')
+    assert.equal(results[2].title, 'Minimal Result')
+  })
+
+  it('sends the integration tracking header', async () => {
+    let capturedHeaders: Record<string, string> = {}
+    globalThis.fetch = mock.fn(async (url: string | URL | Request, init?: RequestInit) => {
+      const headers = init?.headers as Record<string, string> | undefined
+      if (headers) capturedHeaders = { ...headers }
+      return new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }) as unknown as typeof globalThis.fetch
+
+    process.env.EXA_API_KEY = 'test-key'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa' })
+    await provider.search('test', 5)
+
+    assert.equal(capturedHeaders['x-exa-integration'], 'swarmclaw')
+    assert.equal(capturedHeaders['x-api-key'], 'test-key')
+  })
+
+  it('throws on non-OK HTTP response', async () => {
+    globalThis.fetch = mock.fn(async () => new Response('Unauthorized', {
+      status: 401,
+      statusText: 'Unauthorized',
+    })) as unknown as typeof globalThis.fetch
+
+    process.env.EXA_API_KEY = 'bad-key'
+    const { getSearchProvider } = await import('./search-providers')
+    const provider = await getSearchProvider({ webSearchProvider: 'exa' })
+
+    await assert.rejects(
+      () => provider.search('test', 5),
+      (err: Error) => {
+        assert.match(err.message, /401/)
+        return true
+      },
+    )
+  })
+})

package/src/lib/server/session-tools/search-providers.ts

@@ -243,6 +243,65 @@ class BraveProvider implements WebSearchProvider {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Exa (API key required — from secrets or EXA_API_KEY env var)
+// ---------------------------------------------------------------------------
+
+interface ExaSearchResult {
+  title?: string
+  url?: string
+  publishedDate?: string | null
+  author?: string | null
+  text?: string
+  highlights?: string[]
+  highlightScores?: number[]
+  summary?: string
+}
+
+class ExaProvider implements WebSearchProvider {
+  id = 'exa'
+  name = 'Exa'
+
+  constructor(private apiKey: string) {}
+
+  async search(query: string, maxResults: number): Promise<SearchResult[]> {
+    const res = await fetch('https://api.exa.ai/search', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': this.apiKey,
+        'x-exa-integration': 'swarmclaw',
+      },
+      body: JSON.stringify({
+        query,
+        type: 'auto',
+        numResults: maxResults,
+        contents: {
+          highlights: { numSentences: 3 },
+          text: { maxCharacters: 500 },
+          summary: true,
+        },
+      }),
+      signal: AbortSignal.timeout(15000),
+    })
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`)
+    const data = await res.json()
+    const rawResults: ExaSearchResult[] = Array.isArray(data.results) ? data.results : []
+    return rawResults.slice(0, maxResults).map((r) => ({
+      title: r.title || '',
+      url: r.url || '',
+      snippet: buildExaSnippet(r),
+    }))
+  }
+}
+
+function buildExaSnippet(result: ExaSearchResult): string {
+  if (result.summary) return result.summary
+  if (result.highlights && result.highlights.length > 0) return result.highlights.join(' … ')
+  if (result.text) return result.text
+  return ''
+}
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -279,6 +338,17 @@ export async function getSearchProvider(settings: Partial<AppSettings>): Promise
       if (!apiKey) throw new Error('Brave Search requires an API key. Set one in Settings > Web Search.')
       return new BraveProvider(apiKey)
     }
+    case 'exa': {
+      let apiKey = settings.exaApiKey
+      if (!apiKey) apiKey = process.env.EXA_API_KEY ?? null
+      if (!apiKey) {
+        const { getSecret } = await import('../storage')
+        const secret = await getSecret('exa')
+        apiKey = secret?.value ?? null
+      }
+      if (!apiKey) throw new Error('Exa requires an API key. Set one in Settings > Web Search or set the EXA_API_KEY environment variable.')
+      return new ExaProvider(apiKey)
+    }
     default:
       return new DuckDuckGoProvider()
   }

package/src/lib/server/storage.ts

@@ -1045,6 +1045,7 @@ const APP_SETTINGS_SECRET_FIELDS = [
   'elevenLabsApiKey',
   'tavilyApiKey',
   'braveApiKey',
+  'exaApiKey',
 ] as const
 
 const ENCRYPTED_APP_SETTINGS_KEY = '__encryptedAppSettings'

package/src/types/app-settings.ts

@@ -115,8 +115,10 @@ export interface AppSettings {
   // Theme
   themeHue?: string
   // Web search provider
-  webSearchProvider?: 'duckduckgo' | 'google' | 'bing' | 'searxng' | 'tavily' | 'brave'
+  webSearchProvider?: 'duckduckgo' | 'google' | 'bing' | 'searxng' | 'tavily' | 'brave' | 'exa'
   searxngUrl?: string
+  exaApiKey?: string | null
+  exaApiKeyConfigured?: boolean
   // Task custom field definitions
   taskCustomFieldDefs?: Array<{ key: string; label: string; type: 'text' | 'number' | 'select'; options?: string[] }>
   // OpenClaw sync settings

package/src/views/settings/section-web-search.tsx

@@ -6,6 +6,7 @@ export function WebSearchSection({ appSettings, patchSettings, inputClass }: Set
   const provider = appSettings.webSearchProvider || 'duckduckgo'
   const hasTavilyKey = appSettings.tavilyApiKeyConfigured === true
   const hasBraveKey = appSettings.braveApiKeyConfigured === true
+  const hasExaKey = appSettings.exaApiKeyConfigured === true
 
   return (
     <div className="mb-10">
@@ -30,6 +31,7 @@ export function WebSearchSection({ appSettings, patchSettings, inputClass }: Set
             <option value="searxng">SearXNG (self-hosted, no key required)</option>
             <option value="tavily">Tavily (API key required)</option>
             <option value="brave">Brave Search (API key required)</option>
+            <option value="exa">Exa (API key required)</option>
           </select>
         </div>
 
@@ -82,6 +84,24 @@ export function WebSearchSection({ appSettings, patchSettings, inputClass }: Set
             <p className="text-[11px] text-text-3/60 mt-2">Get your API key from <a href="https://brave.com/search/api/" target="_blank" rel="noopener noreferrer" className="text-accent-bright hover:underline">brave.com/search/api</a></p>
           </div>
         )}
+
+        {provider === 'exa' && (
+          <div>
+            <label className="block font-display text-[11px] font-600 text-text-3 uppercase tracking-[0.08em] mb-2">Exa API Key</label>
+            <input
+              type="password"
+              value={appSettings.exaApiKey || ''}
+              onChange={(e) => patchSettings({ exaApiKey: e.target.value || null })}
+              placeholder={hasExaKey ? 'Stored securely. Enter a new key to replace it.' : 'exa-...'}
+              className={inputClass}
+              style={{ fontFamily: 'inherit' }}
+            />
+            {hasExaKey && (
+              <p className="text-[11px] text-emerald-400/90 mt-1.5">Stored securely. Clear the field and save to remove it.</p>
+            )}
+            <p className="text-[11px] text-text-3/60 mt-2">Get your API key from <a href="https://exa.ai" target="_blank" rel="noopener noreferrer" className="text-accent-bright hover:underline">exa.ai</a>. You can also set the <code className="text-[11px] font-mono text-text-2">EXA_API_KEY</code> environment variable.</p>
+          </div>
+        )}
       </div>
     </div>
   )