Web Fetch（网页内容获取）

web_fetch 工具执行普通 HTTP GET 请求并提取可读内容（HTML 转 Markdown 或纯文本）。它不执行 JavaScript。

对于 JS 密集型站点或需要登录的页面，请改用 Web 浏览器。

快速开始

web_fetch 默认启用——无需任何配置，代理可立即调用：

await web_fetch({ url: "https://example.com/article" });

工具参数

参数	类型	描述
url	string	要获取的 URL（必填，仅 http/https）
extractMode	string	"markdown"（默认）或 "text"
maxChars	number	将输出截断至此字符数

工作原理

第一步：获取

发送带有 Chrome-like User-Agent 和 Accept-Language 头的 HTTP GET 请求，阻止私有/内部主机名，并在重定向时重新检查。

第二步：提取

对 HTML 响应运行 Readability（主内容提取）。

第三步：备用（可选）

若 Readability 失败且已配置 Firecrawl，通过 Firecrawl API 以反爬模式重试。

第四步：缓存

结果缓存 15 分钟（可配置）以减少对同一 URL 的重复获取。

配置

{
  tools: {
    web: {
      fetch: {
        enabled: true, // 默认：true
        maxChars: 50000, // 最大输出字符数
        maxCharsCap: 50000, // maxChars 参数的硬性上限
        maxResponseBytes: 2000000, // 截断前的最大下载大小
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true, // 使用 Readability 提取
        userAgent: "Mozilla/5.0 ...", // 覆盖 User-Agent
      },
    },
  },
}

Firecrawl 备用方案

若 Readability 提取失败，web_fetch 可以回退到 Firecrawl 以实现反爬和更好的提取效果：

{
  tools: {
    web: {
      fetch: {
        firecrawl: {
          enabled: true,
          apiKey: "fc-...", // 若已设置 FIRECRAWL_API_KEY 可省略
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // 缓存时长（1 天）
          timeoutSeconds: 60,
        },
      },
    },
  },
}

tools.web.fetch.firecrawl.apiKey 支持 SecretRef 对象。

若 Firecrawl 已启用且其 SecretRef 未解析、也无 FIRECRAWL_API_KEY 环境变量回退，网关启动时会快速失败。

限制与安全

• maxChars 被钳制到 tools.web.fetch.maxCharsCap
• 响应正文在解析前被限制为 maxResponseBytes；超大响应被截断并附带警告
• 私有/内部主机名被阻止
• 重定向受 maxRedirects 检查和限制
• web_fetch 是尽力而为的——某些站点需要使用 Web 浏览器

工具配置文件

若使用工具配置文件或白名单，添加 web_fetch 或 group:web：

{
  tools: {
    allow: ["web_fetch"],
    // 或：allow: ["group:web"]（包含 web_fetch 和 web_search）
  },
}

相关链接

• 网页搜索（Web Search）——使用多个提供商搜索网页
• Web 浏览器——用于 JS 密集型站点的完整浏览器自动化
• Firecrawl——Firecrawl 搜索和爬取工具