Web 搜索（Web Search）

让任意模型都能获取实时网络信息

openrouter:web_search 服务端工具让 OpenRouter 上的任意模型都能获取实时网络信息。当模型判断需要最新信息时，会带着搜索查询调用该工具。OpenRouter 执行搜索并将结果返回给模型，供其生成有据可依、带引用的回复。

工作原理

1. 在 tools 数组中加入 { "type": "openrouter:web_search" }。
2. 模型根据用户的提示词决定是否需要网页搜索，并生成搜索查询。
3. OpenRouter 使用配置的引擎执行搜索（默认为 auto：若可用则使用模型服务提供商的原生搜索，否则回退到 Exa）。
4. 搜索结果（URL、标题和内容片段）返回给模型。
5. 模型将结果综合到回复中。如有需要，它可能在同一次请求中多次搜索。

快速开始

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    messages: [
      {
        role: 'user',
        content: '本周有哪些重大的 AI 发布？'
      }
    ],
    tools: [
      { type: 'openrouter:web_search' }
    ]
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

配置

Web 搜索工具接受可选的 parameters，用于自定义搜索行为：

{
  "type": "openrouter:web_search",
  "parameters": {
    "engine": "exa",
    "max_results": 5,
    "max_total_results": 20,
    "search_context_size": "medium",
    "allowed_domains": ["example.com"],
    "excluded_domains": ["reddit.com"]
  }
}

用户位置

传入大致的用户位置，使搜索结果偏向该地理区域：

{
  "type": "openrouter:web_search",
  "parameters": {
    "user_location": {
      "type": "approximate",
      "city": "San Francisco",
      "region": "California",
      "country": "US",
      "timezone": "America/Los_Angeles"
    }
  }
}

user_location 内的所有字段均为可选。

原生搜索服务提供商

当 engine 为 "auto"（默认）或 "native" 时，OpenRouter 会为受支持的模型使用服务提供商内置的搜索。以下模型服务提供商提供原生网页搜索：

• OpenAI — GPT-4.1、GPT-4.1 Mini、GPT-4.1 Nano、GPT-5 及之后的版本、o3、o3 Pro、o4-mini
• Anthropic — Claude 3.5 Haiku、Claude 3.7 Sonnet、Claude 4 及之后的版本（所有 Opus/Sonnet 变体）
• Google — Gemini 3 Flash、Gemini 3 Pro、Gemini 3.1 Flash/Lite、Gemini 3.5 Flash
• SpaceXAI — Grok 4 及之后的版本（同时包含网页搜索和 X 搜索）
• Perplexity — 所有 Perplexity 模型（搜索是其 API 的核心能力）

你可以在对应的模型页面查看特定模型是否支持原生搜索——留意 “Web Search” 能力徽章。对于没有原生搜索的模型，将 engine 设为其他受支持的选项（Exa、Firecrawl、Parallel 或 Perplexity）——或保持 "auto" 以默认使用 Exa。

引擎选择

Web 搜索服务端工具支持多种搜索引擎：

• auto（默认）：若模型服务提供商支持原生搜索则使用原生搜索，否则回退到 Exa
• native：优先使用服务提供商内置的网页搜索；若模型不支持原生搜索则回退到 Exa
• exa：使用 Exa 的搜索 API，结合关键词搜索与基于嵌入的搜索。返回 Exa 高亮摘录（highlights）——从各页面中抽取与搜索查询最相关的片段——而不是截断后的整页文本。详见下文 Exa 一节。
• firecrawl：使用 Firecrawl 的搜索 API（自带密钥，BYOK）
• parallel：使用 Parallel 的搜索 API
• perplexity：使用 Perplexity Search API，返回带排名的网页结果，并支持域名过滤、上下文大小控制和 max_characters

引擎能力

Exa

OpenRouter 会为每条结果请求 Exa 高亮摘录（highlights），而不是 text 内容选项。高亮摘录是直接从页面抽取、并由 Exa 判定为与搜索查询最相关的片段，对于智能体网页工具而言，通常能以更少的 Token 提供更高质量的上下文，优于截断后的整页文本。

Exa 的 mode 控制搜索延迟与深度。默认仍为 auto：

默认情况下，Exa 会按查询和文档自适应选择高亮摘录长度——通常每条结果约 2,000–4,000 个字符。你可以通过两种方式控制每条结果的字符预算：

通过 search_context_size 使用粗粒度预设 — 映射到 Exa 的 contents.highlights.maxCharacters：

• low — 每条结果 5,000 个字符
• medium — 每条结果 15,000 个字符
• high — 每条结果 30,000 个字符

通过 max_characters 指定精确值 — 传入任意整数（1–100,000）以设置精确的每条结果内容预算。Exa、Parallel 和 Perplexity 均支持。若同时设置 max_characters 和 search_context_size，以 max_characters 为准。

{
  "type": "openrouter:web_search",
  "parameters": {
    "engine": "exa",
    "max_characters": 2000
  }
}

若既未设置 max_characters 也未设置 search_context_size，OpenRouter 会让 Exa 自适应选择高亮摘录长度，而 Parallel 使用每条结果 1,500 个字符的默认值。所选片段会随每条结果返回给模型，并通过 url_citation 注解呈现给 API 调用方。在同一条结果内，来自页面不同位置的片段会用 Exa 的 [...] 标记分隔，因此 url_citation 注解的 content 字段可能如下所示：

从页面中抽取的第一段摘录。
[...]
从同一页面其他位置抽取的第二段摘录。
[...]
第三段摘录。

Firecrawl（自带密钥，BYOK）

Firecrawl 使用你自己的 API 密钥。设置步骤：

1. 前往 OpenRouter 插件设置，将网页搜索引擎选为 Firecrawl
2. 接受 Firecrawl 服务条款——这会创建一个与你的邮箱关联的 Firecrawl 账户
3. 账户初始赠送 10,000 免费额度（额度在 3 个月后过期）

Firecrawl 搜索直接消耗你的 Firecrawl 额度——OpenRouter 不额外收费。每次搜索按每 10 条结果消耗 2 额度，外加每条抓取结果 5 额度（1 次基础抓取 + 4 次高亮摘录提取）。例如，返回 5 条结果的搜索会消耗 27 个 Firecrawl 额度（2 次搜索 + 5×5 次抓取）。详见 Firecrawl 定价。

Firecrawl 支持域名过滤（allowed_domains / excluded_domains），但二者互斥——不能在同一次请求中同时使用。

Parallel

Parallel 支持域名过滤和上下文大小控制（search_context_size）。设置 mode 以选择服务提供商模式；OpenRouter 会保留现有的 turbo 默认值并显式发送。

每种模式最多包含 10 条结果。额外结果按每 1,000 条 $1 计费。

Perplexity

Perplexity 返回带排名的网页结果（标题、URL、摘要片段），不进行 LLM 综合。它支持域名过滤（allowed_domains / excluded_domains，互斥）、search_context_size 和 max_characters。使用 OpenRouter 额度，每次请求 $0.005。

域名过滤

使用 allowed_domains 和 excluded_domains 限制搜索结果中出现的域名：

{
  "type": "openrouter:web_search",
  "parameters": {
    "allowed_domains": ["arxiv.org", "nature.com"],
    "excluded_domains": ["reddit.com"]
  }
}

控制结果总数

当模型在单次请求中多次搜索时，使用 max_total_results 限制累计结果数：

{
  "type": "openrouter:web_search",
  "parameters": {
    "max_results": 5,
    "max_total_results": 15
  }
}

达到上限后，后续搜索调用会向模型返回一条提示已达上限的消息，而不是再执行一次搜索。这有助于控制智能体循环中的费用和上下文窗口占用。

限制搜索次数

要硬性限制模型在单次请求中最多可执行多少次搜索，在工具的 parameters 中设置 max_uses（与 Anthropic 原生网页搜索的 max_uses 对齐）：

{
  "type": "openrouter:web_search",
  "parameters": {
    "max_uses": 3
  }
}

达到上限后，后续搜索调用会向模型返回一条提示已达上限的消息，而不是再执行一次搜索。使用模型服务提供商的原生搜索时，该值仅会转发给 Anthropic（作为其原生 max_uses）；其他原生搜索服务提供商没有等效参数，会忽略它。

每次搜索还会消耗请求整体服务端工具预算中的一步，该预算由所有服务端工具共享。设置顶层 max_tool_calls 请求字段（与 messages 和 tools 同级，不是工具参数）来限制该预算：

{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "tools": [{ "type": "openrouter:web_search" }],
  "max_tool_calls": 5
}

省略时，预算默认为 30 步，这也是最大值。若需更精细的控制（消费上限、自定义停止条件），使用 stop_server_tools_when，它会完全覆盖 max_tool_calls。各服务端工具的预算如何工作，详见工具调用限制。

也可用于 Responses API

Web 搜索服务端工具也可用于 Responses API：

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    input: '比特币当前价格是多少？',
    tools: [
      { type: 'openrouter:web_search', parameters: { max_results: 3 } }
    ]
  }),
});

const data = await response.json();
console.log(data);

用量追踪

网页搜索用量会在响应的 usage 对象中报告：

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 250,
    "server_tool_use": {
      "web_search_requests": 2
    }
  }
}

web_search_requests 字段统计模型在该请求期间发起的搜索查询总数。

定价

以上费用均叠加在处理搜索结果内容所产生的标准 LLM Token 费用之上。

从 Web 搜索插件迁移

主要区别：

迁移示例

// 迁移前（已弃用）
{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "plugins": [{ "id": "web", "max_results": 3 }]
}

// 迁移后
{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "tools": [
    { "type": "openrouter:web_search", "parameters": { "max_results": 3 } }
  ]
}

// 迁移前（已弃用）— 引擎与域名过滤
{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "plugins": [{
    "id": "web",
    "engine": "exa",
    "max_results": 5,
    "include_domains": ["arxiv.org"]
  }]
}

// 迁移后
{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "tools": [{
    "type": "openrouter:web_search",
    "parameters": {
      "engine": "exa",
      "max_results": 5,
      "allowed_domains": ["arxiv.org"]
    }
  }]
}

// 迁移前（已弃用）— :online 变体
{
  "model": "openai/gpt-5.2:online"
}

// 迁移后
{
  "model": "openai/gpt-5.2",
  "tools": [{ "type": "openrouter:web_search" }]
}

后续步骤

• 服务端工具概览 — 了解服务端工具
• Datetime — 获取当前日期和时间
• 工具调用 — 了解用户自定义工具调用