OpenClaw Exa 搜索插件指南：神经搜索、内容提取与日期过滤的完整配置实战

OpenClaw Exa 搜索插件指南神经搜索、内容提取与日期过滤的完整配置实战【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读本文围绕 OpenClaw 项目中 docs/tools/exa-search.md 这篇官方工具文档展开系统讲解如何将 Exa AI 接入 OpenClaw 的web_search工具链涵盖插件安装、API Key 配置、搜索模式、内容提取、日期过滤、缓存与超时调优并结合仓库内插件实现源码extensions/exa与插件 SDK 源码解释每个参数在底层是如何被解析、校验、发送和缓存的。读完本文你将能够独立完成 Exa 搜索插件的部署与调优并在 Agent 工具调用中精准控制搜索结果的数量、时效、摘要形式与请求超时。Exa 在 OpenClaw 中的定位Exa AIhttps://exa.ai/是 OpenClaw 的一个web_search提供方provider与 Brave、Perplexity 等并列支持三类搜索方式神经搜索neural、关键词搜索keyword与混合/深度搜索hybrid/deep并内置内容提取能力高亮句、正文、AI 摘要。在 OpenClaw 的插件体系中Exa 通过标准 Web Search Provider 契约注册插件入口 extensions/exa/index.ts 调用api.registerWebSearchProvider(createExaWebSearchProvider())完成注册工具的元数据定义在 extensions/exa/src/exa-web-search-provider.shared.tsid: exa、label: Exa Search、envVars: [EXA_API_KEY]。该插件的包名为openclaw/exa-plugin见 extensions/exa/package.json要求宿主版本2026.6.8、插件 API2026.9.2可从 npm 或 ClawHub 安装。安装插件在 OpenClaw CLI 中执行openclaw plugins install openclaw/exa-plugin openclaw gateway restart安装完成后重启 Gateway 使插件生效。插件清单 extensions/exa/openclaw.plugin.json 中activation.onStartup为false即插件不会在启动时主动加载而是按需惰性加载——这也是 extensions/exa/src/exa-web-search-provider.ts 中通过createLazyRuntimeModule(() import(./exa-web-search-provider.runtime.js))延迟加载运行时模块的原因冷启动阶段不会加载 Exa 运行时代码只有首次调用web_search时才动态引入。获取 API Key在 https://exa.ai/ 注册账号并在控制台生成 API Key形如exa-...。将 Key 写入 Gateway 环境变量EXA_API_KEY对于 gateway 安装方式放入~/.openclaw/.env参见 Env vars 说明。或者通过交互式配置命令写入配置openclaw configure --section web底层实现中API Key 的解析优先级在 extensions/exa/src/exa-web-search-provider.runtime.ts 的resolveExaApiKey中体现先读取插件配置plugins.entries.exa.config.webSearch.apiKey未设置时回退到环境变量EXA_API_KEY两者均缺失时返回missing_exa_api_key错误提示。测试用例extensions/exa/src/exa-web-search-provider.test.ts也是直接以webSearch: { apiKey: exa-test-key }的插件配置形式构造工具进行验证的。配置插件在 OpenClaw 配置文件中加入如下片段JSON5 格式{ plugins: { entries: { exa: { config: { webSearch: { apiKey: exa-..., // 可选设置了 EXA_API_KEY 时可不填 baseUrl: https://api.exa.ai, // 可选OpenClaw 会自动补全 /search }, }, }, }, }, tools: { web: { search: { provider: exa, }, }, }, }plugins.entries.exa.config.webSearch.apiKey插件级凭据优先级高于环境变量源码见上。tools.web.search.provider显式指定web_search使用 Exa若省略该项OpenClaw 会按autoDetectOrderExa 为 65见 exa-web-search-provider.shared.ts对已配置凭据的提供方做自动探测。插件清单 openclaw.plugin.json 中的configSchema严格约束了配置结构webSearch对象下仅允许apiKey字符串或对象与baseUrl字符串两个字段additionalProperties: false表示传入未知字段会直接报错。Base URL 覆盖设置plugins.entries.exa.config.webSearch.baseUrl可将 Exa 搜索请求路由到兼容代理或替代端点。底层规范化逻辑在 exa-web-search-provider.runtime.ts 的resolveExaSearchEndpoint中实现未配置时使用内置默认端点https://api.exa.ai/search常量定义裸主机名不带协议会自动补https://前缀仅允许http:/https:协议其他协议返回invalid_base_url错误路径末尾若不以/search结尾会自动追加/search并清理多余斜杠最终端点会参与搜索缓存键buildExaCacheKey中endpoint是键的一部分因此不同端点的结果永远不会互相共享缓存。工具参数web_search工具向 Exa 传递的参数定义在 exa-web-search-provider.ts 的ExaSearchSchema中additionalProperties: false会拒绝未声明参数参数类型必填默认说明querystring是—搜索查询串countnumber否5或tools.web.search.maxResults返回结果数范围 1–100受 Exa 搜索类型上限约束typestring否auto搜索模式auto/neural/fast/deep/deep-reasoning/instantfreshnessstring否—时间过滤day/week/month/year不能与date_after/date_before同时使用date_afterstring否—仅返回此日期YYYY-MM-DD之后发布的结果date_beforestring否—仅返回此日期之前发布的结果contentsobject否{ highlights: true }内容提取选项见下节参数校验逻辑在 exa-web-search-provider.runtime.tsquery通过readStringParam(params, query, { required: true })强制必填type不属于合法枚举时静默回退为autoL430-L433count经readPositiveIntegerParam校验并夹取上限EXA_MAX_SEARCH_COUNT 100L32未传时回退到searchConfig?.maxResults再回退到 SDK 默认值DEFAULT_SEARCH_COUNT 5见 src/agents/tools/web-search-provider-common.tsfreshness非法值返回invalid_freshness错误freshness与date_after/date_before同时出现时返回conflicting_time_filters错误date_after/date_before通过parseIsoDateRange校验YYYY-MM-DD格式及先后顺序非法时返回对应错误。内容提取contents不传contents时Exa 默认使用{ highlights: true }见 L335因此结果默认包含关键句摘录。手动控制示例await web_search({ query: transformer architecture explained, type: neural, contents: { text: true, // 全文 highlights: { numSentences: 3 }, // 关键句 summary: true, // AI 摘要 }, });选项类型说明textboolean \| { maxCharacters }提取整页正文可用maxCharacters限制字符数highlightsboolean \| { maxCharacters, query, numSentences, highlightsPerUrl }提取关键句numSentences控制句数query指定聚焦问题highlightsPerUrl控制每 URL 高亮条数summaryboolean \| { query }生成 AI 摘要可用query引导摘要关注点底层解析在 exa-web-search-provider.runtime.ts 的parseExaContents中完成contents必须是对象且只能包含text/highlights/summary三个字段未知字段返回invalid_contents每个字段可以是布尔值也可以是对象且各字段的合法子字段被严格限定highlights允许 4 个子字段text/summary各仅 1 个所有数值子字段必须是正整数否则报错。结果描述description的解析顺序为高亮highlights优先 → 摘要summary次之 → 全文text兜底见 resolveExaDescription。同时Exa API 返回的原始highlightScores数值数组与summary字段会被原样保留在结果中L530-L535并额外解析出siteName基于 URL 推断与publishedDate。搜索模式模式说明auto由 Exa 自动选择最优模式默认neural语义/含义层面的神经搜索fast快速关键词搜索deep深度搜索deep-reasoning带推理的深度搜索instant最快响应这些枚举值同时定义在 exa-web-search-provider.runtime.ts 与工具 Schema 中请求时会原样写入 Exa API 的type字段。请求的组装与发送细节runExaSearchexa-web-search-provider.runtime.ts展示了请求体的完整组装方式可作为排查问题时的参考// 请求体结构发送到 {baseUrl}/searchPOST JSON { query: …, numResults: 5, // count 映射为 numResults type: neural, // 搜索模式 contents: { highlights: true }, // 未显式指定时默认 // startPublishedDate / endPublishedDate 由 freshness 或 date_after/date_before 生成 }几个值得注意的实现细节请求头Accept: application/json、Content-Type: application/json、x-api-key: key并附加x-exa-integration: openclaw标识请求来源freshness 的时间换算resolveFreshnessStartDateday 当前 UTC 时间往前 1 天week 往前 7 天month 往前 1 个自然月并处理月末天数与 29/30/31 日等边界取当前日与目标月末较小值year 往前 1 年统一转成 ISO 时间字符串写入startPublishedDatedate_after/date_before则直接映射为startPublishedDate/endPublishedDate响应安全边界成功 JSON 最多读取 16 MiBEXA_SEARCH_JSON_MAX_BYTES错误响应体最多读取 8 KiB防止异常/恶意端点无界流式写入内存L33-L37外部内容包装结果中的title、description、summary均通过wrapWebContent标记为不可信外部内容externalContent: { untrusted: true, wrapped: true }与 OpenClaw 对所有 Web 搜索提供方的一致处理保持一致。缓存与超时调优Exa 结果默认在本地缓存 15 分钟。缓存键由buildExaCacheKeyL382-L405构造包含提供方标识exa、端点、搜索模式、查询串、count、freshness、日期范围与序列化后的contents。读写流程为请求前readCachedSearchPayload(cacheKey, cacheTtlMs)命中则直接返回否则发起请求、写入writeCachedSearchPayload。全局调优配置对包括 Exa 在内的所有web_search提供方生效完整示例见 docs/tools/web.md{ tools: { web: { search: { provider: exa, maxResults: 5, // count 未指定时的默认结果数 timeoutSeconds: 30, // 请求超时默认 30s cacheTtlMinutes: 15 // 缓存 TTL默认 15 分钟 } } } }cacheTtlMinutes: 0可完全绕过缓存读写较短的 TTL 限制复用时长更长的 TTL 不会延长已有条目的原始过期时间见 docs/tools/web.md 中说明。默认常量定义在 src/agents/tools/web-shared.tsDEFAULT_TIMEOUT_SECONDS 30、DEFAULT_CACHE_TTL_MINUTES 15SDK 侧resolveSearchTimeoutSeconds/resolveSearchCacheTtlMs在 src/agents/tools/web-search-provider-common.ts 中读取配置并回退默认值。取消与并发安全插件对请求取消AbortSignal有完备的处理测试用例exa-web-search-provider.test.ts覆盖了两个关键场景发送前已取消execute入口处context?.signal?.throwIfAborted()exa-web-search-provider.ts会立即抛出调用方取消原因测试断言此时fetch未被调用、结果也不会被写入缓存请求进行中被取消withTrustedWebSearchEndpoint将 AbortSignal 透传给底层 fetch取消时保留调用方的原始错误原因测试名aborts the guarded Exa request without losing the callers reason即验证此行为。此外响应解析完成后还有一次signal?.throwIfAborted()runtime L514确保取消的请求不会把结果写入缓存。常见错误与排查结合源码中的错误负载设计常见失败场景及对应错误码错误触发条件处理建议missing_exa_api_key插件配置与环境变量均无 Key设置EXA_API_KEY或plugins.entries.exa.config.webSearch.apiKeyinvalid_base_urlbaseUrl非合法 http(s) URL检查baseUrl是否带非法协议或无法解析invalid_freshnessfreshness非day/week/month/year修正枚举值conflicting_time_filtersfreshness与date_after/date_before同时使用二选一invalid_contentscontents含未知字段或子字段类型错误参照上文字段表修正HTTP 非 2xxExa 端返回错误错误详情最多 8 KiB会随Exa API error (status)一起抛出可用于定位配额、鉴权问题关联阅读Web Search 总览全部提供方与自动探测机制Brave Search支持国家/语言过滤的结构化结果Perplexity Search支持域名过滤的结构化结果Exa 插件完整实现extensions/exa入口 index.ts、运行时 exa-web-search-provider.runtime.ts、Schema exa-web-search-provider.ts、测试 exa-web-search-provider.test.ts【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考