Perplexity Search API

OpenClaw 支援以 Perplexity Search API 作為 web_search 供應商。它會回傳包含 title、url 和 snippet 欄位的結構化結果。

為了向下相容，OpenClaw 也支援舊版 Perplexity Sonar/OpenRouter 設定。如果你使用 OPENROUTER_API_KEY、在 tools.web.search.perplexity.apiKey 填入 sk-or-... 金鑰，或設定了 tools.web.search.perplexity.baseUrl / model，供應商會切換到 chat-completions 路徑，回傳 AI 合成的答案和引用，而非結構化的 Search API 結果。

取得 Perplexity API 金鑰

1. 前往 https://www.perplexity.ai/settings/api 建立 Perplexity 帳號
2. 在控制台產生 API 金鑰
3. 將金鑰存入設定檔，或在 Gateway 環境中設定 PERPLEXITY_API_KEY。

OpenRouter 相容模式

如果你原本就透過 OpenRouter 使用 Perplexity Sonar，保持 provider: "perplexity" 不變，在 Gateway 環境中設定 OPENROUTER_API_KEY，或將 sk-or-... 金鑰存入 tools.web.search.perplexity.apiKey。

選用的舊版控制項：

• tools.web.search.perplexity.baseUrl
• tools.web.search.perplexity.model

設定範例

原生 Perplexity Search API

{
  tools: {
    web: {
      search: {
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...",
        },
      },
    },
  },
}

OpenRouter / Sonar 相容模式

{
  tools: {
    web: {
      search: {
        provider: "perplexity",
        perplexity: {
          apiKey: "<openrouter-api-key>",
          baseUrl: "https://openrouter.ai/api/v1",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

金鑰設定方式

透過設定檔： 執行 openclaw configure --section web。金鑰會存在 ~/.openclaw/openclaw.json 的 tools.web.search.perplexity.apiKey。該欄位也接受 SecretRef 物件。

透過環境變數： 在 Gateway 程序環境中設定 PERPLEXITY_API_KEY 或 OPENROUTER_API_KEY。若是已安裝的 Gateway 服務，放在 ~/.openclaw/.env（或你的服務環境）。詳見 環境變數。

若設定了 provider: "perplexity" 但 Perplexity 金鑰的 SecretRef 無法解析且沒有環境變數可退回，啟動／重新載入會立即失敗。

工具參數

以下參數適用於原生 Perplexity Search API 路徑。

舊版 Sonar/OpenRouter 相容路徑僅支援 query 和 freshness。Search API 專屬的篩選器如 country、language、date_after、date_before、domain_filter、max_tokens 和 max_tokens_per_page 會回傳明確的錯誤訊息。

範例：

// 指定國家與語言的搜尋
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

// 近期結果（過去一週）
await web_search({
  query: "AI news",
  freshness: "week",
});

// 日期範圍搜尋
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// 網域篩選（白名單）
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// 網域篩選（黑名單——加上 - 前綴）
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// 擷取更多內容
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

網域篩選規則

• 每個篩選器最多 20 個網域
• 同一個請求中不能混用白名單和黑名單
• 黑名單條目使用 - 前綴（例如 ["-reddit.com"]）

備註

• Perplexity Search API 回傳結構化的網頁搜尋結果（title、url、snippet）
• 使用 OpenRouter 或明確設定 baseUrl / model 會將 Perplexity 切換回 Sonar chat completions 以確保相容性
• 搜尋結果預設快取 15 分鐘（可透過 cacheTtlMinutes 設定）

完整的 web_search 設定請參閱 Web 工具。 更多細節請參閱 Perplexity Search API 文件。