openrouter:web_fetch 是 OpenRouter 的 Server Tool（Beta），让任何 LLM 模型都能在推理过程中抓取指定 URL 的网页或 PDF 内容。模型收到需要读取 URL 的请求时，调用该工具；OpenRouter 在服务端执行抓取，提取文本内容后返回给模型，模型再将内容融入回复。支持五种 fetch 引擎：auto（默认，优先使用 provider 原生能力，回退到 Exa）、native、exa、openrouter、firecrawl（BYOK）。可通过 parameters 配置最大调用次数、内容 token 上限、域名白名单/黑名单。费用：Exa 每 1000 次 $1（BYOK 免费）、OpenRouter 引擎免费、Firecrawl 使用自己的 credits。

openrouter:web_fetch Server Tool（目前为 Beta）让任何 LLM 模型都能在一次 API 调用中抓取 URL 内容，无需客户端单独实现网页抓取逻辑。

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

工作原理

1. 在 tools 数组中包含 { "type": "openrouter:web_fetch" }
2. 模型根据用户请求决定是否需要抓取 URL，并生成抓取请求
3. OpenRouter 使用配置的引擎（默认 auto，优先使用 provider 原生能力，回退到 Exa）抓取 URL
4. 页面内容（文本、标题、URL）返回给模型
5. 模型将内容融入回复，必要时可在一次请求中抓取多个 URL

快速开始

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: '总结 https://example.com/article 这篇文章的内容'
      }
    ],
    tools: [
      { type: 'openrouter:web_fetch' }
    ]
  }),
});

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

参数配置

可通过 parameters 自定义抓取行为：

{
  "type": "openrouter:web_fetch",
  "parameters": {
    "engine": "exa",
    "max_uses": 10,
    "max_content_tokens": 100000,
    "allowed_domains": ["docs.example.com"],
    "blocked_domains": ["private.example.com"]
  }
}

参数	类型	默认值	说明
engine	string	auto	抓取引擎：auto、native、exa、openrouter、firecrawl
max_uses	integer	—	单次请求最多抓取次数，超出后返回错误
max_content_tokens	integer	—	返回内容的最大 token 数，超出部分截断
allowed_domains	string[]	—	只抓取这些域名下的 URL
blocked_domains	string[]	—	禁止抓取这些域名下的 URL

引擎选择

引擎	说明
auto（默认）	优先使用 provider 原生能力，不支持时回退到 Exa
native	强制使用 provider 内置 web fetch
exa	使用 Exa 的 Contents API 提取页面内容，支持 BYOK
openrouter	直接 HTTP 抓取并提取内容
firecrawl	使用 Firecrawl 的 scrape API（BYOK，需自备密钥）

引擎能力对比

功能	Exa	Firecrawl	OpenRouter	Native
域名过滤	✓	✓	✓	视 provider
内容截断	✓	✓	✓	✗
API Key	服务端或 BYOK	BYOK（自备）	服务端	Provider 处理
硬性上限	无	无	50 次/请求	50 次/请求

Firecrawl（BYOK）

使用自己的 Firecrawl API Key：

1. 前往 OpenRouter 插件设置 配置 Firecrawl API Key
2. 抓取费用直接走你自己的 Firecrawl 账户，OpenRouter 不额外收费

域名过滤

{
  "type": "openrouter:web_fetch",
  "parameters": {
    "allowed_domains": ["docs.example.com", "api.example.com"],
    "blocked_domains": ["internal.example.com"]
  }
}

设置 allowed_domains 后，只抓取这些域名下的 URL；设置 blocked_domains 后，这些域名的请求会被拒绝。

内容截断

{
  "type": "openrouter:web_fetch",
  "parameters": {
    "max_content_tokens": 50000
  }
}

超出限制的内容会被截断，适合控制大页面对 context window 的占用。

Responses API 支持

也可在 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: '这个文档说了什么？https://example.com/docs',
    tools: [
      { type: 'openrouter:web_fetch', parameters: { max_content_tokens: 50000 } }
    ]
  }),
});

响应格式

工具调用成功时返回：

{
  "url": "https://example.com/article",
  "title": "Article Title",
  "content": "页面的完整文本内容...",
  "status": "completed",
  "retrieved_at": "2025-07-15T14:30:00.000Z"
}

抓取失败时：

{
  "url": "https://example.com/404",
  "status": "failed",
  "error": "HTTP 404: Page not found"
}

费用

引擎	费用
Exa	每 1000 次抓取 $1（配置自己的 Exa API Key 后免费）
Firecrawl	直接使用你的 Firecrawl credits，OpenRouter 不收费
OpenRouter	免费
Native	由 provider 收费

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

Exa BYOK

在 provider 设置 中配置自己的 Exa API Key 后，Exa 引擎的抓取费用直接向 Exa 支付，OpenRouter 不再收取每次 $0.001 的费用。

常见问题

Q: web_fetch 和 web_search 工具有什么区别？

A: web_fetch 用于抓取已知 URL 的完整内容（网页正文、PDF），适合总结、引用特定文档；web_search 用于搜索未知内容，返回搜索结果列表（标题 + 摘要），适合获取实时信息。可以组合使用：先搜索找到相关 URL，再用 web_fetch 读取完整内容。

Q: max_content_tokens 是精确限制还是近似值？

A: 近似值。max_content_tokens 是对内容长度的 token 估算，实际返回内容可能稍有浮动。建议设置比实际需要稍小的值（如需 50K tokens 内，设 45000）留出余量。

Q: 模型一定会抓取 URL 吗？

A: 不一定。模型会根据请求自主判断是否需要抓取。用户明确提到"读取这个链接"时大概率触发；对于含 URL 的模糊问题，模型可能选择基于已有知识回答。如需确保触发，可在系统提示中明确说明。