# Perplexity

> Perplexity Web 搜索提供商设置（API key、搜索模式、筛选）

- 网址：https://funcoding.ai/agents/openclaw/providers/perplexity-provider/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/providers/perplexity-provider

---
Perplexity 插件注册了一个 `web_search` 提供商，并支持两种传输方式：原生 Perplexity Search API（提供带筛选条件的结构化结果），以及直接调用或通过 OpenRouter 调用的 Perplexity Sonar 聊天补全（提供带引用的 AI 综合答案）。

<div class="callout callout-note">

本页面介绍 Perplexity **提供商**的设置。有关 Perplexity **工具**（智能体如何使用它），请参阅 [Perplexity 搜索](https://funcoding.ai/agents/openclaw/tools/perplexity-search/)。

</div>

| 属性        | 值                                                                     |
| ----------- | ---------------------------------------------------------------------- |
| 类型        | Web 搜索提供商（不是模型提供商）                                       |
| 身份验证    | `PERPLEXITY_API_KEY`（原生）或 `OPENROUTER_API_KEY`（通过 OpenRouter） |
| 配置路径    | `plugins.entries.perplexity.config.webSearch.apiKey`                   |
| 覆盖项      | `plugins.entries.perplexity.config.webSearch.baseUrl` / `.model`       |
| 获取密钥    | [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)   |

## 安装插件

```bash
openclaw plugins install @openclaw/perplexity-plugin
openclaw gateway restart
```

## 入门指南

**设置 API key**

```bash
openclaw configure --section web
```

或者直接设置密钥：

```bash
openclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
```

在 Gateway 网关环境中导出为 `PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY` 的密钥也可以使用。

**开始搜索**

当 Perplexity 的密钥成为可用的搜索凭据时，`web_search` 会自动检测 Perplexity，无需进一步设置。若要明确指定提供商：

```bash
openclaw config set tools.web.search.provider perplexity
```

## 搜索模式

插件按以下顺序解析传输方式：

1. 设置了 `webSearch.baseUrl` 或 `webSearch.model`：无论密钥类型如何，始终通过 Sonar 聊天补全路由到该端点。
2. 否则，由密钥来源决定端点：已配置密钥的前缀决定传输方式（配置优先于环境变量）；环境密钥直接使用与其匹配的端点。

| 密钥前缀 | 传输方式                                                   | 功能                                             |
| ---------- | ---------------------------------------------------------- | ------------------------------------------------ |
| `pplx-`    | 原生 Perplexity Search API（`https://api.perplexity.ai`） | 结构化结果、域名/语言/日期筛选条件               |
| `sk-or-`   | OpenRouter（`https://openrouter.ai/api/v1`）、Sonar 模型   | 带引用的 AI 综合答案                             |

具有任何其他前缀的已配置密钥也使用原生 Search API。聊天补全路径默认使用 `perplexity/sonar-pro` 模型；可通过 `plugins.entries.perplexity.config.webSearch.model` 覆盖它。

## 原生 API 筛选

| 筛选条件                             | 说明                                                            | 传输方式     |
| ------------------------------------ | --------------------------------------------------------------- | ----------- |
| `count`                              | 每次搜索的结果数，1-10（默认 5）                                | 仅原生      |
| `freshness`                          | 时间范围：`day`、`week`、`month`、`year`                  | 两者均支持  |
| `country`                            | 2 位国家/地区代码（`us`、`de`、`jp`）                        | 仅原生      |
| `language`                           | ISO 639-1 语言代码（`en`、`fr`、`zh`）                      | 仅原生      |
| `date_after` / `date_before`         | 采用 `YYYY-MM-DD` 格式的发布日期范围                            | 仅原生      |
| `domain_filter`                      | 最多 20 个域名；允许列表或带 `-` 前缀的拒绝列表，不得混用 | 仅原生      |
| `max_tokens` / `max_tokens_per_page` | 所有结果的内容预算 / 每页内容预算                               | 仅原生      |

在聊天补全路径上使用仅原生支持的筛选条件时，会返回描述性错误。`freshness` 不能与 `date_after`/`date_before` 组合使用。

## 高级配置

<details>
<summary>守护进程的环境变量</summary>

<div class="callout callout-warning">

仅在交互式 shell 中导出的密钥对 launchd/systemd Gateway 网关守护进程不可见，除非显式导入该环境。请在 `~/.openclaw/.env` 中或通过 `env.shellEnv` 设置密钥，以便 Gateway 网关进程可以读取它。有关完整的优先级顺序，请参阅[环境变量](https://funcoding.ai/agents/openclaw/help/environment/)。

</div>

</details>

<details>
<summary>OpenRouter 代理设置</summary>

若要通过 OpenRouter 路由 Perplexity 搜索，请设置 `OPENROUTER_API_KEY`（前缀为 `sk-or-`），而不是原生 Perplexity 密钥。OpenClaw 会检测该密钥并自动切换到 Sonar 传输方式。如果你已经设置了 OpenRouter 计费，并希望在那里整合提供商，此方式会很有用。

</details>

## 相关内容

- [Perplexity 搜索工具](https://funcoding.ai/agents/openclaw/tools/perplexity-search/)：智能体如何调用 Perplexity 搜索并解释结果。
- [配置参考](https://funcoding.ai/agents/openclaw/gateway/configuration-reference/)：完整的配置参考，包括插件条目。