网页抓取

web_fetch 执行普通 HTTP GET，并提取可读内容（将 HTML 转换为 markdown 或 text）。它不执行 JavaScript。对于依赖 JS 的网站或需要登录保护的页面，请改用 Web Browser。

快速开始¶

默认启用，无需配置：

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

工具参数¶

url string (path) 必填: 要获取的 URL。仅支持 http(s)。
extractMode 'markdown' | 'text' (path) 默认：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；仅元数据截断不会创建正文溢出文件。

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 仅在获取在 5 秒后仍处于待处理状态时，才会发出公开的进度行：

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-key SecretRef 且其无法解析，并且没有 FIRECRAWL_API_KEY 环境变量回退，网关启动会快速失败。

Note

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

当前运行时行为：

tools.web.fetch.provider 显式选择抓取回退提供商。
如果省略 provider，OpenClaw 会从已配置的凭据中自动检测第一个就绪的网页抓取提供商。非沙箱化的 web_fetch 可以使用声明了 contracts.webFetchProviders 并在运行时注册匹配提供商的已安装插件。目前，官方 Firecrawl 插件提供此回退。
沙箱化的 web_fetch 调用允许使用内置提供商，以及经过官方 npm 或 ClawHub 来源验证的已安装提供商。目前这允许使用官方 Firecrawl 插件；第三方外部抓取插件仍被排除。
如果禁用 Readability，web_fetch 会直接跳到所选提供商回退。如果没有可用提供商，它会失败关闭。

自定义请求头¶

当你的部署需要在出站抓取中添加额外的请求元数据时，请设置 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。
帧结构和逐跳名称，例如 Content-Length、Transfer-Encoding、Connection 和 Upgrade，请求会直接拒绝或忽略这些名称。
不是有效 HTTP token 的名称，例如 "X Routing Target"。
被丢弃的值：请求无法承载的字节（CR、LF、NUL 或任何高于 U+00FF 的字符）。缺失的环境变量会由配置加载报告；当有意使用字面量 ${VAR} 文本时，全局 $${VAR} 转义仍然可用。
两个仅大小写不同的名称会合并为后面的条目，因此请求永远不会携带接收网关无法解析的逗号连接值。被丢弃的名称会记录日志，且不包含任一值。如果后面的条目不可用，则两个值都不会发送。
拒绝发生在计算缓存键之前，因此缓存键始终与实际发送的字节匹配：更改一个确实发送的请求头会使抓取缓存分区，而添加一个被丢弃的请求头则不会。
当重定向跨越源时，会应用受保护抓取的安全允许列表。不在该列表中的路由请求头会被丢弃；Cache-Control、Content-Type 和 Range 等标准安全请求头会被保留。

受信任的环境代理¶

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

在此模式下，OpenClaw 在发送请求前仍会应用基于主机名的 SSRF 检查，但会让代理解析 DNS，而不是执行本地 DNS 固定。仅当代理由操作员控制并在 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 是针对受信任的 fake-IP 代理栈的窄范围选择加入项；除非你的代理拥有这些合成范围并执行自己的目标策略，否则请保持未设置
重定向会被检查并受 maxRedirects（默认 3）限制
tools.web.fetch.headers 的值会从暴露的配置和调试捕获中删除，发送到初始抓取主机，并且仅在现有受保护抓取策略允许时，才会在重定向上保留
useTrustedEnvProxy 是显式选择加入项，应仅对仍在 DNS 解析后执行出站策略的操作员控制代理启用
web_fetch 是尽力而为的——某些站点需要网页浏览器

工具配置¶

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

{
  tools: {
    allow: ["web_fetch"],
    // or: allow: ["group:web"]  (includes web_fetch, web_search, and x_search)
  },
}

网络搜索 -- 使用多个提供商搜索网络
网络浏览器 -- 为 JS 密集型站点提供完整的浏览器自动化
Firecrawl -- Firecrawl 搜索和抓取工具

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

网页抓取

快速开始¶

工具参数¶

结果¶

工作原理¶

进度更新¶

配置¶

Firecrawl 回退¶

自定义请求头¶

受信任的环境代理¶

限制与安全¶

工具配置¶

相关¶