跳转至

Web Fetch

web_fetch 执行简单的 HTTP GET 并提取可读内容(将 HTML 转换为 markdown 或文本)。它不会执行 JavaScript。对于重度依赖 JS 的站点或需要登录的页面,请改用 Web Browser。

快速开始

默认启用,无需配置:

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

工具参数

url string (path) required
要获取的 URL。仅支持 http(s)。
extractMode 'markdown' | 'text' (path) default: markdown
主内容提取后的输出格式。
maxChars number (path)
将输出截断为该字符数。上限为 tools.web.fetch.maxCharsCap。

结果

web_fetch 返回包含以下字段的封闭式结构化结果:

  • 请求元数据:url、finalUrl、status、extractMode 和 extractor
  • 可选响应元数据:contentType、title 和 warning(不存在时省略)
  • 包装内容元数据:externalContent、truncated、length、rawLength、fetchedAt、tookMs 和 text
  • 命中缓存时可选的 cached: true
  • 当截断的内容写入私有临时文件时,可选的 spill: { path, chars, truncated? };仅当该文件包含部分源内容时才存在 truncated

length 是包装后的 text 长度。rawLength 是外部内容包装之前的提取内容长度。

text、title 和 warning 共享 maxChars,包括它们的内容包装。标题和警告各自最多保留 256 个字符,包装后的总配额最多为 512 个字符,同时不超过 maxChars 的一半。警告优先于标题;未使用的元数据空间仍可供正文使用。当元数据被缩短或省略时,truncated 也为 true;仅元数据截断不会创建正文 spill 文件。

JSON 分帧和协议元数据是额外开销。contentType、extractor 和 fetchedAt 分别限制为 256、128 和 64 个字符。URL 保持完整以便后续请求:返回的重定向/提供商 URL 超过 2,048 个字符时,回退到请求的 url 并将结果标记为已截断。调用者请求的 URL 会被保留。

工作原理

1. 获取

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

2. 提取

对 HTML 响应运行 Readability(主内容提取)。

3. 回退(可选)

如果 Readability 失败且存在可用的获取提供商,则通过该提供商重试(例如 Firecrawl 的反爬虫规避模式)。

4. 缓存

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

设置 tools.web.fetch.cacheTtlMinutes: 0 可让 OpenClaw 的获取缓存在读取和写入时都被绕过。正值会根据当前请求的 TTL 限制复用;缓存条目仍会在原始截止时间过期。提供商侧的缓存(例如 Firecrawl 的 maxAgeMs)需单独配置。

进度更新

web_fetch 仅在获取在五秒后仍处于待处理状态时发出公开的进度行:

Fetching page content...

快速缓存命中和快速网络响应会在计时器触发前完成,因此它们永远不会显示进度行。取消调用会清除计时器。进度行仅是频道 UI 状态,绝不包含获取到的页面内容。

OpenClaw 将取消传递给回退提供商。遵守该信号的提供商可以停止其请求;即使提供商忽略取消,核心也会拒绝延迟结果。即使存在缓存结果,已经取消的调用也会被拒绝。如果取消发生在获取、回退处理或连接清理期间,OpenClaw 会拒绝该调用,而不是返回成功或将结果添加到获取缓存中。

配置

{
  tools: {
    web: {
      fetch: {
        enabled: true, // default: true
        provider: "firecrawl", // optional; omit for auto-detect
        maxChars: 20000, // default output chars; capped by maxCharsCap
        maxCharsCap: 20000, // hard cap for maxChars param
        maxResponseBytes: 750000, // max download size before truncation (32000-10000000)
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS
        readability: true, // use Readability extraction
        userAgent: "Mozilla/5.0 ...", // override User-Agent
        headers: {
          // optional; every value is treated as sensitive
          "X-Routing-Target": "staging",
        },
        ssrfPolicy: {
          dangerouslyAllowPrivateNetwork: false, // broad private-network opt-in; keep false by default
          allowedHostnames: ["internal.example"], // narrow exact host exception
          allowRfc2544BenchmarkRange: true, // opt-in for trusted fake-IP proxies using 198.18.0.0/15
          allowIpv6UniqueLocalRange: true, // opt-in for trusted fake-IP proxies using fc00::/7
        },
      },
    },
  },
}

Firecrawl 回退

如果 Readability 提取失败,web_fetch 可以回退到 Firecrawl 以进行反爬虫规避并获得更好的提取效果:

{
  tools: {
    web: {
      fetch: {
        provider: "firecrawl", // optional; omit for auto-detect from available credentials
      },
    },
  },
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
        config: {
          webFetch: {
            // apiKey: "fc-...", // optional; omit for keyless starter access
            baseUrl: "https://api.firecrawl.dev",
            onlyMainContent: true,
            maxAgeMs: 172800000, // cache duration (2 days)
            timeoutSeconds: 60,
          },
        },
      },
    },
  },
}

plugins.entries.firecrawl.config.webFetch.apiKey 是可选的,且支持 SecretRef 对象。旧版 tools.web.fetch.firecrawl.* 配置会通过 openclaw doctor --fix 自动迁移到 plugins.entries.firecrawl.config.webFetch。

Note

如果你配置了 Firecrawl API 密钥的 SecretRef,但该引用无法解析且没有 FIRECRAWL_API_KEY 环境变量作为回退,网关启动将快速失败。

Note

Firecrawl 的 baseUrl 覆盖受到严格限制:托管流量使用 https://api.firecrawl.dev;自托管覆盖必须指向私有或内部端点,且仅对这些私有目标接受 http://。

当前运行时行为:

  • tools.web.fetch.provider 显式选择抓取回退提供程序。
  • 如果省略 provider,OpenClaw 会根据已配置的凭据自动检测第一个可用的 web-fetch 提供程序。非沙箱化的 web_fetch 可以使用已安装的、声明了 contracts.webFetchProviders 并在运行时注册匹配提供程序的插件。目前官方 Firecrawl 插件提供了这一回退能力。
  • 沙箱化的 web_fetch 调用允许内置提供程序,以及已通过官方 npm 或 ClawHub 来源验证的已安装提供程序。目前这允许官方 Firecrawl 插件;第三方外部抓取插件仍被排除在外。
  • 如果禁用了 Readability,web_fetch 将直接跳转到所选提供程序回退。如果没有可用提供程序,则按失败关闭(fail closed)处理。

自定义请求头

当你的部署需要在出站抓取请求上附带额外请求元数据时(例如用于将流量导向你所控制网关的路由头或服务注入头),请设置 tools.web.fetch.headers。

{
  tools: {
    web: {
      fetch: {
        headers: {
          "X-Routing-Target": "${WEB_FETCH_ROUTING_TARGET}",
        },
      },
    },
  },
}

Warning

每个已配置的值都被视为敏感信息,并会从暴露的配置和调试信息中编辑隐藏。这些请求头仍会发送给 web_fetch 请求的每个初始 URL,而该 URL 是由模型选择的。仅当这符合预期的信任边界时,才配置凭据请求头。

值得了解的行为:

  • 值必须是普通字符串,并像其他配置字符串一样支持 ${VAR} 环境变量替换。不接受结构化的 SecretRef 值。
  • 这些请求头仅适用于直接的 web_fetch 请求。诸如 Firecrawl 之类的提供程序回退会调用其自有 API,绝不会收到这些请求头。
  • 请求头条目在构建请求时而非配置加载时验证,因此单个错误条目会被丢弃,其余条目仍然生效。配置加载刻意保持宽松:仅因某个请求头名称拼写错误而触发失败关闭式校验错误,会禁用整个功能面。每个被丢弃的条目都会按名称记录日志。
  • 被丢弃的名称:
  • Accept、Accept-Language 和 User-Agent 属于抓取与可读性契约的一部分。请使用 tools.web.fetch.userAgent 设置用户代理。
  • 帧头与逐跳(hop-by-hop)名称,如 Content-Length、Transfer-Encoding、Connection 和 Upgrade,这类请求头会被请求直接拒绝或忽略。
  • 不是有效 HTTP 令牌的名称,例如 "X Routing Target"。
  • 被丢弃的值:请求无法承载的字节(CR、LF、NUL 或任何高于 U+00FF 的字符)。缺失的环境变量会在配置加载时报告;当确实需要字面量 ${VAR} 文本时,全局 $${VAR} 转义仍可使用。
  • 两个仅名称大小写不同的条目会合并为后一个条目,因此请求绝不会携带接收网关无法解析的逗号拼接值。被丢弃的名称会以不包含任一值的方式记录。如果后一个条目不可用,则两个值都不会发送。
  • 拒绝发生在缓存键计算之前,因此缓存键始终与实际发送的字节一致:修改一个真正会发送的请求头会使抓取缓存分区失效,而添加一个会被丢弃的请求头则不会。
  • 当重定向跨源时,会应用受保护抓取(guarded-fetch)的安全白名单。该列表之外的路由请求头会被丢弃;标准安全请求头(如 Cache-Control、Content-Type 和 Range)则会被保留。

可信环境代理

如果你的部署要求 web_fetch 通过可信的出站 HTTP(S) 代理访问,请设置 tools.web.fetch.useTrustedEnvProxy: true。

在此模式下,OpenClaw 在发送请求前仍会应用基于主机名的 SSRF 检查,但会让代理负责 DNS 解析,而不是执行本地 DNS 固定(pinning)。仅在代理由运维人员控制并在 DNS 解析后强制实施出站策略时,才启用此选项。

Note

如果未配置 HTTP(S) 代理环境变量,或目标主机被 NO_PROXY 排除,web_fetch 将回退到使用本地 DNS 固定的常规严格路径。主机名匹配忽略大小写以及 URL 或 NO_PROXY 条目中末尾的一个 DNS 点。

限制与安全性

  • maxChars 被限制在 tools.web.fetch.maxCharsCap(默认 20000)以内
  • 在解析前,响应体被限制在 maxResponseBytes(默认 750000,限制范围为 32000-10000000)以内;超大响应会被截断并给出警告
  • 私有/内部主机名会被阻止
  • tools.web.fetch.ssrfPolicy.allowedHostnames 允许精确匹配的可信主机,同时保持其他私有/内部目标被阻止
  • tools.web.fetch.ssrfPolicy.blockedHostnames 会在 DNS 和允许规则之前拒绝精确主机和通配符子域,包括在重定向和启用私有网络访问时也生效。例如,["tracker.example.com", "*.ads.example.com"] 会阻止这些主机,而无需完整白名单。通配符不匹配根域;如需阻止 ads.example.com 需要单独添加。匹配忽略大小写和末尾点;国际化域名请使用 ASCII/Punycode。为空或未设置则不添加任何拒绝项。
  • tools.web.fetch.ssrfPolicy.dangerouslyAllowPrivateNetwork 广泛允许私有网络目标;仅当你的部署信任模型选定的 URL 时才启用
  • tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange 和 tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange 是针对可信伪 IP 代理栈的窄范围选择性启用项;除非你的代理拥有这些合成地址段并自行执行目标策略,否则请保持不设置
  • 重定向会经过检查并由 maxRedirects(默认 3)限制
  • tools.web.fetch.headers 的值会从暴露的配置和调试捕获中编辑隐藏,发送给初始抓取主机,并且仅在现有受保护抓取策略允许时才在重定向上保留
  • useTrustedEnvProxy 是显式选择启用项,只应为仍会在 DNS 解析后强制实施出站策略的运维控制代理启用
  • web_fetch 尽力而为——有些站点需要 Web Browser

工具配置

如果你使用工具配置或允许列表,请添加 web_fetch 或 group:web:

{
  tools: {
    allow: ["web_fetch"],
    // or: allow: ["group:web"]  (includes web_fetch, web_search, and x_search)
  },
}
  • Web Search -- 使用多个提供商搜索网络
  • Web Browser -- 针对 JS 密集型网站的完整浏览器自动化
  • Firecrawl -- Firecrawl 搜索和抓取工具

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw