Perplexity with OpenClaw

Overview

OpenClaw(https://openclaw.ai) is an open-source AI agent that runs in your terminal and connects to multiple LLM providers, featuring support for Perplexity as a web search provider for real-time information retrieval.

You can configure OpenClaw to use Perplexity's Agent API models as your agent, and the Perplexity Search API for web search tool calls. This allows you to leverage Perplexity's powerful models and up-to-date search results directly within OpenClaw's agent framework.

Get a Perplexity API Key

Navigate to the API Console and generate a new key to use with OpenClaw.

Get Key

Search API Setup (Use Perplexity as your Web Search Provider)

Use Perplexity Search API as OpenClaw's web search backend for real-time information retrieval.

Install the Perplexity plugin
The Perplexity search provider ships as a separate OpenClaw plugin. Install it before you configure a key:
Bash
```
openclaw plugins install @openclaw/perplexity-plugin
openclaw gateway restart
```

Configure the Search Provider

The quickest way, no file editing required:

Bash

openclaw configure --section web

Select Perplexity when prompted for a search provider, then paste your API key.

Edit your openclaw.json (run openclaw config file to locate it):

JSON

{
  "plugins": {
    "entries": {
      "perplexity": {
        "config": {
          "webSearch": {
            "apiKey": "pplx-..."
          }
        }
      }
    }
  },
  "tools": {
    "web": {
      "search": {
        "provider": "perplexity"
      }
    }
  }
}

Set the environment variable and OpenClaw will auto-detect it:

Bash

export PERPLEXITY_API_KEY="pplx-..."

powershell

setx PERPLEXITY_API_KEY="pplx-..."

Or set PERPLEXITY_API_KEY in ~/.openclaw/.env for daemon installs.

Start using OpenClaw with Perplexity Search
Start OpenClaw and ask anything that requires web search:
```
openclaw
> What are the latest developments in quantum computing?
```
OpenClaw will use Perplexity Search API to retrieve structured results and incorporate them into its response.

Search Tool Parameters

When OpenClaw invokes web_search with Perplexity as the provider, these parameters are available:

Parameter	Description
`query`	Search query (required)
`count`	Number of results (1–10, default: 5)
`country`	ISO 3166-1 alpha-2 country code (e.g., `US`, `DE`)
`language`	ISO 639-1 language code (e.g., `en`, `fr`)
`freshness`	Time filter: `day`, `week`, `month`, or `year`
`date_after`	Results published after this date (`YYYY-MM-DD`)
`date_before`	Results published before this date (`YYYY-MM-DD`)
`domain_filter`	Domain allowlist or denylist (max 20 entries)
`max_tokens`	Total content budget (default: 25,000, max: 1,000,000)
`max_tokens_per_page`	Per-page token limit (default: 2,048)

Agent API Setup (Use Perplexity as your LLM Provider)

Use Perplexity's Agent API to run frontier models from Anthropic, OpenAI, Google, and others through a single API key.

Get Your API Key
Generate API Key
Navigate to the API Console and generate a new key.
Get Key
Install OpenClaw
If you haven't installed OpenClaw yet:
- macOS / Linux
- Windows (PowerShell)
Bash
curl -fsSL https://openclaw.ai/install.sh | bash
powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
For Docker, Podman, Nix, or other installation methods, see the OpenClaw install documentation.
Apply the required configuration
Perplexity's Agent API runs its own server-side built-in tools. To use it as an OpenClaw model provider, disable OpenClaw's managed web_search in openclaw.json so the model uses Perplexity's built-in search instead:
JSON
```
{
  "tools": {
    "web": {
      "search": { "enabled": false }
    }
  }
}
```
See Reserved tool names below for the full list of names Perplexity's Agent API reserves for its server-side tools.

Configure Perplexity as an LLM Provider

The quickest way, no file editing required:

Bash

openclaw onboard \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.perplexity.ai/v1" \
  --custom-api-key "pplx-YOUR_KEY_HERE" \
  --custom-model-id "anthropic/claude-sonnet-4-6" \
  --custom-compatibility openai-responses \
  --custom-provider-id perplexity \
  --install-daemon

This registers Perplexity as a provider with one model. To add more models, re-run with a different --custom-model-id or switch to the config file method.

You can replace anthropic/claude-sonnet-4-6 with any model ID from the Agent API models list to change your default model.

Edit your openclaw.json (run openclaw config file to locate it). This declares Perplexity with one starter model and opts into live model discovery, so OpenClaw learns the rest of the Agent API catalog from GET /v1/models:

JSON

{
"agents": {
  "defaults": {
    "model": { "primary": "perplexity/anthropic/claude-sonnet-4-6" },
    "models": { "perplexity/*": {} }
  }
},
"tools": {
  "web": { "search": { "enabled": false } }
},
"models": {
  "mode": "merge",
  "providers": {
    "perplexity": {
      "baseUrl": "https://api.perplexity.ai/v1",
      "apiKey": "${PERPLEXITY_API_KEY}",
      "api": "openai-responses",
      "models": [
        {
          "id": "anthropic/claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6 (Perplexity)",
          "api": "openai-responses",
          "reasoning": false,
          "input": ["text"],
          "cost": { "input": 3.00, "output": 15.00, "cacheRead": 0.30, "cacheWrite": 0 },
          "contextWindow": 200000,
          "maxTokens": 16384
        }
      ]
    }
  }
}
}

Set PERPLEXITY_API_KEY in your shell or use OpenClaw's secret storage instead of putting the key in config.

The "perplexity/*": {} entry under agents.defaults.models opts into live discovery. After a restart, run openclaw models list --provider perplexity to see every model returned by GET /v1/models, then reference any of them as perplexity/<model-id> (for example perplexity/openai/gpt-5.6-terra or perplexity/anthropic/claude-opus-4-7). To pin a per-model context window, cost, or capability, add just that model to the models array; anything you do not pin is inherited from live discovery.

Start using OpenClaw
Launch OpenClaw and your agent will use Perplexity:
Bash
```
openclaw
```

Reserved tool names

Perplexity's Agent API reserves these function names for its own server-side built-in tools; do not define custom functions with these names:

web_search
fetch_url
people_search
finance_search

The required configuration in the setup steps above disables OpenClaw's managed web_search so the model uses Perplexity's server-side search instead. Perplexity's web_search runs inside the model's response, invoked automatically by the model at $0.0025 per call, and returns grounded results with citations. To force it on for a request, add {"type": "web_search"} to the request's tools array as a built-in tool rather than a function.

To remove any other reserved-name tool from the outbound tool catalog, disable it through its own config toggle, or use OpenClaw's general tool policy:

JSON

{
  "tools": {
    "deny": ["web_search"]
  }
}

MCP Server Setup (Use Perplexity as a Tool Provider)

OpenClaw can also reach Perplexity through the Model Context Protocol, which exposes perplexity_search, perplexity_ask, perplexity_research, and perplexity_reason as MCP tools your agent can call. This complements the Agent API setup above: the Agent API drives the model, MCP gives the model access to Perplexity's search and research surfaces.

Add the hosted MCP server to openclaw.json:

JSON

{
  "mcp": {
    "servers": {
      "perplexity": {
        "url": "https://api.perplexity.ai/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${PERPLEXITY_API_KEY}"
        }
      }
    }
  }
}

Or use the CLI:

Bash

openclaw mcp add perplexity \
  --url https://api.perplexity.ai/mcp \
  --transport streamable-http \
  --header "Authorization=Bearer $PERPLEXITY_API_KEY"
openclaw mcp doctor perplexity --probe

OpenClaw resolves ${PERPLEXITY_API_KEY} from your environment at request time. Do not paste the raw key into config.

Run the MCP server locally through npx and let OpenClaw manage the child process:

JSON

{
  "mcp": {
    "servers": {
      "perplexity": {
        "command": "npx",
        "args": ["-y", "@perplexity-ai/mcp-server"],
        "transport": "stdio",
        "env": {
          "PERPLEXITY_API_KEY": "${PERPLEXITY_API_KEY}"
        }
      }
    }
  }
}

Or use the CLI:

Bash

openclaw mcp add perplexity \
  --command npx \
  --arg "-y" \
  --arg "@perplexity-ai/mcp-server" \
  --env "PERPLEXITY_API_KEY=$PERPLEXITY_API_KEY"
openclaw mcp doctor perplexity --probe

Local stdio requires Node.js on the machine running OpenClaw. Prefer the remote MCP server unless you need to run everything offline of Perplexity's edge.

Agent API Configuration Tips

API transport must be openai-responses

Perplexity's Agent API primary endpoint is POST https://api.perplexity.ai/v1/agent. It also accepts requests at POST https://api.perplexity.ai/v1/responses as an OpenAI-Responses-compatible alias, which is what OpenClaw uses when api is "openai-responses".

Set api: "openai-responses" at both the provider level and each model entry in openclaw.json. Using "openai-completions" will not work because the Agent API does not implement /v1/chat/completions.

Base URL must be exactly https://api.perplexity.ai/v1

Perplexity's Agent API primary endpoint is POST /v1/agent, and POST /v1/responses is its OpenAI-Responses-compatible alias. OpenClaw's openai-responses client sends to whatever base URL you give it with /responses appended, so the base URL must be https://api.perplexity.ai/v1 for OpenClaw to hit the alias at /v1/responses.

Correct base URL	Do not use as a base URL
`https://api.perplexity.ai/v1`	`https://api.perplexity.ai/v1/agent` (OpenClaw would call `/v1/agent/responses` and get `405 Method Not Allowed`)
	`https://api.perplexity.ai/v1/responses` (OpenClaw would call `/v1/responses/responses` and get `404`)
	`https://api.perplexity.ai` (missing `/v1`; requests hit `/responses` and get `404`)

Model ID format

In the config, model IDs under a provider block omit the provider prefix. The full model reference adds it:

Config model ID: anthropic/claude-sonnet-4-6
Full model reference: perplexity/anthropic/claude-sonnet-4-6

Discover models with the `perplexity/*` wildcard

Add "perplexity/*": {} to agents.defaults.models to have OpenClaw call GET https://api.perplexity.ai/v1/models and register every returned model automatically. You keep detailed entries under models.providers.perplexity.models only for the ones you want to pin, and the rest fall through to live discovery. Verify with openclaw models list --provider perplexity.

Links & Resources

Agent API Quickstart

Use third-party models with built-in tools and function calling

Agent API Models

Full list of available models and pricing

MCP Server

Perplexity's remote and local MCP servers, tools, and auth

Perplexity CLI

Terminal companion for search and page snippets from shell or agent scripts

Search API Quickstart

Full Perplexity Search API documentation

OpenAI Compatibility

How the Agent API works with OpenAI-compatible clients

OpenClaw Documentation

OpenClaw's official documentation

API Console

Generate and manage your API keys

Search documentation

Getting Started

Router API

Agent API

Embeddings API

Perplexity SDK

Admin & Management

Resources

Perplexity with OpenClaw

Overview

Search API Setup (Use Perplexity as your Web Search Provider)

Search Tool Parameters

Agent API Setup (Use Perplexity as your LLM Provider)

Reserved tool names

MCP Server Setup (Use Perplexity as a Tool Provider)

Agent API Configuration Tips

Links & Resources

Getting Started

Router API

Agent API

Embeddings API

Perplexity SDK

Admin & Management

Resources