web_fetch 是干什么的

web_search 给你一堆链接和摘要；web_fetch 把其中某个 URL 真正拉下来，提取成 Markdown / 文本。它是轻量级抓取，不依赖浏览器自动化，适合：

  • 读一篇具体文章的全文
  • 抓 API 返回的 JSON（带 extractMode: text）
  • 取某个文档页的结构化内容做参考

它和 browser 工具的区别：web_fetch 不执行 JS、不保持登录态，适合静态/半静态页面；要登录后抓取或用 JS 渲染的页面，才上 browser。

核心参数

| 参数 | 说明 |

|------|------|

| url | 目标 HTTP(S) 地址，必填 |

| extractMode | markdown（默认，提取正文为 MD）或 text（原始纯文本） |

| maxChars | 返回最大字符数，超长截断，避免灌爆上下文 |

示例：

web_fetch({
  url: "https://docs.openclaw.ai/gateway/configuration",
  extractMode: "markdown",
  maxChars: 8000
})

实战一：读官方文档

文档站大多是静态渲染，web_fetch 直接出干净的 Markdown，比浏览器截图再识别快得多。配合 maxChars 控制长度——先看前 8000 字定位章节，需要再二次抓取更深的锚点。

实战二：抓 API JSON

有些接口返回纯 JSON，用 extractMode: "text" 直接拿原始串：

web_fetch({
  url: "https://api.example.com/v1/status",
  extractMode: "text",
  maxChars: 2000
})

注意：如果目标需要鉴权头，web_fetch 不支持自定义 header，这种得上 browser 或 exec + curl。

实战三：大页截断处理

长文档（如规范、手册）一次抓不完。策略：

  1. 先 maxChars: 4000 看目录/结构。
  1. 找到目标章节的锚点 URL（如 #section-3），直接抓那个锚点（若服务端支持）。
  1. 或分段：先抓头部，再抓尾部 maxChars 配合不同起点——但 web_fetch 本身不支持 offset，需用 browser 的 text 选择器做定点提取。

关键行为（必须知道）

  1. 不执行 JavaScript：SPA（React/Vue 纯前端渲染）页面可能只抓到空壳。遇到内容缺失，换 browser。
  1. 登录态无效：带 cookie 的私有页面抓不到，需 browser 用已登录 profile。
  1. 截断是静默的：maxChars 超了直接砍尾，不会提示"还有更多"，需要自己判断内容是否完整。
  1. 部分站点会封自动化 UA：返回 403 时，先确认是不是目标站反爬，必要时走 browser 模拟真实访问。

标准工作流

  1. web_search 找到候选 URL → 挑最相关的 1~3 个。
  1. web_fetch 拉正文，extractMode: markdown，maxChars 先小后大。
  1. 内容不全 → 锚点二次抓取，或升级到 browser。
  1. 引用时标注来源：文章/文档类输出应带 Source: <url> 方便核对。

踩坑与反模式

  • ❌ 拿 web_fetch 抓需要登录的后台：必然空。私有内容用 browser + 已登录 profile。
  • ❌ 一次 maxChars 拉满：长页灌爆上下文，先小后大更高效。
  • ❌ SPA 页面抓到空壳就以为没内容：换 browser 渲染再看。
  • ✅ 静态文档/API 首选 web_fetch：快、省、干净。

和 web_search 的分工

  • web_search：广撒网，定位"哪个 URL 可能有答案"。
  • web_fetch：深读取，把那个 URL 变成可用文本。

一句话总结

web_fetch 是联网的"精读器"：静态页和 API 用它最快最干净，登录态/SPA 才上 browser。配合 maxChars 先小后大，既省 token 又不漏内容。

扫码关注公众号，获取更多 OpenClaw 实操技巧：

公众号二维码