feat: add Exa as web_search provider by louiswalsh · Pull Request #31310 · openclaw/openclaw

louiswalsh · 2026-03-02T05:16:50Z

Summary

Problem: OpenClaw has no native Exa search integration — users who want Exa's semantic search must use external workarounds.
Why it matters: Exa provides high-quality semantic search with token-efficient highlights, useful for AI assistant workflows.
What changed: Added Exa as a 6th web_search provider (explicit opt-in only via provider: "exa" config), with highlights-based content retrieval, config types, Zod schema, env var support (EXA_API_KEY), and tests.
What did NOT change (scope boundary): No changes to existing providers, no changes to web_fetch, no auto-detection — Exa is only activated when explicitly configured.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Related Feature: Add Exa as a native web_search provider #20134

User-visible / Behavior Changes

New provider: "exa" option for tools.web.search.provider
New config keys: tools.web.search.exa.apiKey, tools.web.search.exa.numResults (default: 5), tools.web.search.exa.highlightsMaxChars (default: 8000)
New env var: EXA_API_KEY
Tool description changes when Exa is selected: "Search the web using Exa search. Returns structured results with titles, URLs, and highlights."
No changes to default behavior — Brave remains the default provider

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? Yes — new EXA_API_KEY env var / exa.apiKey config, follows same pattern as existing providers
New/changed network calls? Yes — new outbound call to https://api.exa.ai/search with x-exa-integration: "openclaw" header
Command/tool execution surface changed? No
Data access scope changed? No
If any Yes, explain risk + mitigation: API key is marked sensitive in Zod schema (same as all other provider keys). Network call only fires when user explicitly sets provider: "exa". Uses existing withTrustedWebSearchEndpoint wrapper with timeout and abort support.

Repro + Verification

Environment

OS: Linux
Runtime/container: Node.js (vitest)
Model/provider: N/A (unit tests only)
Integration/channel (if any): N/A
Relevant config (redacted): { tools: { web: { search: { provider: "exa", exa: { apiKey: "exa-..." } } } } }

Steps

Set EXA_API_KEY or configure tools.web.search.exa.apiKey
Set tools.web.search.provider: "exa"
Invoke web_search tool with a query

Expected

Returns structured results with title, URL, highlights, published date, author
Results capped at numResults (default 5) with highlights limited to highlightsMaxChars (default 8000)

Actual

Matches expected (verified via unit tests)

Evidence

Failing test/log before + passing after

47 tests passing in web-search.test.ts, 18 in config.web-search-provider.test.ts.

Human Verification (required)

Verified scenarios: All resolver functions (apiKey, numResults, highlightsMaxChars), config validation, auto-detection exclusion, Exa not in provider priority chain
Edge cases checked: Invalid/missing/zero/negative/Infinity/NaN values for numResults and highlightsMaxChars, missing API key fallback to env var
What you did not verify: Live API call to Exa (unit tests mock the network layer)

Compatibility / Migration

Backward compatible? Yes
Config/env changes? Yes — new optional EXA_API_KEY env var and tools.web.search.exa config block
Migration needed? No
If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

How to disable/revert this change quickly: Remove provider: "exa" from config — falls back to default Brave provider
Files/config to restore: N/A (additive change, no existing behavior modified)
Known bad symptoms reviewers should watch for: If EXA_API_KEY is invalid, the tool returns an API error message (same pattern as other providers)

Risks and Mitigations

Risk: Exa API availability/rate limits
- Mitigation: Exa is only used when explicitly configured — no impact on default behavior

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f39bef2311

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-02T05:20:25Z

src/config/zod-schema.agent-runtime.ts

    suppressToolErrorWarnings: z.boolean().optional(),
-    lightContext: z.boolean().optional(),
  })


Restore heartbeat lightContext in config schema

Removing lightContext from HeartbeatSchema breaks existing configs that set defaults.heartbeat.lightContext, because this schema is .strict() and validateConfigObject* rejects unknown keys. The runtime still consumes heartbeat.lightContext (for lightweight heartbeat context), so this change turns a previously valid and used setting into a validation error and can block config loading for users already relying on it.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-02T05:20:25Z

docs/tools/web.md

 2. **Gemini** — `GEMINI_API_KEY` env var or `search.gemini.apiKey` config
 3. **Perplexity** — `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` env var or `search.perplexity.apiKey` config
 4. **Grok** — `XAI_API_KEY` env var or `search.grok.apiKey` config
+5. **Exa** — `EXA_API_KEY` env var or `search.exa.apiKey` config


Correct Exa auto-detection behavior in docs

This section now states Exa is auto-detected from EXA_API_KEY, but the implementation and tests explicitly require provider: "exa" (auto-detection falls back through other providers and then Brave). Users following this doc can set only EXA_API_KEY and still not get Exa, which leads to confusing setup failures; the doc should match the actual resolver behavior.

Useful? React with 👍 / 👎.

greptile-apps · 2026-03-02T05:29:45Z

Greptile Summary

This PR adds Exa as a 6th web search provider with explicit opt-in configuration. The implementation is well-structured and follows established patterns from other providers (Brave, Perplexity, Gemini, Grok, Kimi).

Key changes:

Added Exa provider support in web-search.ts with highlights-based content retrieval
Configuration types and Zod schema validation in types.tools.ts and zod-schema.agent-runtime.ts
Comprehensive test coverage for config resolution and validation
Documentation updates for the new provider
Exa is NOT auto-detected (requires explicit provider: "exa" config)

Issue found:

docs/tools/web.md:242 contains incorrect documentation about Gemini's redirect resolver SSRF policy - states it uses "trusted-network model" (allows private networks) when the code actually uses withStrictWebToolsEndpoint (blocks private networks). This is unrelated to the Exa feature.

Confidence Score: 4/5

Safe to merge after fixing the documentation error about Gemini SSRF policy
Score reflects one factual documentation error (Gemini SSRF policy incorrectly documented) that needs correction. The Exa implementation itself is solid with proper tests, types, validation, and follows existing patterns. The unrelated documentation change should ideally be reverted or fixed.
docs/tools/web.md line 242 needs correction - revert to previous accurate description of Gemini redirect SSRF behavior

_{Last reviewed commit: f39bef2}

greptile-apps

_{6 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

docs/tools/web.md

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1f886eb67

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-02T23:09:18Z

src/agents/tools/web-search.ts

+      numResults: params.exaNumResults ?? DEFAULT_EXA_NUM_RESULTS,
+      highlightsMaxChars: params.exaHighlightsMaxChars ?? DEFAULT_EXA_HIGHLIGHTS_MAX_CHARS,


Honor count argument when using Exa provider

The Exa branch ignores the tool-level count input (and the derived search.maxResults fallback) by always sending numResults from exaNumResults/default 5. In practice, web_search calls like count: 1 or count: 10 with provider: "exa" will still return the configured/default Exa count, which breaks the existing web_search parameter contract for callers that expect per-request result sizing.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3286b5f8a6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/config/zod-schema.agent-runtime.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 801725f441

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

src/agents/tools/web-search.ts

Adds Exa as a 6th web_search provider (explicit opt-in only via provider: "exa" config). Includes config types, Zod schema, highlights- based content retrieval, env var support (EXA_API_KEY), and tests. No changes to existing providers or default behavior.

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

…eading

…Schema for exa.apiKey

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78bfed1dec

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-04T23:48:49Z

src/agents/tools/web-search.ts

+}
+
+function resolveExaApiKey(exa?: ExaSearchConfig): string | undefined {
+  const fromConfig = normalizeApiKey(exa?.apiKey);


Resolve Exa SecretRefs before reading apiKey

resolveExaApiKey normalizes exa.apiKey as a plain string, so a valid SecretRef value gets coerced to empty and the Exa provider fails with missing_exa_api_key. Fresh evidence for re-raising this area: Exa is still absent from the web-search secret resolver paths in src/secrets/runtime-config-collectors-core.ts:284-290 and from the target registry in src/secrets/target-registry-data.ts:666-719, so tools.web.search.exa.apiKey is never resolved before this code executes.

Useful? React with 👍 / 👎.

This reverts commit 257e607.

…rets/schema

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7e5bce9e41

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-04T23:58:43Z

src/secrets/runtime-config-collectors-core.ts

  const paths = [
    "apiKey",
+    "exa.apiKey",


Include exa in provider gating for secret resolution

Adding "exa.apiKey" to this path list without updating the selectedProvider whitelist above means provider: "exa" falls into the selectedProvider === undefined branch, so all web-search provider secret refs are treated as active. In that configuration, stale refs like tools.web.search.grok.apiKey or tools.web.search.kimi.apiKey are now resolved (instead of ignored as inactive), and missing/invalid refs can fail config secret resolution even though only Exa is selected.

Useful? React with 👍 / 👎.

…body

vincentkoc · 2026-03-23T03:59:10Z

Nice work surfacing this early.

I'm closing this as a duplicate of #52617. The Exa provider is now merged through the current bundled-plugin architecture, so this earlier branch is fully superseded by the landed path.

If that overlap looks wrong from your side, tell me what differs and I can re-check it quickly.

openclaw-barnacle bot added docs Improvements or additions to documentation agents Agent runtime and tooling size: M labels Mar 2, 2026

chatgpt-codex-connector bot reviewed Mar 2, 2026

View reviewed changes

greptile-apps bot reviewed Mar 2, 2026

View reviewed changes

docs/tools/web.md Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 2, 2026

View reviewed changes

louiswalsh force-pushed the feat/exa-web-search-clean branch from 04bfb21 to 3286b5f Compare March 3, 2026 05:11

chatgpt-codex-connector bot reviewed Mar 3, 2026

View reviewed changes

src/config/zod-schema.agent-runtime.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 3, 2026

View reviewed changes

src/agents/tools/web-search.ts Outdated Show resolved Hide resolved

louiswalsh mentioned this pull request Mar 4, 2026

feat(web-search): set Exa as default provider via auto-detection (EXA_API_KEY activates Exa) #35062

Open

15 tasks

louiswalsh and others added 5 commits March 4, 2026 15:39

Update docs/tools/web.md

c5a5ba2

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

docs(web): disambiguate Gemini section heading to 'Gemini notes'

3473478

docs(web): rename Exa section heading to 'Exa notes', revert Gemini h…

34fe3b1

…eading

fix(web-search): respect tool-level count for Exa and use SecretInput…

78bfed1

…Schema for exa.apiKey

louiswalsh force-pushed the feat/exa-web-search-clean branch from 801725f to 78bfed1 Compare March 4, 2026 23:40

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

louiswalsh added 3 commits March 4, 2026 15:48

chore: fix formatting (oxfmt)

257e607

Revert "chore: fix formatting (oxfmt)"

94a40d3

This reverts commit 257e607.

fix(web-search): restore lightContext, wrap Exa author, fix count/sec…

7e5bce9

…rets/schema

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

fix(web-search): remove redundant query from Exa highlights contents …

29515a2

…body

github-actions bot mentioned this pull request Mar 5, 2026

🦞 OpenClaw 生态日报 2026-03-05 duanyytop/agents-radar#77

Open

MonkeyLeeT mentioned this pull request Mar 11, 2026

feat(web-search): add Exa as web search provider #32529

Closed

6 tasks

louiswalsh mentioned this pull request Mar 19, 2026

Adding Exa as a web search plugin #50281

Closed

20 tasks

vincentkoc mentioned this pull request Mar 23, 2026

feat(web-search): add Exa as bundled web search plugin #52617

Merged

20 tasks

vincentkoc closed this Mar 23, 2026

		numResults: params.exaNumResults ?? DEFAULT_EXA_NUM_RESULTS,
		highlightsMaxChars: params.exaHighlightsMaxChars ?? DEFAULT_EXA_HIGHLIGHTS_MAX_CHARS,

Uh oh!

Conversation

louiswalsh commented Mar 2, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot commented Mar 2, 2026

Greptile Summary

Confidence Score: 4/5

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

vincentkoc commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants