Perplexity with OpenClaw

Overview

OpenClaw 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.

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:

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

Configure the Search Provider

Interactive CLI (Recommended)
Config File (JSON)
Environment Variable

The quickest way, no file editing required:

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):

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

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

macOS / Linux
Windows (PowerShell)

export PERPLEXITY_API_KEY="pplx-..."

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)

Domain filters support allowlists (["nature.com", "science.org"]) and denylists (["-reddit.com", "-pinterest.com"]), but you cannot mix both in the same request. See the domain filter guide for details.

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.

Install OpenClaw

If you haven’t installed OpenClaw yet:

macOS / Linux
Windows (PowerShell)

curl -fsSL https://openclaw.ai/install.sh | bash

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:

{
  "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

Onboarding CLI (Recommended)
Config File

The quickest way, no file editing required:

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:

{
"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.4 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:

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:

{
  "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.

Remote MCP (Recommended)
Local MCP (stdio)

Add the hosted MCP server to openclaw.json:

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

Or use the CLI:

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:

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

Or use the CLI:

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.

The MCP tools have names like perplexity_search, so they do not collide with Perplexity’s Agent API reserved names. If you use both the Agent API setup and the MCP setup together, keep the tools.web.search.enabled: false entry from the Agent API section in place.

MCP tools respect OpenClaw’s tool profiles and allow/deny policy. Filter which Perplexity tools your agent can call with mcp.servers.perplexity.toolFilter.include. See the OpenClaw MCP guide for the full field list.

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.

For the latest model list and pricing, see the Agent API models page and pricing page.

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

Getting Started

Router API

Agent API

Search API

Search SDK

Embeddings API

Perplexity SDK

Admin & Management

Resources

Legacy API

Perplexity with OpenClaw

Overview

Get a Perplexity API Key

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

Search Tool Parameters

Agent API Setup (Use Perplexity as your LLM Provider)

Generate API Key

Reserved tool names

MCP Server Setup (Use Perplexity as a Tool Provider)

Agent API Configuration Tips

Links & Resources

Agent API Quickstart

Agent API Models

MCP Server

Perplexity CLI

Search API Quickstart

OpenAI Compatibility

OpenClaw Documentation

API Console

​Overview

Get a Perplexity API Key

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

​Search Tool Parameters

​Agent API Setup (Use Perplexity as your LLM Provider)

Generate API Key

​Reserved tool names

​MCP Server Setup (Use Perplexity as a Tool Provider)

​Agent API Configuration Tips

​Links & Resources

Agent API Quickstart

Agent API Models

MCP Server

Perplexity CLI

Search API Quickstart

OpenAI Compatibility

OpenClaw Documentation

API Console

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