Perplexity Provider
기준일: 2026-07-26
난이도: 중급
공식 기준: Perplexity
개요
이 페이지는 OpenClaw Perplexity provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.
공식 요약: Perplexity web search provider setup (API key, search modes, filtering)
model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.
빠른 참조
| Property | Value |
|---|---|
| Type | Web search provider (not a model provider) |
| Auth | PERPLEXITY_API_KEY (native) or OPENROUTER_API_KEY (via OpenRouter) |
| Config path | plugins.entries.perplexity.config.webSearch.apiKey |
| Overrides | plugins.entries.perplexity.config.webSearch.baseUrl / .model |
| Get a key | perplexity.ai/settings/api |
공식 문서 기반 상세
아래는 공식 providers/perplexity-provider 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.
The Perplexity plugin registers a web_search provider with two transports: the
native Perplexity Search API (structured results with filters) and Perplexity
Sonar chat completions, direct or via OpenRouter (AI-synthesized answers with
citations).
This page covers the Perplexity provider setup. For the Perplexity tool (how the agent uses it), see Perplexity search.
| Property | Value |
|---|---|
| Type | Web search provider (not a model provider) |
| Auth | PERPLEXITY_API_KEY (native) or OPENROUTER_API_KEY (via OpenRouter) |
| Config path | plugins.entries.perplexity.config.webSearch.apiKey |
| Overrides | plugins.entries.perplexity.config.webSearch.baseUrl / .model |
| Get a key | perplexity.ai/settings/api |
Install plugin
openclaw plugins install @openclaw/perplexity-plugin
openclaw gateway restart
시작하기
Set the API key
```bash
openclaw configure --section web
```
Or set the key directly:
```bash
openclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
```
A key exported as `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY` in the Gateway
environment also works.
Start searching
`web_search` auto-detects Perplexity once its key is the available search
credential; no further setup is required. To pin the provider explicitly:
```bash
openclaw config set tools.web.search.provider perplexity
```
Search modes
The plugin resolves transport in this order:
webSearch.baseUrlorwebSearch.modelset: always routes through Sonar chat completions against that endpoint, regardless of key type.- Otherwise, key source decides the endpoint: a configured key's prefix picks the transport (config beats environment variables); an environment key uses its matching endpoint directly.
| Key prefix | Transport | Features |
|---|---|---|
pplx- |
Native Perplexity Search API (https://api.perplexity.ai) |
Structured results, domain/language/date filters |
sk-or- |
OpenRouter (https://openrouter.ai/api/v1), Sonar model |
AI-synthesized answers with citations |
A configured key with any other prefix also uses the native Search API. The
chat-completions path defaults to the perplexity/sonar-pro model; override it
with plugins.entries.perplexity.config.webSearch.model.
Native API filtering
| Filter | Description | Transport |
|---|---|---|
count |
Results per search, 1-10 (default 5) | Native only |
freshness |
Recency window: day, week, month, year |
Both |
country |
2-letter country code (us, de, jp) |
Native only |
language |
ISO 639-1 language code (en, fr, zh) |
Native only |
date_after / date_before |
Published-date range in YYYY-MM-DD |
Native only |
domain_filter |
Max 20 domains; allowlist or --prefixed denylist, never mixed |
Native only |
max_tokens / max_tokens_per_page |
Content budget across all results / per page | Native only |
Native-only filters return a descriptive error on the chat-completions path.
freshness cannot be combined with date_after/date_before.
고급 설정
Environment variable for daemon processes
A key exported only in an interactive shell is not visible to a launchd/systemd Gateway daemon unless that environment is explicitly imported. Set the key in
~/.openclaw/.envor viaenv.shellEnvso the Gateway process can read it. See Environment variables for the full precedence order.
OpenRouter proxy setup
To route Perplexity searches through OpenRouter, set an `OPENROUTER_API_KEY`
(prefix `sk-or-`) instead of a native Perplexity key. OpenClaw detects the
key and switches to the Sonar transport automatically. Useful if you already
have OpenRouter billing set up and want to consolidate providers there.
관련 문서
How the agent invokes Perplexity searches and interprets results.
Full configuration reference including plugin entries.
검증 체크리스트
-
openclaw models list --provider perplexity-provider로 모델이 보이는지 확인 - 기본 model alias를
agents.defaults.model.primary에 설정했는지 확인 - API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
- failover 시 데이터가 다른 provider로 이동할 수 있는지 검토