Adding Exa as a web search plugin by louiswalsh · Pull Request #50281 · openclaw/openclaw

louiswalsh · 2026-03-19T06:50:06Z

Summary

Problem: OpenClaw has no native Exa web search provider — users must rely on a community plugin for Exa integration.
Why it matters: Exa is a neural search engine optimized for AI applications; bundling it makes it a zero-config option for OpenClaw users with an Exa API key.
What changed: Added extensions/exa/ as a new bundled web search provider plugin (4 new files), registered it in BUNDLED_WEB_SEARCH_PLUGIN_IDS, and updated the contract registry + test expectations.
What did NOT change (scope boundary): No modifications to core config types, Zod schemas, existing providers, or the plugin SDK. Only additive changes to shared registration files (+9 lines across 5 existing files).

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

New exa web search provider available when EXA_API_KEY is set or configured via openclaw configure --section web.
Exa appears last in auto-detect order (65, after Firecrawl at 60) — it will only auto-select if no other provider keys are configured.
New config path: plugins.entries.exa.config.webSearch.apiKey.

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No — follows existing readConfiguredSecretString / readProviderEnvValue pattern
New/changed network calls? Yes — POST to https://api.exa.ai/search with x-api-key header
Command/tool execution surface changed? No
Data access scope changed? No
If any Yes, explain risk + mitigation: Network call is gated behind API key presence. Request goes through withTrustedWebSearchEndpoint (same as all other providers). No secrets are logged or exposed. The x-exa-integration: "openclaw" header is sent for usage tracking only.

Repro + Verification

Environment

OS: Linux (Ubuntu)
Runtime/container: Node.js >=22.16.0
Model/provider: N/A (web search provider, not model provider)
Integration/channel (if any): Exa Search API
Relevant config (redacted): EXA_API_KEY=exa-***

Steps

Set EXA_API_KEY environment variable
Run openclaw configure --section web and select Exa, or let auto-detect pick it up
Use web_search tool — should route through Exa

Expected

Search returns titles, URLs, and highlighted snippets from Exa's neural search

Actual

(Verified via unit test suite — all 599 plugin tests pass)

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

All 599 plugin tests pass (pnpm vitest run src/plugins/). Lint clean (oxlint --type-aware: 0 warnings, 0 errors).

Human Verification (required)

Verified scenarios: Full plugin test suite (599 tests), lint, registration in bundled IDs, contract registry assertions, auto-detect ordering.
Edge cases checked: Missing API key returns descriptive error with docs link. Empty/malformed results handled via fallback defaults.
What you did not verify: Live API call to Exa (no API key available in test environment). UI rendering of Exa in provider selection dropdown.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? Yes — new optional EXA_API_KEY env var recognized
Migration needed? No
If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

How to disable/revert this change quickly: Remove "exa" from BUNDLED_WEB_SEARCH_PLUGIN_IDS in src/plugins/bundled-web-search.ts, or set plugins.entries.exa.enabled: false in config.
Files/config to restore: src/plugins/bundled-web-search.ts (remove "exa" from array)
Known bad symptoms reviewers should watch for: Provider selection failing when EXA_API_KEY is set but Exa API is unreachable.

Risks and Mitigations

Risk: Exa API endpoint becomes unavailable or changes response format.
- Mitigation: Provider is last in auto-detect order (65); users with other keys configured are unaffected. Response parsing handles missing fields with safe defaults.

Co-Authored-By: Louis Walsh <[email protected]>

greptile-apps · 2026-03-19T06:53:20Z

Greptile Summary

This PR adds Exa as a new bundled web search provider, following the exact same patterns established by Brave, Firecrawl, and other existing bundled providers — additive changes only, no modifications to core types or schemas.

Changes:

New extensions/exa/ plugin (4 files): provider implementation, plugin entry point, manifest, and package.json.
"exa" registered in BUNDLED_WEB_SEARCH_PLUGIN_IDS (alphabetical order) and in the contract registry with a test credential.
autoDetectOrder: 65 places Exa last in auto-detect priority — users with any other provider key configured are unaffected.
Test expectations updated across 3 test files to reflect the new provider.

Implementation quality: The provider correctly uses withTrustedWebSearchEndpoint, readConfiguredSecretString/readProviderEnvValue for secret resolution, the standard cache key/payload pattern, and the same createTool/pluginConfig merge logic as Brave. The API error body is surfaced in the thrown error message, and missing-key errors return a structured object with a docs link rather than throwing.

One nit found: published: entry.publishedDate ?? undefined on line 90 is redundant — since publishedDate is already string | undefined, the ?? undefined fallback is a no-op and can be removed.

Confidence Score: 5/5

This PR is safe to merge — purely additive changes with no modifications to existing code paths.
All changes are additive: a new plugin directory, a one-line addition to the bundled ID list, a one-import + one-entry addition to the contract registry, and updated test expectations. The implementation faithfully follows existing provider patterns (withTrustedWebSearchEndpoint, secret resolution, caching, payload structure). The only finding is a trivial redundant expression (?? undefined) with no runtime impact. The live API has not been verified but that is disclosed in the PR and is outside the unit-test scope.
No files require special attention.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: extensions/exa/src/exa-web-search-provider.ts
Line: 90

Comment:
**Redundant `?? undefined` fallback**

`entry.publishedDate` is already typed as `string | undefined`, so appending `?? undefined` is a no-op — if the value is already `undefined`, the nullish coalescing just returns `undefined` again. The field can simply be assigned directly, matching how other result fields like `siteName` handle the same pattern via `|| undefined` (which additionally coerces empty string to `undefined`).

```suggestion
          published: entry.publishedDate,
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "refactor: move exa t..."}

extensions/exa/src/exa-web-search-provider.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a3720f976

ℹ️ 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".

extensions/exa/src/exa-web-search-provider.ts

Co-Authored-By: Louis Walsh <[email protected]>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 82afdc5bcf

ℹ️ 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-19T07:07:48Z

extensions/exa/src/exa-web-search-provider.ts

+    signupUrl: "https://exa.ai/",
+    docsUrl: "https://docs.exa.ai/",
+    autoDetectOrder: 65,
+    credentialPath: "plugins.entries.exa.config.webSearch.apiKey",


Register Exa's credential path with secret tooling

This provider advertises plugins.entries.exa.config.webSearch.apiKey, but the static secret registry was not updated for that path (src/secrets/target-registry-data.ts still only lists the existing Brave/Google/xAI/Moonshot/Perplexity/Firecrawl web-search entries). Because discoverConfigSecretTargets() drives both openclaw secrets configure (src/secrets/configure-plan.ts:88) and openclaw secrets audit (src/secrets/audit.ts:215), an Exa key stored at the new plugin path is invisible to those workflows: operators cannot manage it through the configure flow, manual plans using that target type fail validation, and audits miss plaintext Exa keys entirely.

Useful? React with 👍 / 👎.

V-Gutierrez · 2026-03-21T15:10:35Z

Hey @louiswalsh 👋 — I implemented the same Exa integration as a plugin extension in #49319 (following the firecrawl/moonshot pattern). Happy to help review, test, or merge efforts if it makes sense to consolidate. Let me know!

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

Thanks for pushing this.

I'm closing this as a duplicate of #52617. This was targeting the same bundled Exa plugin outcome, and the merged PR now covers that path on top of current main.

If you think there is still a gap in the landed version, point me to it and I can reopen review right away.

louiswalsh and others added 3 commits March 19, 2026 06:28

feat(web-search): add Exa as bundled web search provider

3b1f73f

Co-Authored-By: Louis Walsh <[email protected]>

refactor: remove date range filtering for barebones provider

a1acd75

Co-Authored-By: Louis Walsh <[email protected]>

refactor: move exa to last in auto-detect order (65)

5a3720f

Co-Authored-By: Louis Walsh <[email protected]>

openclaw-barnacle bot added the size: M label Mar 19, 2026

greptile-apps bot reviewed Mar 19, 2026

View reviewed changes

extensions/exa/src/exa-web-search-provider.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 19, 2026

View reviewed changes

extensions/exa/src/exa-web-search-provider.ts Show resolved Hide resolved

louiswalsh and others added 2 commits March 19, 2026 06:56

fix: remove redundant ?? undefined fallback on publishedDate

3c7d98a

Co-Authored-By: Louis Walsh <[email protected]>

Merge branch 'main' into feat/exa-web-search-plugin

82afdc5

chatgpt-codex-connector bot reviewed Mar 19, 2026

View reviewed changes

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Adding Exa as a web search plugin#50281

Adding Exa as a web search plugin#50281
louiswalsh wants to merge 5 commits intoopenclaw:mainfrom
exa-labs:feat/exa-web-search-plugin

louiswalsh commented Mar 19, 2026

Uh oh!

greptile-apps bot commented Mar 19, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 19, 2026

Uh oh!

V-Gutierrez commented Mar 21, 2026

Uh oh!

vincentkoc commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

louiswalsh commented Mar 19, 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)

Review Conversations

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

greptile-apps bot commented Mar 19, 2026

Greptile Summary

Confidence Score: 5/5

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 19, 2026

Choose a reason for hiding this comment

Uh oh!

V-Gutierrez commented Mar 21, 2026

Uh oh!

vincentkoc commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants