Web 搜索

与模型无关的检索增强（grounding）

你可以通过启用并自定义 web 插件，或在模型 slug 后追加 :online，为 OpenRouter 上的任意模型引入相关 Web 搜索结果：

{
  "model": "openai/gpt-5.2:online"
}

你也可以将 :online 追加到 :free 模型变体，例如：

{
  "model": "openai/gpt-oss-20b:free:online"
}

:online 是使用 web 插件的快捷方式，完全等价于：

{
  "model": "openrouter/auto",
  "plugins": [{ "id": "web" }]
}

Web 搜索插件对 Anthropic、Google、OpenAI、Perplexity 和 SpaceXAI 模型使用原生搜索。各模型服务提供商支持的模型系列完整列表，见服务端工具 Web 搜索文档。

对其余模型，Web 搜索插件由 Exa 提供支持。它使用 Exa 的 "auto" 方法（关键词搜索与基于嵌入的 Web 搜索相结合），找出最相关的结果，并用来增强你的提示词、为其提供事实依据。对每条结果，OpenRouter 会向 Exa 请求高亮摘录（highlights）——即 Exa 判定与搜索查询最相关的页面摘录，长度自适应（通常每条结果约 2,000–4,000 个字符）。这些摘录会返回给模型，并通过 url_citation 注解呈现；同一页面不同位置的摘录之间，Exa 用 [...] 标记分隔。

解析 Web 搜索结果

所有模型（包括仅支持原生搜索的模型，如 Perplexity 和 OpenAI Online）的 Web 搜索结果都可以从 API 获取，并由 OpenRouter 标准化为 OpenAI Chat Completion Message 类型 中的同一套注解结构：

{
  "message": {
    "role": "assistant",
    "content": "这是我找到的最新消息：...",
    "annotations": [
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://www.example.com/web-search-result",
          "title": "Web 搜索结果的标题",
          "content": "Web 搜索结果的内容", // 若可用，由 OpenRouter 添加
          "start_index": 100, // 消息中 URL 引用的第一个字符的索引。
          "end_index": 200 // 消息中 URL 引用的最后一个字符的索引。
        }
      }
    ]
  }
}

自定义 Web 插件

Web 插件允许的最大结果数，以及把结果附加到消息流时使用的提示词，都可以自定义：

{
  "model": "openai/gpt-5.2:online",
  "plugins": [
    {
      "id": "web",
      "engine": "parallel", // 可选："native"、"exa"、"firecrawl"、"parallel"、"perplexity"，或不指定
      "mode": "turbo", // 可选；可接受的值取决于所选引擎
      "max_results": 1, // 默认为 5
      "search_prompt": "一些相关的网页结果：", // 默认值见下文
      "include_domains": ["example.com", "*.substack.com"], // 可选
      "exclude_domains": ["reddit.com"] // 可选
    }
  ]
}

默认情况下，Web 插件使用以下搜索提示词，其中包含当前日期：

A web search was conducted on `date`. Incorporate the following web search results into your response.

IMPORTANT: Cite them using markdown links named using the domain of the source.
Example: [nytimes.com](https://nytimes.com/some-page).

域名过滤

你可以使用 include_domains 和 exclude_domains 限制 Web 搜索结果中出现的域名：

{
  "model": "openai/gpt-5.2",
  "plugins": [
    {
      "id": "web",
      "include_domains": ["example.com", "*.substack.com"],
      "exclude_domains": ["reddit.com"]
    }
  ]
}

这两个字段都接受域名字符串数组。你可以使用通配符（*.substack.com）和路径过滤（openai.com/blog）。

引擎兼容性

原生模型服务提供商行为

使用原生搜索时，域名过滤支持取决于模型服务提供商：

• Anthropic：同时支持 include_domains 和 exclude_domains，但二者互斥——不能同时使用
• Google：不支持域名过滤。使用默认引擎（auto）时，若设置了过滤条件，OpenRouter 会回退到 Exa。使用 "engine": "native" 时返回 400 错误
• OpenAI：仅支持 include_domains；exclude_domains 会被静默忽略
• SpaceXAI：两者都支持，但互斥，且各自最多 5 个域名

X 搜索过滤（仅 SpaceXAI）

在启用 Web 搜索的情况下使用 SpaceXAI 模型时， OpenRouter 会自动在 web_search 之外加入 x_search 工具。 你可以通过顶层 x_search_filter 参数传入过滤条件， 以控制 X/Twitter 搜索结果：

{
  "model": "x-ai/grok-4.1-fast",
  "messages": [
    {
      "role": "user",
      "content": "大家在讨论 OpenRouter 什么？"
    }
  ],
  "plugins": [{ "id": "web" }],
  "x_search_filter": {
    "allowed_x_handles": ["OpenRouterAI"],
    "from_date": "2025-01-01",
    "to_date": "2025-12-31"
  }
}

过滤参数

引擎选择

Web 搜索插件的 engine 参数支持以下选项：

• native：始终使用模型服务提供商内置的 Web 搜索能力
• exa：使用 Exa 的搜索 API 获取网页结果
• firecrawl：使用 Firecrawl 的搜索 API
• parallel：使用 Parallel 的搜索 API 获取网页结果
• perplexity：使用 Perplexity Search API 获取排序后的网页结果
• undefined（未指定）：若该模型服务提供商支持原生搜索则使用原生搜索，否则回退到 Exa

默认行为

未指定 engine 参数时：

• 对支持原生搜索的 OpenAI、Anthropic、Google、Perplexity 和 SpaceXAI 模型，默认使用原生搜索
• 对所有其他模型，或在不支持原生搜索时，使用 Exa 搜索

当你显式指定 "engine": "native" 时，系统会始终尝试使用该模型服务提供商的原生搜索，即使模型并不支持（这可能导致错误）。

强制指定引擎

你可以显式指定要使用的引擎：

{
  "model": "openai/gpt-5.2",
  "plugins": [
    {
      "id": "web",
      "engine": "native"
    }
  ]
}

也可以对支持原生搜索的模型强制使用 Exa 搜索：

{
  "model": "openai/gpt-5.2",
  "plugins": [
    {
      "id": "web",
      "engine": "exa",
      "max_results": 3
    }
  ]
}

Firecrawl

Firecrawl 是自带密钥（BYOK）搜索引擎。使用方法：

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

设置完成后，Firecrawl 搜索会直接消耗你的 Firecrawl 额度——OpenRouter 不再额外收费。每次搜索每 10 条结果消耗 2 额度，外加每抓取一条结果消耗 5 额度（1 次基础抓取 + 4 次高亮摘录提取）。详见 Firecrawl 定价。

{
  "model": "openai/gpt-5.2",
  "plugins": [
    {
      "id": "web",
      "engine": "firecrawl",
      "max_results": 5
    }
  ]
}

Parallel

Parallel 是支持域名过滤的搜索引擎。当 engine 为 parallel 时设置 mode。OpenRouter 会保留现有的 turbo 默认值，并显式发送解析后的模式。

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

{
  "model": "openai/gpt-5.2",
  "plugins": [
    {
      "id": "web",
      "engine": "parallel",
      "mode": "advanced",
      "max_results": 5,
      "include_domains": ["arxiv.org"]
    }
  ]
}

Exa 模式

Exa 默认使用 auto。选择模式以权衡延迟与搜索深度：

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

{
  "model": "openai/gpt-5.2",
  "plugins": [
    {
      "id": "web",
      "engine": "exa",
      "mode": "deep-lite",
      "max_results": 5
    }
  ]
}

各引擎定价

• 原生搜索：价格由模型服务提供商直接透传（见下方各提供商定价信息）
• Exa 搜索：Instant、Fast 和 Auto 每次请求 $0.007；Deep Lite 和 Deep 为 $0.012；Deep Reasoning 为 $0.015。包含最多 10 条结果，之后每条额外结果 $0.001
• Parallel 搜索：Turbo 使用 OpenRouter 积分，每次请求 $0.001；Basic 和 Advanced 每次请求 $0.005。各自包含最多 10 条结果，之后每条额外结果 $0.001
• Perplexity 搜索：使用 OpenRouter 积分，每次请求 $0.005
• Firecrawl 搜索：直接消耗你的 Firecrawl 额度（每 10 条结果 2 额度 + 带高亮摘录的每次抓取 5 额度）。可在 Firecrawl.dev 充值

定价

Exa 搜索定价

使用 Exa 搜索时（通过 "engine": "exa" 显式指定，或作为回退），Web 插件会使用你的 OpenRouter 积分，并按所选 Exa 模式计费。Auto 仍是默认模式，每次请求 $0.007。这包含最多 10 条结果；额外结果每条 $0.001，此外还要计入搜索结果提示词 Token 的 LLM 用量。

原生搜索定价（模型服务提供商透传）

部分模型内置 Web 搜索。这些模型按搜索上下文规模收费，该规模决定一次查询检索并处理多少搜索数据。

搜索上下文规模阈值

搜索上下文可以是 low、medium 或 high，决定一次查询检索多少搜索上下文：

• Low：最少搜索上下文，适合基本查询
• Medium：中等搜索上下文，适合一般查询
• High：大量搜索上下文，适合详细研究

指定搜索上下文规模

你可以在 API 请求中使用 web_search_options 参数指定搜索上下文规模：

{
  "model": "openai/gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "量子计算有哪些最新进展？"
    }
  ],
  "web_search_options": {
    "search_context_size": "high"
  }
}