Web Search 插件（已废弃）允许为任意模型附加实时网页搜索结果，最简单的方式是在模型 ID 后追加 :online（如 openai/gpt-4o:online）。底层支持 native（Anthropic/OpenAI/Perplexity/xAI 原生）、Exa、Firecrawl（BYOK）和 Parallel 四种搜索引擎。推荐迁移到 openrouter:web_search server tool，后者允许模型按需决定是否搜索，而不是每次请求都强制执行。

OpenRouter Web Search 插件

已废弃：Web Search 插件已废弃。推荐改用 openrouter:web_search server tool——Server tools 让模型自主决定何时、是否搜索，比插件的"每次必搜"更灵活。

Web Search 插件让任意模型都能获取实时网页搜索结果，对不原生支持搜索的模型尤其有用。

快速使用：:online 模型变体

在任意模型 ID 后追加 :online 即可启用网页搜索，这是最简便的方式：

{ "model": "openai/gpt-4o:online" }

也可以与 :free 变体组合使用：

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

注意：即使对免费模型，使用网页搜索也会产生额外费用（见下方定价）。

:online 等同于：

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

搜索结果格式

OpenRouter 将所有搜索引擎的结果统一为 OpenAI Chat Completion Message 的 annotation 格式，响应中包含 annotations 数组：

{
  "message": {
    "role": "assistant",
    "content": "以下是我找到的最新信息：...",
    "annotations": [
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://www.example.com/article",
          "title": "文章标题",
          "content": "摘要内容（如有）",
          "start_index": 100,
          "end_index": 200
        }
      }
    ]
  }
}

自定义插件配置

{
  "model": "openai/gpt-4o:online",
  "plugins": [
    {
      "id": "web",
      "engine": "exa",
      "max_results": 3,
      "search_prompt": "以下是相关网页内容：",
      "include_domains": ["example.com", "*.substack.com"],
      "exclude_domains": ["reddit.com"]
    }
  ]
}

搜索引擎选择

引擎值	说明
不指定（默认）	支持原生搜索的模型使用 native，否则回退 Exa
native	强制使用提供商内置搜索（不支持时报错）
exa	使用 Exa 搜索 API
firecrawl	使用 Firecrawl（BYOK，需在设置中配置）
parallel	使用 Parallel 搜索 API

Firecrawl（BYOK）

1. 在 插件设置 中选择 Firecrawl 作为搜索引擎
2. 接受 Firecrawl 服务条款（自动创建与你邮箱关联的账户）
3. 初始获赠 免费 100,000 积分
4. 搜索费用从你的 Firecrawl 积分中扣除，OpenRouter 不额外收费

Parallel

支持域名过滤，按 $4/1000 条结果收费（与 Exa 相同）。

域名过滤

引擎	include_domains	exclude_domains	备注
Exa	✅	✅	可同时使用
Parallel	✅	✅	互斥（只能用其中一个）
Native	取决于提供商	取决于提供商	见下方说明
Firecrawl	❌	❌	设置了会返回 400

原生搜索各提供商的域名过滤支持：

• Anthropic：支持两者，但互斥
• OpenAI：仅支持 include_domains
• xAI：支持两者，互斥，每项最多 5 个域名

xAI X Search 过滤参数

对 xAI 模型（如 Grok）启用 web 插件时，自动添加 X/Twitter 搜索能力。通过 x_search_filter 参数过滤 X 搜索结果：

{
  "model": "x-ai/grok-3-fast",
  "plugins": [{ "id": "web" }],
  "x_search_filter": {
    "allowed_x_handles": ["OpenRouterAI"],
    "from_date": "2025-01-01",
    "to_date": "2025-12-31",
    "enable_image_understanding": true
  }
}

参数	类型	说明
allowed_x_handles	string[]	仅包含这些账号的帖子（最多 10 个）
excluded_x_handles	string[]	排除这些账号的帖子（最多 10 个，与 allowed 互斥）
from_date	string	搜索起始日期（ISO 8601）
to_date	string	搜索截止日期（ISO 8601）
enable_image_understanding	boolean	启用帖子内图片分析
enable_video_understanding	boolean	启用帖子内视频分析

定价

引擎	费用
Exa（默认或明确指定）	$4/1000 条结果；默认 5 条 = 每次最多 $0.02
Native（原生）	按各提供商定价直接转计
Parallel	$4/1000 条结果
Firecrawl	消耗你的 Firecrawl 积分，不经 OpenRouter

原生搜索还支持 web_search_options.search_context_size（low/medium/high）控制搜索上下文量，影响成本和结果质量。

---

常见问题

Q: 什么时候该用 server tool，什么时候用 web 插件？

A: 新项目推荐用 openrouter:web_search server tool——它让模型自主决定是否搜索，避免对不需要搜索的请求也产生费用。web 插件每次请求都会执行搜索，适合历史项目兼容或需要强制搜索的场景。

Q: 搜索结果会影响 token 用量吗？

A: 是的。搜索结果会以文本形式注入到提示中，增加 prompt token 数量，产生额外的 LLM 费用（叠加在搜索本身费用之上）。

Q: :online 和直接指定 plugins: [{id: "web"}] 有什么区别？

A: 功能完全等价，:online 只是更简洁的写法。指定 plugins 数组的方式额外支持 engine、max_results、域名过滤等参数。