OpenClaw Perplexity 插件实战指南将 Perplexity Search 接入 web_search 的安装、配置与底层原理【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 的 Perplexity 插件openclaw/perplexity-plugin将 Perplexity Search API 以web_search提供者的形式接入 Gateway同时兼容历史遗留的 Perplexity Sonar / OpenRouter 接入方式。本文以插件参考文档 docs/plugins/reference/perplexity.md 为骨架结合官方使用文档 docs/tools/perplexity-search.md 与插件源码完整覆盖插件分发、安装、双传输模式选路、凭证配置、工具参数与故障排查帮助读者在 OpenClaw 中稳定启用基于 Perplexity 的结构化网页搜索。插件概览与分发Perplexity 插件为 OpenClaw 提供网页搜索提供者web search provider能力其核心契约声明在插件的 openclaw.plugin.json 中contracts.webSearchProviders注册了perplexity提供者 ID且插件默认不在启动时激活activation.onStartup: false由 web_search 工具按需加载。包名openclaw/perplexity-plugin安装途径npm 或 ClawHub两种路由均可安装同一份插件npmopenclaw/perplexity-pluginClawHubclawhub:openclaw/perplexity-plugin对外契约SurfacewebSearchProviders版本约束插件清单声明minHostVersion: 2026.6.8、pluginApi: 2026.9.3安装时 OpenClaw 会据此校验宿主机版本见 extensions/perplexity/package.json插件还通过setup.providers声明其依赖的环境变量PERPLEXITY_API_KEY与OPENROUTER_API_KEY并在 UI 配置提示uiHints中为webSearch.apiKey敏感字段、占位符pplx-...、webSearch.baseUrl、webSearch.model提供了表单级帮助文本详见 extensions/perplexity/openclaw.plugin.json。双传输模式Search API 与 Sonar/OpenRouter 兼容路径Perplexity 插件最核心的设计是一套配置、两种传输方式transport这是理解后续所有参数行为的前提。源码 perplexity-web-search-provider.shared.ts 中定义了PerplexityTransport search_api | chat_completions选路逻辑如下条件传输方式返回形态使用直接 Perplexity 密钥pplx-...且未显式配置baseUrl/modelsearch_api结构化结果列表title、url、snippet对应 web_search 的kind: results显式配置了plugins.entries.perplexity.config.webSearch.baseUrl或modelchat_completionsAI 综合答案 引用citations对应kind: answer使用OPENROUTER_API_KEY或sk-or-...密钥chat_completions同上走 OpenRouter 兼容路径密钥前缀推断与默认端点resolvePerplexityRuntime与inferPerplexityBaseUrlFromApiKey共同实现端点推断密钥以pplx-开头 → 推断为 Perplexity 直连默认端点https://api.perplexity.aiSearch 端点https://api.perplexity.ai/search密钥以sk-or-开头 → 推断为 OpenRouter默认端点https://openrouter.ai/api/v1默认模型perplexity/sonar-pro无法识别前缀的企业级密钥在源码测试中也会按直连路径处理只要显式设置了baseUrl或model即hasPerplexityLegacyOverride为真或最终解析出的baseUrl主机名不是api.perplexity.aiisDirectPerplexityBaseUrl一律切到chat_completions。一个容易混淆的细节有测试用例佐证即使显式把baseUrl设成https://api.perplexity.ai由于此时存在 legacy override插件仍会走chat_completions请求打到/chat/completions并把模型名中多余的perplexity/前缀剥离后提交resolvePerplexityRequestModel。这一点与官方文档“设置了 baseUrl / model 即切换到 Sonar chat-completions 兼容路径”的描述完全一致。凭证解析顺序resolvePerplexityApiKey按如下优先级解析密钥见 perplexity-web-search-provider.runtime.ts配置项plugins.entries.perplexity.config.webSearch.apiKey支持 SecretRef 对象环境变量PERPLEXITY_API_KEY环境变量OPENROUTER_API_KEY均未配置 → 返回source: none执行时抛出missing_perplexity_api_key错误。环境变量来源还会影响端点选择PERPLEXITY_API_KEY环境变量强制走 Perplexity 直连端点OPENROUTER_API_KEY环境变量强制走 OpenRouter 端点——这与“密钥前缀推断”相互独立、且优先级更高测试用例native environment source ahead of key prefix与OpenRouter environment source ahead of key prefix验证了这一点。安装插件安装官方插件并重启 Gatewayopenclaw plugins install openclaw/perplexity-plugin openclaw gateway restart安装完成后通过openclaw configure --section web或直接编辑~/.openclaw/openclaw.json完成配置见下文。插件自带的 README 提供了相同的安装指引extensions/perplexity/README.md。获取并配置 API Key获取 Perplexity API Key在 Perplexity 官方控制台的 API 设置页创建账号并生成 API key插件源码中的signupUrl字段即指向该页面将密钥写入 OpenClaw 配置或设置到 Gateway 进程环境中。配置位置一配置文件运行openclaw configure --section web后密钥会存储在~/.openclaw/openclaw.json的plugins.entries.perplexity.config.webSearch.apiKey字段。该字段类型为string | object即既可直接填写明文也可传入 SecretRef 对象交给 OpenClaw 的密钥系统解析。配置位置二环境变量在 Gateway 进程环境中设置PERPLEXITY_API_KEY或OPENROUTER_API_KEY。对于以 gateway 方式安装的场景请写入~/.openclaw/.env或服务管理器的环境配置环境变量的加载规则参见 docs/help/faq.md。启动期快速失败Fast Fail官方文档明确如果配置了provider: perplexity但 Perplexity 密钥的 SecretRef 无法解析且没有环境变量兜底Gateway 启动 / 重载会快速失败而不是带着无效配置静默运行。这一行为让密钥缺失在配置阶段即暴露避免运行期才报错。配置示例方式一原生 Perplexity Search API结构化结果{ plugins: { entries: { perplexity: { config: { webSearch: { apiKey: pplx-..., }, }, }, }, }, tools: { web: { search: { provider: perplexity, }, }, }, }方式二OpenRouter / Sonar 兼容路径AI 综合答案如果你此前已在使用 OpenRouter 上的 Perplexity Sonar可以保留provider: perplexity然后二选一在 Gateway 环境设置OPENROUTER_API_KEY或在plugins.entries.perplexity.config.webSearch.apiKey中存放sk-or-...密钥。可选兼容控制项plugins.entries.perplexity.config.webSearch.baseUrl默认https://openrouter.ai/api/v1plugins.entries.perplexity.config.webSearch.model默认perplexity/sonar-pro{ plugins: { entries: { perplexity: { config: { webSearch: { apiKey: openrouter-api-key, baseUrl: https://openrouter.ai/api/v1, model: perplexity/sonar-pro, }, }, }, }, }, tools: { web: { search: { provider: perplexity, }, }, }, }提示tools.web.search.provider会与插件清单声明的提供者 ID 做严格校验拼写错误如brvae会在配置校验阶段直接失败而不是静默回退到自动检测。当未显式设置provider时Perplexity 在自动检测顺序中排第 6 位autoDetectOrder: 50只要其密钥可解析即会被自动选中详见 docs/tools/web.md。web_search 工具参数详解以下参数适用于原生 Perplexity Search API 路径参数类型默认值说明querystring必填搜索查询语句countnumber5返回结果条数1-10countrystring—2 字母 ISO 国家代码如US、DElanguagestring—ISO 639-1 语言代码如en、de、frfreshnessday \| week \| month \| year—时间过滤day表示 24 小时内date_afterstring—仅返回此日期之后发布的结果YYYY-MM-DDdate_beforestring—仅返回此日期之前发布的结果YYYY-MM-DDdomain_filterstring[]—域名白名单 / 黑名单数组最多 20 个max_tokensnumber25000总内容 token 预算最大 1000000max_tokens_per_pagenumber2048单页 token 上限调用示例// 按国家与语言搜索 await web_search({ query: renewable energy, country: DE, language: de, }); // 近期结果过去一周 await web_search({ query: AI news, freshness: week, }); // 日期区间搜索 await web_search({ query: AI developments, date_after: 2024-01-01, date_before: 2024-06-30, }); // 域名过滤白名单 await web_search({ query: climate research, domain_filter: [nature.com, science.org, .edu], }); // 域名过滤黑名单 - 使用 - 前缀 await web_search({ query: product reviews, domain_filter: [-reddit.com, -pinterest.com], }); // 更充分的内容抽取 await web_search({ query: detailed AI research, max_tokens: 50000, max_tokens_per_page: 4096, });域名过滤规则每次请求最多 20 个域名不允许在同一请求中混用白名单与黑名单条目黑名单条目使用-前缀如[-reddit.com]白名单条目不带前缀。源码在 perplexity-web-search-provider.runtime.ts 中同步实现了这三条规则混用返回invalid_domain_filter提示 “cannot mix allowlist and denylist entries”超过 20 个同样返回该错误码。兼容路径下的参数差异在 Sonar / OpenRouter 兼容路径chat_completions下仅接受query、count、freshness三个参数count只是兼容性占位——响应仍然是“单条综合答案 引用”而非 N 条结果列表仅 Search API 支持的过滤参数country、language、date_after、date_before、domain_filter、max_tokens、max_tokens_per_page会返回显式错误对应错误码依次为unsupported_country、unsupported_language、unsupported_date_filter、unsupported_domain_filter、unsupported_content_budget错误信息会提示“仅原生 Perplexity Search API 路径支持请移除 baseUrl/model 覆盖或改用直接 PERPLEXITY_API_KEY”。底层实现请求体、时间过滤与缓存原生 Search API 的请求字段映射插件将工具参数映射为 Perplexity Search 官方字段runPerplexitySearchApi工具参数请求体字段queryquerycountmax_resultscountrycountrydomain_filtersearch_domain_filterfreshnesssearch_recency_filterlanguagesearch_language_filterdate_aftersearch_after_date_filterdate_beforesearch_before_date_filtermax_tokensmax_tokensmax_tokens_per_pagemax_tokens_per_page请求打到https://api.perplexity.ai/searchPOST携带Authorization: Bearer key等请求头。日期会经isoToPerplexityDate转换为 Perplexity 期望的M/D/YYYY格式——测试用例确认date_after: 2024-01-01会以search_after_date_filter: 1/1/2024的形式进入请求体见 perplexity-web-search-provider.test.ts。chat_completions 路径请求打到baseUrl/chat/completionsbody 为{ model, messages: [{ role: user, content: query }] }若传了freshness则额外带上search_recency_filter。响应解析优先取顶层citations数组否则回退遍历choices[].message.annotations中type url_citation的条目去重后作为引用输出。若响应没有最终答案缺choices或 content 为空白插件会报错提示“重试或换一个搜索提供者”且不会缓存失败结果。参数校验优先级工具执行时的校验顺序在源码中是有意排列的测试用例preserves provider validation precedence完整记录了优先级兼容路径下不支持的原生参数按 country → language → date → domain → budget 顺序先于其他校验freshness必须是day/week/month/year否则invalid_freshnesslanguage必须是 2 字母 ISO 639-1 代码否则invalid_languagefreshness与date_after/date_before不能同时使用否则conflicting_time_filters日期必须是YYYY-MM-DD且date_after早于date_before否则invalid_date/invalid_date_rangecount必须是 1-10 的整数max_tokens必须是 1-1000000 的正整数max_tokens_per_page必须是正整数。结果缓存缓存键由 provider、transport、baseUrl、model、query、count 及全部过滤参数联合构成buildSearchCacheKey默认缓存 15 分钟可通过tools.web.search.cacheTtlMinutes配置调整设为0可完全绕过缓存读写注意count只有在原生路径下才进入缓存维度——因为兼容路径返回的是单条答案count不参与上游请求测试用例uses count as a cache dimension only when ... sends it upstream验证了两种路径的缓存行为差异缓存命中时返回的 payload 带有cached: true标记。安全与健壮性所有外发请求经withTrustedWebSearchEndpoint走 OpenClaw 的受保护 fetch 路径网络范围仅限当前提供者自身主机名SSRF 相关防护由核心层的 web 工具策略统一管控见 docs/tools/web.md返回结果统一通过wrapWebContent包装并标记externalContent: { untrusted: true, source: web_search, provider: perplexity, wrapped: true }作为不可信内容的信任边界标记HTTP 错误保留状态码与受控诊断信息且会对反射回显的请求凭证做脱敏如401错误中的密钥被替换为***测试用例redacts reflected request credentials覆盖原生与兼容两条路径支持调用方通过AbortSignal取消请求发起前检查预取消不发起请求请求进行中也会传播取消信号测试用例覆盖了 pre-canceled 与 in-flight cancellation 两种场景。常见错误与排查错误码 / 现象原因处理方式missing_perplexity_api_key未配置任何密钥设置PERPLEXITY_API_KEY/OPENROUTER_API_KEY环境变量或配置plugins.entries.perplexity.config.webSearch.apiKey若不想配置搜索密钥可改用web_fetch抓取指定 URL 或用 browser 工具处理交互页面unsupported_country/unsupported_language/unsupported_date_filter/unsupported_domain_filter/unsupported_content_budget在 chat_completions 兼容路径使用了原生参数移除baseUrl/model覆盖或改用直接PERPLEXITY_API_KEY走原生路径invalid_freshnessfreshness不是day/week/month/year修正取值conflicting_time_filters同时使用freshness与date_after/date_before二选一invalid_date/invalid_date_range日期格式错误或区间颠倒使用YYYY-MM-DD且保证date_after date_beforeinvalid_domain_filter混用白名单与黑名单或超过 20 个域名统一使用正条目白名单或全部加-前缀黑名单且不超过 20 个Gateway 启动 / 重载快速失败provider: perplexity已配置但 SecretRef 无法解析且无环境变量兜底补齐密钥配置后重载相关文档Perplexity 使用指南本文的权威配置来源Web 搜索总览全部提供者、自动检测顺序与结果归一化形态插件参考文档插件源码目录含运行时实现与完整测试套件适合深入阅读【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw Perplexity 插件实战指南：将 Perplexity Search 接入 web_search 的安装、配置与底层原理
OpenClaw Perplexity 插件实战指南将 Perplexity Search 接入 web_search 的安装、配置与底层原理【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 的 Perplexity 插件openclaw/perplexity-plugin将 Perplexity Search API 以web_search提供者的形式接入 Gateway同时兼容历史遗留的 Perplexity Sonar / OpenRouter 接入方式。本文以插件参考文档 docs/plugins/reference/perplexity.md 为骨架结合官方使用文档 docs/tools/perplexity-search.md 与插件源码完整覆盖插件分发、安装、双传输模式选路、凭证配置、工具参数与故障排查帮助读者在 OpenClaw 中稳定启用基于 Perplexity 的结构化网页搜索。插件概览与分发Perplexity 插件为 OpenClaw 提供网页搜索提供者web search provider能力其核心契约声明在插件的 openclaw.plugin.json 中contracts.webSearchProviders注册了perplexity提供者 ID且插件默认不在启动时激活activation.onStartup: false由 web_search 工具按需加载。包名openclaw/perplexity-plugin安装途径npm 或 ClawHub两种路由均可安装同一份插件npmopenclaw/perplexity-pluginClawHubclawhub:openclaw/perplexity-plugin对外契约SurfacewebSearchProviders版本约束插件清单声明minHostVersion: 2026.6.8、pluginApi: 2026.9.3安装时 OpenClaw 会据此校验宿主机版本见 extensions/perplexity/package.json插件还通过setup.providers声明其依赖的环境变量PERPLEXITY_API_KEY与OPENROUTER_API_KEY并在 UI 配置提示uiHints中为webSearch.apiKey敏感字段、占位符pplx-...、webSearch.baseUrl、webSearch.model提供了表单级帮助文本详见 extensions/perplexity/openclaw.plugin.json。双传输模式Search API 与 Sonar/OpenRouter 兼容路径Perplexity 插件最核心的设计是一套配置、两种传输方式transport这是理解后续所有参数行为的前提。源码 perplexity-web-search-provider.shared.ts 中定义了PerplexityTransport search_api | chat_completions选路逻辑如下条件传输方式返回形态使用直接 Perplexity 密钥pplx-...且未显式配置baseUrl/modelsearch_api结构化结果列表title、url、snippet对应 web_search 的kind: results显式配置了plugins.entries.perplexity.config.webSearch.baseUrl或modelchat_completionsAI 综合答案 引用citations对应kind: answer使用OPENROUTER_API_KEY或sk-or-...密钥chat_completions同上走 OpenRouter 兼容路径密钥前缀推断与默认端点resolvePerplexityRuntime与inferPerplexityBaseUrlFromApiKey共同实现端点推断密钥以pplx-开头 → 推断为 Perplexity 直连默认端点https://api.perplexity.aiSearch 端点https://api.perplexity.ai/search密钥以sk-or-开头 → 推断为 OpenRouter默认端点https://openrouter.ai/api/v1默认模型perplexity/sonar-pro无法识别前缀的企业级密钥在源码测试中也会按直连路径处理只要显式设置了baseUrl或model即hasPerplexityLegacyOverride为真或最终解析出的baseUrl主机名不是api.perplexity.aiisDirectPerplexityBaseUrl一律切到chat_completions。一个容易混淆的细节有测试用例佐证即使显式把baseUrl设成https://api.perplexity.ai由于此时存在 legacy override插件仍会走chat_completions请求打到/chat/completions并把模型名中多余的perplexity/前缀剥离后提交resolvePerplexityRequestModel。这一点与官方文档“设置了 baseUrl / model 即切换到 Sonar chat-completions 兼容路径”的描述完全一致。凭证解析顺序resolvePerplexityApiKey按如下优先级解析密钥见 perplexity-web-search-provider.runtime.ts配置项plugins.entries.perplexity.config.webSearch.apiKey支持 SecretRef 对象环境变量PERPLEXITY_API_KEY环境变量OPENROUTER_API_KEY均未配置 → 返回source: none执行时抛出missing_perplexity_api_key错误。环境变量来源还会影响端点选择PERPLEXITY_API_KEY环境变量强制走 Perplexity 直连端点OPENROUTER_API_KEY环境变量强制走 OpenRouter 端点——这与“密钥前缀推断”相互独立、且优先级更高测试用例native environment source ahead of key prefix与OpenRouter environment source ahead of key prefix验证了这一点。安装插件安装官方插件并重启 Gatewayopenclaw plugins install openclaw/perplexity-plugin openclaw gateway restart安装完成后通过openclaw configure --section web或直接编辑~/.openclaw/openclaw.json完成配置见下文。插件自带的 README 提供了相同的安装指引extensions/perplexity/README.md。获取并配置 API Key获取 Perplexity API Key在 Perplexity 官方控制台的 API 设置页创建账号并生成 API key插件源码中的signupUrl字段即指向该页面将密钥写入 OpenClaw 配置或设置到 Gateway 进程环境中。配置位置一配置文件运行openclaw configure --section web后密钥会存储在~/.openclaw/openclaw.json的plugins.entries.perplexity.config.webSearch.apiKey字段。该字段类型为string | object即既可直接填写明文也可传入 SecretRef 对象交给 OpenClaw 的密钥系统解析。配置位置二环境变量在 Gateway 进程环境中设置PERPLEXITY_API_KEY或OPENROUTER_API_KEY。对于以 gateway 方式安装的场景请写入~/.openclaw/.env或服务管理器的环境配置环境变量的加载规则参见 docs/help/faq.md。启动期快速失败Fast Fail官方文档明确如果配置了provider: perplexity但 Perplexity 密钥的 SecretRef 无法解析且没有环境变量兜底Gateway 启动 / 重载会快速失败而不是带着无效配置静默运行。这一行为让密钥缺失在配置阶段即暴露避免运行期才报错。配置示例方式一原生 Perplexity Search API结构化结果{ plugins: { entries: { perplexity: { config: { webSearch: { apiKey: pplx-..., }, }, }, }, }, tools: { web: { search: { provider: perplexity, }, }, }, }方式二OpenRouter / Sonar 兼容路径AI 综合答案如果你此前已在使用 OpenRouter 上的 Perplexity Sonar可以保留provider: perplexity然后二选一在 Gateway 环境设置OPENROUTER_API_KEY或在plugins.entries.perplexity.config.webSearch.apiKey中存放sk-or-...密钥。可选兼容控制项plugins.entries.perplexity.config.webSearch.baseUrl默认https://openrouter.ai/api/v1plugins.entries.perplexity.config.webSearch.model默认perplexity/sonar-pro{ plugins: { entries: { perplexity: { config: { webSearch: { apiKey: openrouter-api-key, baseUrl: https://openrouter.ai/api/v1, model: perplexity/sonar-pro, }, }, }, }, }, tools: { web: { search: { provider: perplexity, }, }, }, }提示tools.web.search.provider会与插件清单声明的提供者 ID 做严格校验拼写错误如brvae会在配置校验阶段直接失败而不是静默回退到自动检测。当未显式设置provider时Perplexity 在自动检测顺序中排第 6 位autoDetectOrder: 50只要其密钥可解析即会被自动选中详见 docs/tools/web.md。web_search 工具参数详解以下参数适用于原生 Perplexity Search API 路径参数类型默认值说明querystring必填搜索查询语句countnumber5返回结果条数1-10countrystring—2 字母 ISO 国家代码如US、DElanguagestring—ISO 639-1 语言代码如en、de、frfreshnessday \| week \| month \| year—时间过滤day表示 24 小时内date_afterstring—仅返回此日期之后发布的结果YYYY-MM-DDdate_beforestring—仅返回此日期之前发布的结果YYYY-MM-DDdomain_filterstring[]—域名白名单 / 黑名单数组最多 20 个max_tokensnumber25000总内容 token 预算最大 1000000max_tokens_per_pagenumber2048单页 token 上限调用示例// 按国家与语言搜索 await web_search({ query: renewable energy, country: DE, language: de, }); // 近期结果过去一周 await web_search({ query: AI news, freshness: week, }); // 日期区间搜索 await web_search({ query: AI developments, date_after: 2024-01-01, date_before: 2024-06-30, }); // 域名过滤白名单 await web_search({ query: climate research, domain_filter: [nature.com, science.org, .edu], }); // 域名过滤黑名单 - 使用 - 前缀 await web_search({ query: product reviews, domain_filter: [-reddit.com, -pinterest.com], }); // 更充分的内容抽取 await web_search({ query: detailed AI research, max_tokens: 50000, max_tokens_per_page: 4096, });域名过滤规则每次请求最多 20 个域名不允许在同一请求中混用白名单与黑名单条目黑名单条目使用-前缀如[-reddit.com]白名单条目不带前缀。源码在 perplexity-web-search-provider.runtime.ts 中同步实现了这三条规则混用返回invalid_domain_filter提示 “cannot mix allowlist and denylist entries”超过 20 个同样返回该错误码。兼容路径下的参数差异在 Sonar / OpenRouter 兼容路径chat_completions下仅接受query、count、freshness三个参数count只是兼容性占位——响应仍然是“单条综合答案 引用”而非 N 条结果列表仅 Search API 支持的过滤参数country、language、date_after、date_before、domain_filter、max_tokens、max_tokens_per_page会返回显式错误对应错误码依次为unsupported_country、unsupported_language、unsupported_date_filter、unsupported_domain_filter、unsupported_content_budget错误信息会提示“仅原生 Perplexity Search API 路径支持请移除 baseUrl/model 覆盖或改用直接 PERPLEXITY_API_KEY”。底层实现请求体、时间过滤与缓存原生 Search API 的请求字段映射插件将工具参数映射为 Perplexity Search 官方字段runPerplexitySearchApi工具参数请求体字段queryquerycountmax_resultscountrycountrydomain_filtersearch_domain_filterfreshnesssearch_recency_filterlanguagesearch_language_filterdate_aftersearch_after_date_filterdate_beforesearch_before_date_filtermax_tokensmax_tokensmax_tokens_per_pagemax_tokens_per_page请求打到https://api.perplexity.ai/searchPOST携带Authorization: Bearer key等请求头。日期会经isoToPerplexityDate转换为 Perplexity 期望的M/D/YYYY格式——测试用例确认date_after: 2024-01-01会以search_after_date_filter: 1/1/2024的形式进入请求体见 perplexity-web-search-provider.test.ts。chat_completions 路径请求打到baseUrl/chat/completionsbody 为{ model, messages: [{ role: user, content: query }] }若传了freshness则额外带上search_recency_filter。响应解析优先取顶层citations数组否则回退遍历choices[].message.annotations中type url_citation的条目去重后作为引用输出。若响应没有最终答案缺choices或 content 为空白插件会报错提示“重试或换一个搜索提供者”且不会缓存失败结果。参数校验优先级工具执行时的校验顺序在源码中是有意排列的测试用例preserves provider validation precedence完整记录了优先级兼容路径下不支持的原生参数按 country → language → date → domain → budget 顺序先于其他校验freshness必须是day/week/month/year否则invalid_freshnesslanguage必须是 2 字母 ISO 639-1 代码否则invalid_languagefreshness与date_after/date_before不能同时使用否则conflicting_time_filters日期必须是YYYY-MM-DD且date_after早于date_before否则invalid_date/invalid_date_rangecount必须是 1-10 的整数max_tokens必须是 1-1000000 的正整数max_tokens_per_page必须是正整数。结果缓存缓存键由 provider、transport、baseUrl、model、query、count 及全部过滤参数联合构成buildSearchCacheKey默认缓存 15 分钟可通过tools.web.search.cacheTtlMinutes配置调整设为0可完全绕过缓存读写注意count只有在原生路径下才进入缓存维度——因为兼容路径返回的是单条答案count不参与上游请求测试用例uses count as a cache dimension only when ... sends it upstream验证了两种路径的缓存行为差异缓存命中时返回的 payload 带有cached: true标记。安全与健壮性所有外发请求经withTrustedWebSearchEndpoint走 OpenClaw 的受保护 fetch 路径网络范围仅限当前提供者自身主机名SSRF 相关防护由核心层的 web 工具策略统一管控见 docs/tools/web.md返回结果统一通过wrapWebContent包装并标记externalContent: { untrusted: true, source: web_search, provider: perplexity, wrapped: true }作为不可信内容的信任边界标记HTTP 错误保留状态码与受控诊断信息且会对反射回显的请求凭证做脱敏如401错误中的密钥被替换为***测试用例redacts reflected request credentials覆盖原生与兼容两条路径支持调用方通过AbortSignal取消请求发起前检查预取消不发起请求请求进行中也会传播取消信号测试用例覆盖了 pre-canceled 与 in-flight cancellation 两种场景。常见错误与排查错误码 / 现象原因处理方式missing_perplexity_api_key未配置任何密钥设置PERPLEXITY_API_KEY/OPENROUTER_API_KEY环境变量或配置plugins.entries.perplexity.config.webSearch.apiKey若不想配置搜索密钥可改用web_fetch抓取指定 URL 或用 browser 工具处理交互页面unsupported_country/unsupported_language/unsupported_date_filter/unsupported_domain_filter/unsupported_content_budget在 chat_completions 兼容路径使用了原生参数移除baseUrl/model覆盖或改用直接PERPLEXITY_API_KEY走原生路径invalid_freshnessfreshness不是day/week/month/year修正取值conflicting_time_filters同时使用freshness与date_after/date_before二选一invalid_date/invalid_date_range日期格式错误或区间颠倒使用YYYY-MM-DD且保证date_after date_beforeinvalid_domain_filter混用白名单与黑名单或超过 20 个域名统一使用正条目白名单或全部加-前缀黑名单且不超过 20 个Gateway 启动 / 重载快速失败provider: perplexity已配置但 SecretRef 无法解析且无环境变量兜底补齐密钥配置后重载相关文档Perplexity 使用指南本文的权威配置来源Web 搜索总览全部提供者、自动检测顺序与结果归一化形态插件参考文档插件源码目录含运行时实现与完整测试套件适合深入阅读【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考