Web Fetch
web_fetch 执行简单的 HTTP GET 并提取可读内容(将 HTML 转换为 markdown 或文本)。它不会执行 JavaScript。对于重度依赖 JS 的站点或需要登录的页面,请改用 Web Browser。
快速开始¶
默认启用,无需配置:
工具参数¶
urlstring (path) required- 要获取的 URL。仅支持
http(s)。 extractMode'markdown' | 'text' (path) default:markdown- 主内容提取后的输出格式。
maxCharsnumber (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 仅在获取在五秒后仍处于待处理状态时发出公开的进度行:
快速缓存命中和快速网络响应会在计时器触发前完成,因此它们永远不会显示进度行。取消调用会清除计时器。进度行仅是频道 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