diff --git a/docs/zh-CN/tools/web-fetch.md b/docs/zh-CN/tools/web-fetch.md
index 37aaf5135..a93de39db 100644
--- a/docs/zh-CN/tools/web-fetch.md
+++ b/docs/zh-CN/tools/web-fetch.md
@@ -1,30 +1,28 @@
---
read_when:
- 你想获取一个 URL 并提取可读内容
- - 你需要配置 web_fetch 或其 Firecrawl 后备方案
+ - 你需要配置 web_fetch 或其 Firecrawl 回退方案
- 你想了解 web_fetch 的限制和缓存
sidebarTitle: Web Fetch
summary: web_fetch 工具 -- HTTP 获取并提取可读内容
-title: 网页抓取
+title: 网页获取
x-i18n:
- generated_at: "2026-05-02T05:39:01Z"
+ generated_at: "2026-05-03T21:39:58Z"
model: gpt-5.5
provider: openai
- source_hash: f455da77c20049f0ed0246fa53e9f49d3cf2004e65bd64a0bf871861c6e93229
+ source_hash: c8c3efbf4a640b2fd69cc9532dcb06a873a6830a2e8a85ab7510ab38207c8670
source_path: tools/web-fetch.md
workflow: 16
---
-`web_fetch` 工具会执行普通的 HTTP GET,并提取可读内容
-(HTML 转为 markdown 或文本)。它**不会**执行 JavaScript。
+`web_fetch` 工具会执行普通的 HTTP GET,并提取可读内容(将 HTML 转为 Markdown 或文本)。它**不会**执行 JavaScript。
-对于 JS 密集型站点或受登录保护的页面,请改用
+对于重度依赖 JS 的站点或受登录保护的页面,请改用
[Web 浏览器](/zh-CN/tools/browser)。
## 快速开始
-`web_fetch` **默认启用** -- 无需配置。智能体可以
-立即调用它:
+`web_fetch` **默认启用**,无需配置。智能体可以立即调用它:
```javascript
await web_fetch({ url: "https://example.com/article" });
@@ -33,7 +31,7 @@ await web_fetch({ url: "https://example.com/article" });
## 工具参数
-要抓取的 URL。仅限 `http(s)`。
+要获取的 URL。仅支持 `http(s)`。
@@ -41,26 +39,23 @@ await web_fetch({ url: "https://example.com/article" });
-将输出截断为这么多个字符。
+将输出截断为指定字符数。
## 工作原理
-
- 使用类似 Chrome 的 User-Agent 和 `Accept-Language`
- 标头发送 HTTP GET。阻止私有/内部主机名,并重新检查重定向。
+
+ 使用类似 Chrome 的 User-Agent 和 `Accept-Language` 标头发送 HTTP GET。阻止私有/内部主机名,并重新检查重定向。
-
+
在 HTML 响应上运行 Readability(主内容提取)。
-
- 如果 Readability 失败且已配置 Firecrawl,则通过
- Firecrawl API 以规避机器人检测模式重试。
+
+ 如果 Readability 失败且已配置 Firecrawl,则通过带机器人规避模式的 Firecrawl API 重试。
-
- 结果会缓存 15 分钟(可配置),以减少对同一 URL 的重复
- 抓取。
+
+ 结果会缓存 15 分钟(可配置),以减少对同一 URL 的重复获取。
@@ -79,6 +74,7 @@ await web_fetch({ url: "https://example.com/article" });
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
ssrfPolicy: {
@@ -94,7 +90,7 @@ await web_fetch({ url: "https://example.com/article" });
## Firecrawl 回退
如果 Readability 提取失败,`web_fetch` 可以回退到
-[Firecrawl](/zh-CN/tools/firecrawl),用于规避机器人检测并获得更好的提取效果:
+[Firecrawl](/zh-CN/tools/firecrawl),用于机器人规避和更好的提取:
```json5
{
@@ -124,42 +120,42 @@ await web_fetch({ url: "https://example.com/article" });
}
```
-`plugins.entries.firecrawl.config.webFetch.apiKey` 支持 SecretRef 对象。
-旧版 `tools.web.fetch.firecrawl.*` 配置会由 `openclaw doctor --fix` 自动迁移。
+`plugins.entries.firecrawl.config.webFetch.apiKey` 支持 SecretRef 对象。旧版 `tools.web.fetch.firecrawl.*` 配置会由 `openclaw doctor --fix` 自动迁移。
- 如果 Firecrawl 已启用,但其 SecretRef 未解析且没有
- `FIRECRAWL_API_KEY` 环境变量回退,Gateway 网关启动会快速失败。
+ 如果 Firecrawl 已启用,并且其 SecretRef 未解析且没有 `FIRECRAWL_API_KEY` 环境变量回退,Gateway 网关启动会快速失败。
- Firecrawl `baseUrl` 覆盖会被锁定:托管流量使用
- `https://api.firecrawl.dev`;自托管覆盖必须指向私有或
- 内部端点,并且仅这些私有目标接受 `http://`。
+ Firecrawl `baseUrl` 覆盖会被锁定:托管流量使用 `https://api.firecrawl.dev`;自托管覆盖必须指向私有或内部端点,并且 `http://` 仅对这些私有目标可接受。
当前运行时行为:
-- `tools.web.fetch.provider` 会显式选择抓取回退提供商。
-- 如果省略 `provider`,OpenClaw 会根据可用凭据自动检测第一个就绪的 web-fetch
- 提供商。非沙箱隔离的 `web_fetch` 可以使用已安装的插件,这些插件声明
- `contracts.webFetchProviders` 并在运行时注册匹配的提供商。当前内置提供商是 Firecrawl。
+- `tools.web.fetch.provider` 会显式选择获取回退提供商。
+- 如果省略 `provider`,OpenClaw 会从可用凭证中自动检测第一个就绪的 Web 获取提供商。非沙箱隔离的 `web_fetch` 可以使用已安装的插件,这些插件声明 `contracts.webFetchProviders` 并在运行时注册匹配的提供商。目前内置提供商是 Firecrawl。
- 沙箱隔离的 `web_fetch` 调用仍仅限于内置提供商。
-- 如果禁用 Readability,`web_fetch` 会直接跳到选定的
- 提供商回退。如果没有可用提供商,它会以关闭方式失败。
+- 如果禁用 Readability,`web_fetch` 会直接跳到选定的提供商回退。如果没有可用提供商,它会以封闭方式失败。
-## 限制和安全
+## 可信环境代理
+
+如果你的部署要求 `web_fetch` 通过可信的出站 HTTP(S) 代理,请设置 `tools.web.fetch.useTrustedEnvProxy: true`。
+
+在此模式下,OpenClaw 仍会在发送请求前应用基于主机名的 SSRF 检查,但会让代理解析 DNS,而不是执行本地 DNS 固定。仅当该代理由操作方控制,并在 DNS 解析后强制执行出站策略时,才启用此选项。
+
+
+ 如果未配置 HTTP(S) 代理环境变量,或目标主机被 `NO_PROXY` 排除,`web_fetch` 会回退到带本地 DNS 固定的普通严格路径。
+
+
+## 限制与安全
- `maxChars` 会被限制到 `tools.web.fetch.maxCharsCap`
-- 响应正文在解析前会被限制在 `maxResponseBytes`;超大
- 响应会被截断并附带警告
+- 响应体在解析前会被限制为 `maxResponseBytes`;超大响应会被截断并附带警告
- 私有/内部主机名会被阻止
-- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` 和
- `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是针对
- 受信任假 IP 代理栈的窄范围选择启用项;除非你的代理拥有
- 这些合成地址范围并执行自己的目标策略,否则请保持未设置
+- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` 和 `tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是面向可信假 IP 代理栈的窄范围选择加入项;除非你的代理拥有这些合成范围并强制执行自己的目标策略,否则请保持未设置
- 重定向会被检查,并受 `maxRedirects` 限制
-- `web_fetch` 是尽力而为的工具 -- 某些站点需要 [Web 浏览器](/zh-CN/tools/browser)
+- `useTrustedEnvProxy` 是显式选择加入项,只应为由操作方控制、且在 DNS 解析后仍会强制执行出站策略的代理启用
+- `web_fetch` 是尽力而为的工具,有些站点需要使用 [Web 浏览器](/zh-CN/tools/browser)
## 工具配置文件
@@ -176,6 +172,6 @@ await web_fetch({ url: "https://example.com/article" });
## 相关内容
-- [Web 搜索](/zh-CN/tools/web) -- 使用多个提供商搜索 Web
-- [Web 浏览器](/zh-CN/tools/browser) -- 用于 JS 密集型站点的完整浏览器自动化
+- [Web 搜索](/zh-CN/tools/web) -- 使用多个提供商搜索网页
+- [Web 浏览器](/zh-CN/tools/browser) -- 面向重度依赖 JS 站点的完整浏览器自动化
- [Firecrawl](/zh-CN/tools/firecrawl) -- Firecrawl 搜索和抓取工具