Appearance
web_fetch 是 OpenClaw 中默认启用的 HTTP GET 工具，无需配置即可直接调用，用于抓取 URL 并提取可读内容（Markdown 或纯文本）。关键配置包括缓存 TTL（默认 15 分钟）、最大输出字符数（上限 50000）、Firecrawl 备用方案（需单独配置插件）以及 SSRF 安全策略；如果 Readability 提取失败且已配置 Firecrawl，会自动回退。注意 web_fetch 不执行 JavaScript，JS 密集站点或需登录的页面请改用 Web Browser 工具。
OpenClaw web_fetch 配置与限制说明
web_fetch 工具执行普通 HTTP GET 请求并提取可读内容（HTML 转 Markdown 或纯文本）。它不执行 JavaScript。
对于 JS 密集型站点或需要登录的页面，请改用 Web Browser 工具。
快速开始
web_fetch 默认启用——无需任何配置，智能体可立即调用：
javascript
await web_fetch({ url: "https://example.com/article" });工具参数
| 参数 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
url | string | 是 | — | 要获取的 URL（仅 http/https） |
extractMode | 'markdown' | 'text' | 否 | 'markdown' | 主内容提取后的输出格式 |
maxChars | number | 否 | — | 将输出截断至此字符数 |
工作原理
- 获取：发送带有 Chrome 风格 User-Agent 和
Accept-Language头的 HTTP GET 请求，阻止私有/内部主机名，并在重定向时重新检查。 - 提取：对 HTML 响应运行 Readability（主内容提取）。
- 备用（可选）：若 Readability 失败且已配置 Firecrawl，通过 Firecrawl API 以反爬模式重试。
- 缓存：结果缓存 15 分钟（可配置）以减少对同一 URL 的重复获取。
配置
json5
{
tools: {
web: {
fetch: {
enabled: true, // 默认：true
provider: "firecrawl", // 可选；省略则自动检测可用凭证
maxChars: 50000, // 最大输出字符数
maxCharsCap: 50000, // maxChars 参数的硬性上限
maxResponseBytes: 2000000, // 截断前的最大下载大小（字节）
timeoutSeconds: 30,
cacheTtlMinutes: 15,
maxRedirects: 3,
useTrustedEnvProxy: false, // 允许信任的 HTTP(S) 环境代理解析 DNS
readability: true, // 使用 Readability 提取
userAgent: "Mozilla/5.0 ...", // 覆盖 User-Agent
ssrfPolicy: {
allowRfc2544BenchmarkRange: true, // 选择启用：可信假 IP 代理使用 198.18.0.0/15
allowIpv6UniqueLocalRange: true, // 选择启用：可信假 IP 代理使用 fc00::/7
},
},
},
},
}Firecrawl 备用方案
如果 Readability 提取失败，web_fetch 可以回退到 Firecrawl 以进行反爬和更好的提取：
json5
{
tools: {
web: {
fetch: {
provider: "firecrawl", // 可选；省略则自动从可用凭证检测
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webFetch: {
apiKey: "fc-...", // 若已设置 FIRECRAWL_API_KEY 可省略
baseUrl: "https://api.firecrawl.dev",
onlyMainContent: true,
maxAgeMs: 86400000, // 缓存时长（1 天）
timeoutSeconds: 60,
},
},
},
},
},
}plugins.entries.firecrawl.config.webFetch.apiKey支持 SecretRef 对象。- 旧版
tools.web.fetch.firecrawl.*配置会自动迁移（openclaw doctor --fix）。
注意：若 Firecrawl 已启用且其 SecretRef 未解析、也无
FIRECRAWL_API_KEY环境变量回退，网关启动时会直接失败。
注意：Firecrawl
baseUrl覆盖有安全限制：托管流量只能使用https://api.firecrawl.dev；自托管覆盖必须指向私有或内部端点，且仅对私有目标接受http://。
当前运行时行为：
tools.web.fetch.provider显式选择抓取回退提供商。- 如果省略
provider，OpenClaw 自动从可用凭证中检测第一个就绪的 web-fetch 提供商。非沙箱的web_fetch可使用声明了contracts.webFetchProviders并在运行时注册匹配提供商的已安装插件。目前内置的提供商是 Firecrawl。 - 沙箱化的
web_fetch调用仅限于内置提供商。 - 如果禁用了 Readability（
readability: false），web_fetch直接跳到所选提供商回退。如果没有可用的提供商，则失败关闭。
信任环境代理
如果您的部署要求 web_fetch 通过一个受信任的出站 HTTP(S) 代理，设置 tools.web.fetch.useTrustedEnvProxy: true。
在此模式下，OpenClaw 在发送请求前仍会进行基于主机名的 SSRF 检查，但会由代理解析 DNS 而不是执行本地 DNS Pinning。仅当代理由操作者控制并在 DNS 解析后仍强制执行出站策略时，才启用此选项。
注意：如果未配置 HTTP(S) 代理环境变量，或目标主机被
NO_PROXY排除，web_fetch会回退到正常的严格路径（本地 DNS Pinning）。
限制与安全
maxChars被钳制到tools.web.fetch.maxCharsCap。- 响应正文在解析前被限制为
maxResponseBytes；超大响应被截断并附带警告。 - 私有/内部主机名被阻止。
tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange和tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange是面向可信假 IP 代理栈的窄范围选择启用；除非您的代理拥有这些合成范围并强制执行自身目标策略，否则保持未设置。- 重定向受
maxRedirects检查和限制。 useTrustedEnvProxy是显式选择启用，仅应在操作者控制的代理（DNS 解析后仍强制执行出站策略）上开启。web_fetch是尽力而为的——某些站点需要改用 Web Browser。
工具配置文件
如果您使用工具配置文件或白名单，添加 web_fetch 或 group:web：
json5
{
tools: {
allow: ["web_fetch"],
// 或：allow: ["group:web"]（包含 web_fetch、web_search 和 x_search）
},
}相关链接
- Web Search —— 多提供商网页搜索
- Web Browser —— 完整浏览器自动化（支持 JS 密集型站点）
- Firecrawl —— Firecrawl 搜索和爬取工具
常见问题
web_fetch 怎么配置 Firecrawl 备用？
在 plugins.entries.firecrawl 中启用 Firecrawl 插件，并在 config.webFetch 下设置 apiKey（支持 SecretRef）和 baseUrl。然后在 tools.web.fetch 中设置 provider: "firecrawl" 或省略以自动检测。若 Readability 提取失败，自动回退到 Firecrawl。
web_fetch 不支持 JavaScript，怎么办？
对于需要 JS 渲染的页面（如单页应用、登录后内容），web_fetch 无法工作。请改用 Web Browser 工具，它使用无头浏览器执行完整页面渲染。
web_fetch 缓存时间怎么调整？
在 tools.web.fetch 中设置 cacheTtlMinutes 值（默认 15 分钟）。Firecrawl 缓存单独由 plugins.entries.firecrawl.config.webFetch.maxAgeMs 控制（默认 86400000 毫秒，即 1 天）。注意 maxChars 会被 maxCharsCap 钳制，maxResponseBytes 限制响应体大小。