OpenRouter Server Tools 网页搜索工具：为任意模型提供实时搜索能力

openrouter:web_search 是 OpenRouter 的 Server Tool（Beta），让任何 LLM 模型都能在推理过程中执行实时网络搜索。只需在 tools 数组中添加该工具，模型即可根据请求内容自主决定是否搜索、搜索几次，并将结果融入回复。支持五种搜索引擎：auto（默认）、native（provider 原生）、exa、firecrawl（BYOK）、parallel。可配置 max_results（单次搜索结果数）、max_total_results（整个请求的总结果上限）、search_context_size（每条结果的内容详细程度）和域名过滤。用量记录在响应 usage.server_tool_use.web_search_requests 中。本文还提供从旧版 Web Search Plugin（plugins 数组方式）迁移到新版的完整对照示例。

openrouter:web_search Server Tool（目前为 Beta）让任何 OpenRouter 模型都能获取实时网络信息。模型判断需要当前数据时，调用该工具执行搜索；OpenRouter 返回结果，模型据此生成有据可查的回复。

Beta 提醒：Server Tools 目前处于 Beta 阶段，API 和行为可能会有变更。

工作原理 #

1. 在 tools 数组中包含 { "type": "openrouter:web_search" }
2. 模型根据用户请求决定是否需要搜索，并生成搜索词
3. OpenRouter 使用配置的引擎执行搜索（默认 auto，优先 provider 原生，回退到 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-4o',
    messages: [
      {
        role: 'user',
        content: '本周 AI 领域有哪些重大进展？'
      }
    ],
    tools: [
      { type: 'openrouter:web_search' }
    ]
  }),
});

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

参数配置 #

{
  "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": "Beijing",
      "region": "Beijing",
      "country": "CN",
      "timezone": "Asia/Shanghai"
    }
  }
}

所有字段均为可选。

引擎选择 #

引擎能力对比 #

域名过滤 #

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

各引擎域名过滤支持情况：

控制总结果数 #

在 Agent 循环中控制费用和 context 用量：

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

达到上限后，后续搜索调用会返回"已达到限制"提示，不再执行真实搜索。

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-4o',
    input: '今天比特币价格是多少？',
    tools: [
      { type: 'openrouter:web_search', parameters: { max_results: 3 } }
    ]
  }),
});

用量追踪 #

搜索用量记录在响应 usage 对象中：

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

web_search_requests 记录模型在这次请求中发起的搜索次数。

费用 #

费用均叠加在处理请求和响应的标准 LLM token 费用之上。

从旧版 Web Search Plugin 迁移 #

旧版 plugins 数组方式已弃用，请迁移到新版 tools 数组方式。

主要差异：

迁移示例：

// 旧版（已弃用）
{
  "model": "openai/gpt-4o",
  "messages": [...],
  "plugins": [{ "id": "web", "max_results": 3 }]
}

// 新版
{
  "model": "openai/gpt-4o",
  "messages": [...],
  "tools": [
    { "type": "openrouter:web_search", "parameters": { "max_results": 3 } }
  ]
}

// 旧版（:online 变体）
{ "model": "openai/gpt-4o:online" }

// 新版
{
  "model": "openai/gpt-4o",
  "tools": [{ "type": "openrouter:web_search" }]
}

常见问题 #

Q: 模型一定会搜索吗？

A: 不一定。模型自主判断是否需要搜索。用户问"今天 XX 新闻"时大概率触发；问历史知识时可能直接回答。如需确保触发，可在系统提示中明确说明"当用户问到时效性问题时，必须使用搜索工具"。

Q: 如何控制搜索费用？

A: 使用 max_total_results 限制整个请求中所有搜索的总结果数。例如设置为 10，模型最多获取 10 条结果后就不能再搜索了。对于 Agent 循环场景，这是控制费用最有效的参数。

Q: Exa 和 Parallel 引擎的区别是什么？

A: 两者费用相同（每 1000 条 $4），都支持域名过滤。主要差异在内容量控制：Exa 的 search_context_size 控制每条结果的字符数；Parallel 的 search_context_size 控制所有结果的总字符数。如果需要精确控制每条结果的信息量，选 Exa；需要控制总 token 消耗，选 Parallel。