# How to connect Perplexity AI to OpenClaw (bring your own pplx- key)

> Connect Perplexity AI to OpenClaw with ClawLink: 9 tools your agent can call from chat. You bring one Perplexity API key (pplx-...) — ClawLink hosts it. No openclaw.json edits, no env files, no plugin registry.

Web version: https://claw-link.dev/openclaw/perplexity-ai

The usual route to Perplexity AI access for OpenClaw is an MCP server you configure and keep running, plus your own OAuth app or API keys. ClawLink gives OpenClaw a more practical Perplexity AI setup: install one ClawHub skill, connect Perplexity AI in the browser, and OpenClaw can call real Perplexity AI actions from any chat surface with no auth, token refresh, or tool wiring to build yourself.

**Start here:** install the ClawLink plugin (`openclaw plugins install clawhub:clawlink-plugin`), pair it in the browser, then connect the app in the ClawLink dashboard. The interactive install prompt is on the web version of this page: https://claw-link.dev/openclaw/perplexity-ai

## Setup

It takes three steps to connect OpenClaw to Perplexity AI.

1. **Install ClawLink** — add the plugin to OpenClaw once.
2. **Connect Perplexity AI** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask OpenClaw in plain English.

**Alternative for any agent (no plugin needed):** if the OpenClaw plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect perplexity-ai  # connect Perplexity AI (browser OAuth)
npx -y @useclawlink/cli actions perplexity-ai  # list available actions
npx -y @useclawlink/cli run perplexity-ai <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The setup prompt above does all of this in one paste. By hand, it is one install command plus a browser approval:

```bash
openclaw plugins install clawhub:clawlink-plugin
```

Then ask OpenClaw to set up ClawLink. It starts browser pairing and prints an approval link — open it, approve the device, return to the chat, and say `done`. Finally, connect Perplexity AI in the [ClawLink dashboard](https://claw-link.dev/dashboard) — paste your Perplexity AI API key once.

Verify the connection by asking OpenClaw:

> Search the web for 'latest EU AI regulation news', restrict results to the past week with search_recency_filter 'week' and country 'US', and summarize the top results with sources.

### Using a different agent?

The OpenClaw plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Perplexity AI is connected in the dashboard, that agent calls the same 9 Perplexity AI tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Perplexity AI MCP for OpenClaw

Looking for a Perplexity AI MCP server for OpenClaw? ClawLink connects Perplexity AI to OpenClaw and exposes 9 Perplexity AI tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using Hermes instead? The [Hermes Perplexity AI integration](https://claw-link.dev/hermes/perplexity-ai) works the same way.

You bring one Perplexity API key — it starts with pplx- and is created at console.perplexity.ai, shown once at creation — and ClawLink hosts it. That is the difference from the DIY route: no openclaw.json edits under plugins.entries.perplexity, no PERPLEXITY_API_KEY in .env files, no @openclaw/perplexity-plugin installs to keep working. The nine tools below are called through the ClawLink runtime and the same account is available to the agent from any chat surface.

## The route map for Perplexity + OpenClaw (and the one ClawLink does not serve)

There are three ways to give OpenClaw Perplexity search or models, and knowing which one you are on explains most setup friction.

- Official OpenClaw plugin (@openclaw/perplexity-plugin): Perplexity becomes OpenClaw's web_search provider. You keep the key in openclaw.json (plugins.entries.perplexity.config.webSearch.apiKey) or as PERPLEXITY_API_KEY; a pplx- key uses the native Search API, an sk-or- key routes through OpenRouter's Sonar. Configure with `openclaw configure --section web`. ClawLink does not replace this — it is OpenClaw's own provider slot.
- Perplexity's official MCP server: `npx -y @perplexity-ai/mcp-server` (stdio) or the remote endpoint https://api.perplexity.ai/mcp with your key as a Bearer token. Exposes perplexity_search, perplexity_ask, perplexity_research, perplexity_reason. This is a second key you manage inside an MCP client.
- ClawLink hosted tools (this page): you paste your pplx- key once into the ClawLink connect flow; the nine tools (search, chat completions, embeddings, agent execution, async jobs) are called through the ClawLink runtime, with the key stored encrypted on our side. No openclaw.json edits, no env files, no plugin installs.
- Not served by ClawLink: Perplexity as the LLM model for OpenClaw itself (the Agent API / openai-responses route with base URL https://api.perplexity.ai/v1). That stays in OpenClaw's own provider config — Perplexity documents it under 'Perplexity with OpenClaw'. If your goal is a Perplexity-powered agent brain, use that route; if your goal is Perplexity search and embeddings as tools, use one of the first three.
- Community Pro-subscription bridges (e.g. perplexity-web-mcp) that log into a Perplexity Pro web account instead of using the API exist, but they run against Perplexity's terms of service and carry account-ban risk discussed openly in their Reddit threads; ClawLink does not offer this route.

## What the OpenClaw Perplexity AI integration can do

9 Perplexity AI tools are ready for OpenClaw once the account is connected.

### All 9 Perplexity AI tools for OpenClaw

| Tool | What it does |
|---|---|
| **Create async chat completion** `perplexityai_create_async_chat_completion` | Create Async Chat Completion (POST /v1/async/sonar). Submits an asynchronous chat completion request for long-running tasks. |
| **Create chat completion** `perplexityai_create_chat_completion` | Perplexity Sonar Chat Completions (POST /v1/sonar). Generates web-grounded conversational AI responses with citations. |
| **Create contextualized embeddings** `perplexityai_create_contextualized_embeddings` | Create Contextualized Embeddings (POST /v1/contextualizedembeddings). Generates document-aware embeddings where chunks from the same document share context. |
| **Create embeddings** `perplexityai_create_embeddings` | Generate vector embeddings for independent texts (queries, sentences, documents). This action takes one or more input texts and generates vector embeddings using Perplexity AI's embedding models. |
| **Execute agent** `perplexityai_execute_agent` | Create Agent Response (POST /v1/agent). Orchestrates multi-step agentic workflows with built-in tools (web search, URL fetching, function calling), reasoning, and multi-model support. |
| **Get async chat completion** `perplexityai_get_async_chat_completion` | Get Async Chat Completion (GET /v1/async/sonar/\{id\}). Retrieves the result of an asynchronous chat completion request by its ID. Use this to poll for the result after creating an async job. |
| **List async chat completions** `perplexityai_list_async_chat_completions` | List Async Chat Completions (GET /v1/async/sonar). Retrieves a list of all asynchronous chat completion requests for the authenticated user. |
| **List models** `perplexityai_list_models` | List Models (GET /v1/models). Lists models available for the Agent API. Returns model identifiers that can be used with the Agent endpoint. |
| **Search** `perplexityai_search` | Search the Web (POST /search). Returns raw, ranked web search results directly from Perplexity's index without LLM processing. Faster and cheaper than chat completions when you need raw results. |

## Example prompts

**Search with recency + country filters**

> Search the web for 'latest EU AI regulation news', restrict results to the past week with search_recency_filter 'week' and country 'US', and summarize the top results with sources.

**Multi-query search (max 5 queries)**

> Run a Perplexity search for these 5 queries at once: 'ClawLink', 'OpenClaw Perplexity integration', 'Perplexity Sonar pricing', 'Perplexity Agent API models', 'Perplexity MCP server'. Then merge the results into one briefing.

**Chat completion with citations**

> Use perplexityai_create_chat_completion with model 'sonar' to answer: 'What changed in Perplexity's Agent API this quarter?' Use messages [\{'role':'user','content':'What changed in Perplexity's Agent API this quarter?'\}], and list the citations from the response.

**Deep research (async)**

> Start an async deep research job with perplexityai_create_async_chat_completion using model 'sonar-deep-research' on 'competitive landscape of AI web search in 2026'. Then poll perplexityai_get_async_chat_completion with the returned request id until it completes, and summarize the report.

## What to tell the agent when it calls Perplexity

Argument-level facts from the live Perplexity tool schemas (verified against Composio schemas 2026-08-02). Getting these right is what separates a call that succeeds from the errors in the troubleshooting section.

- perplexityai_search: query is required and can be a single string OR an array of strings for multi-query search — but Perplexity's API rejects arrays longer than 5 queries with a 400 'query validation: maximum 5 queries allowed' error. max_results defaults to 10 and caps at 20; max_tokens defaults to 10,000 (max 1,000,000) and max_tokens_per_page to 4,096. country takes an ISO 3166-1 alpha-2 code (e.g. 'US'). search_recency_filter (hour/day/week/month/year) is mutually exclusive with the date filters (search_after_date_filter, search_before_date_filter, last_updated_after_filter, last_updated_before_filter, all MM/DD/YYYY) — never combine them.
- perplexityai_create_chat_completion: messages is required (a bare prompt string is rejected). model defaults to 'sonar'; options are sonar, sonar-pro, sonar-reasoning-pro (chain-of-thought), and sonar-deep-research. max_tokens caps at 128,000. The 'stop' parameter is not supported by Perplexity's API. Tool-role messages must alternate with assistant messages: system -> user -> assistant -> tool -> user.
- perplexityai_execute_agent: input is required. Choose preset 'fast-search', 'pro-search', or 'deep-research' (deep-research generates 10K-100K+ word reports — prefer the async endpoint for it). At least one of model, models, or preset must be set; models is a fallback chain of up to 5. max_steps ranges 1-10.
- perplexityai_create_embeddings / create_contextualized_embeddings: model and input are required. encoding_format defaults to base64_int8. Max 512 texts per request, each up to 32K tokens. pplx-embed-v1-0.6b supports 128-1024 dimensions, pplx-embed-v1-4b up to 2560 (Matryoshka reduction).
- perplexityai_create_async_chat_completion: only 'sonar-deep-research' is supported for async jobs, and async jobs have a 7-day TTL. Pass idempotency_key to prevent duplicate submissions; poll with perplexityai_get_async_chat_completion using the returned request id until status is COMPLETED.
- Perplexity API keys start with pplx- and are shown only once at creation (console.perplexity.ai). There are no OAuth scopes to grant or refresh — the key is the whole credential, so a revoked key fails immediately with 401.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for OpenClaw. That is fine if you want to build and maintain the integration yourself. Most teams just want Perplexity AI working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Credential handling** | Collect, validate, store, and rotate the Perplexity AI API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected Perplexity AI account becomes available to the agent without you building credential management. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Perplexity AI. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Perplexity AI actions to the runtime in a format your agent can reliably use. | 9 tools for Perplexity AI are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Perplexity AI to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for OpenClaw users instead. You install the plugin once, connect Perplexity AI in the browser, and the 9 tools above work from chat. There is no SDK and no config file, and the Perplexity AI key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### OpenClaw installed the Perplexity AI skill but can't call the tools
The ClawHub skill teaches OpenClaw about Perplexity AI, but the calls run through the ClawLink plugin and your connected account. Make sure Perplexity AI is connected in the dashboard, then start a fresh chat so OpenClaw reloads the tool catalog. If OpenClaw runs as a persistent gateway, restart it so the new tools register.

### Connection succeeds but no tools appear
Reconnect Perplexity AI from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Perplexity AI tools
Perplexity AI tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Perplexity AI call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Perplexity AI returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### "arguments.query is required" when OpenClaw calls Perplexity search
The agent called perplexityai_search with no query — the schema requires it. Two proven causes. (1) The empty-arguments bug: OpenClaw with a Perplexity Agent API model used to emit tool calls with empty \{\} arguments (validated as "command: must have required property 'command'" for any tool); that was fixed upstream in pi 0.66.1, so update OpenClaw to 2026.4.11 or newer. (2) A wrong parameter name — 'search' or 'prompt' instead of 'query'. Ask the agent to pass a plain string (or an array of up to 5 queries) and retry. This error is the single most common Perplexity failure in ClawLink's production logs.

### "arguments.messages is required" when calling Perplexity chat completions
perplexityai_create_chat_completion requires a messages array — a list of \{role, content\} objects (system, user, assistant, tool). A missing or empty messages array fails validation before the call reaches Perplexity. Give the agent a real conversation to continue, and note the API does not accept a bare string prompt here. Tool-role messages must alternate with assistant messages; the pattern is system -> user -> assistant -> tool -> user.

### Perplexity API error 400: "query validation: maximum 5 queries allowed, got 10"
perplexityai_search accepts an array of queries for multi-query search, but Perplexity's API caps the array at 5 queries per request. An agent that builds a longer list (the schema allows any length) gets this 400. Split the search into batches of 5 or fewer queries, or use a single query string. This string is verbatim from ClawLink production logs on 2026-08-02.

### Perplexity returns 401 invalid API key after being revoked
Perplexity API keys are shown only once at creation and can be revoked from the console at any time — a revoked or rotated key fails with 401. If the key worked and then stopped, check whether you regenerated or revoked it in the Perplexity console (console.perplexity.ai) and paste the new pplx- key into the ClawLink dashboard. Because ClawLink stores the key, a revocation elsewhere takes effect immediately.

### "No perplexity-ai connection is available. Connect it first."
A tool call fired with no connected account. Connect Perplexity in the ClawLink dashboard first (the connect flow asks for your pplx- key), then start a fresh chat so OpenClaw reloads the tool catalog. If the runtime is a persistent gateway, restart it after connecting so the new tools register.

### API key setup works but results look incomplete
Double-check that the API key for Perplexity AI has the right scopes or account access. A valid key can still be too limited for some reads or writes.

### Is there a OpenClaw Perplexity AI integration?
Yes. ClawLink is the fastest way to connect OpenClaw to Perplexity AI: link your Perplexity AI account once in the browser and OpenClaw can call the Perplexity AI API through 9 ready-made tools — no custom code or token handling.

### How do I add Perplexity AI to OpenClaw with ClawLink?
Paste the setup prompt from this page into OpenClaw. It installs the ClawLink Perplexity AI skill from ClawHub, then you click Connect in the dashboard to authorize Perplexity AI. OpenClaw calls the tools from the next message — no config files, and the Perplexity AI key you paste is stored server-side instead of in your environment.

### How long does it take to connect Perplexity AI to OpenClaw?
About two minutes. Sign in, click Connect next to Perplexity AI in the dashboard, authenticate, and OpenClaw can use it from the next chat message.

### Why use ClawLink instead of wiring Perplexity AI up myself?
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for OpenClaw. That is fine if you want to build and maintain the integration yourself. Most teams just want Perplexity AI working from chat.

### What does OpenClaw's Perplexity provider configuration require?
OpenClaw's own Perplexity configuration (the provider slot that makes Perplexity your model) is separate from this integration: it lives in OpenClaw's provider settings with a base URL of https://api.perplexity.ai/v1 and a pplx- key, and Perplexity documents it under 'Perplexity with OpenClaw'. ClawLink does not touch that configuration. What ClawLink needs is one Perplexity API key, created at console.perplexity.ai, pasted once into the connect flow — no openclaw.json edits, no provider block, no plugin registry.

### Do I need my own Perplexity API key to use the ClawLink integration?
Yes. ClawLink's Perplexity integration is bring-your-own-key: you paste a Perplexity API key (starting with pplx-, from console.perplexity.ai) into the connect flow once, and ClawLink stores and hosts it. The key is shown only once at creation, so copy it when you generate it. This is the same key you would otherwise paste into openclaw.json or an .env file — ClawLink just keeps it for you.

### Does the ClawLink Perplexity integration use OAuth or hosted OAuth?
Neither. Perplexity's API does not use OAuth at all — it authenticates with a plain API key. The 'hosted OAuth' phrasing on other ClawLink integrations does not apply here. You provide a pplx- key, ClawLink stores it encrypted, and every tool call goes through that key. Revoke the key in the Perplexity console at any time to cut access immediately.

### Can I use Perplexity as the model (LLM) for my OpenClaw agent through ClawLink?
No — ClawLink exposes Perplexity tools (search, chat completions, embeddings, agent execution), not a model endpoint. Using Perplexity's Agent API as the brain of OpenClaw itself (openai-responses transport, base URL https://api.perplexity.ai/v1) is a different setup that stays in OpenClaw's own configuration; Perplexity documents it at docs.perplexity.ai under 'Perplexity with OpenClaw'. The two are complementary: ClawLink for Perplexity tools, OpenClaw's provider config for Perplexity models.

### Why does Perplexity AI return 'arguments.query is required'?
It means the agent called the search tool without a query argument — usually an empty tool call (\{\}), which was a known OpenClaw + Perplexity Agent API bug fixed in OpenClaw 2026.4.11 (upstream pi 0.66.1), or a wrong parameter name like 'search' instead of 'query'. Update OpenClaw, ask the agent to pass a real query string, and retry. See the troubleshooting card above for the full fix.

### Is it safe to give my Perplexity API key to an agent platform?
Treat it like any API credential: create a dedicated key for the integration instead of reusing one, use a platform that stores it encrypted rather than in plain text, and revoke it from the Perplexity console if anything looks wrong. A Perplexity key is a payment credential — misuse or a leak can bill your account, so a dedicated, revocable key is the safe pattern.

### OpenClaw installed the Perplexity AI skill but can't call the tools
The ClawHub skill teaches OpenClaw about Perplexity AI, but the calls run through the ClawLink plugin and your connected account. Make sure Perplexity AI is connected in the dashboard, then start a fresh chat so OpenClaw reloads the tool catalog. If OpenClaw runs as a persistent gateway, restart it so the new tools register.

## Related

- [Connect DataRobot](https://claw-link.dev/openclaw/datarobot) — DataRobot is a machine learning platform that automates model building, deployment, and monitoring, enabling organizations to derive predictive insights from large datasets.
- [Chatbotkit](https://claw-link.dev/openclaw/chatbotkit) — ChatBotKit is a platform that enables developers to build and manage AI-powered chatbots, offering comprehensive APIs and SDKs for seamless integration into applications.
- [OpenClaw ElevenLabs integration](https://claw-link.dev/openclaw/elevenlabs) — Generate speech and voice cloning