Claude Code WebFetch 调用失败解决方案

背景

在使用 Anthropic 的 Claude Code 进行开发辅助时，开发者常依赖其内置的 WebFetch 功能来实时获取网页内容，以增强模型对最新信息或特定文档的理解能力。然而，部分用户（尤其是处于特定网络环境或企业内网中的用户）在调用该功能时，频繁遭遇 Unable to verify if domain xxx is safe to fetch 的错误提示。

这一问题的棘手之处在于，它并非由目标抓取网站（如 Wikipedia、Hacker News 等）本身不可访问引起，甚至在使用全局代理或配置 Clash TUN 模式后依然无法解决。这导致开发者在需要实时检索信息时陷入困境，且由于官方文档未明确提及此限制，排查难度较大。

核心内容

该问题的根本原因源于 Claude Code 在发起实际网页抓取请求前的安全验证机制。

1. 预检查机制（Preflight Check）： WebFetch 功能在抓取目标 URL 之前，会首先向 Anthropic 的服务器发起一个预检查请求。具体而言，它会调用 https://claude.ai/api/web/domain_info?domain=<target_domain> 接口，以验证目标域名的安全性。

2. 失败根源： 如果用户的网络环境存在以下情况，预检查请求将无法成功：

   • claude.ai 域名被网络防火墙拦截或屏蔽。
   • 企业安全策略阻止了对 claude.ai 的出站连接。
   • 代理配置未正确路由 claude.ai 的相关请求。

   即使目标抓取网站本身是可达的，只要上述预检查步骤失败，WebFetch 就会直接报错并终止后续操作。

3. 解决方案： 在 GitHub Issue #6388 中确认，Claude Code 提供了一个隐藏的配置项 skipWebFetchPreflight，用于跳过这一预检查步骤。虽然该配置未写入官方公开文档，但通过修改本地配置文件即可生效。

   具体操作步骤如下：

   • 编辑用户目录下的配置文件：~/.claude/settings.json。
   • 在 JSON 对象中添加配置项："skipWebFetchPreflight": true。
   • 重启 Claude Code 以应用更改。

   配置生效后，WebFetch 将不再执行对 claude.ai 的域名安全验证，直接进行网页抓取，从而绕过网络限制问题。

关键要点

• 错误表象与实质：报错信息提示域名安全性验证失败，实质是预检查请求（Preflight）被网络策略阻断，而非目标网站不可访问。
• 代理配置的局限性：仅配置全局代理或 Clash TUN 模式不足以解决问题，关键在于代理是否能正确处理 claude.ai 域名的请求。若 claude.ai 本身不可达，预检查必败。
• 隐藏配置项：skipWebFetchPreflight 是一个未公开文档化的配置项，专门用于绕过预检查机制。
• 生效方式：修改 ~/.claude/settings.json 后必须重启 Claude Code 进程，配置才会生效。
• 验证方法：重启后，尝试让 Claude Code 抓取如 https://news.ycombinator.com 等网站，若能正常返回内容，则表明问题已解决。

意义与影响

这一发现对于在受限网络环境（如国内网络、企业内网）中使用 Claude Code 的开发者具有重要意义。

1. 提升可用性：通过绕过不必要的预检查步骤，开发者可以在无法直接访问 claude.ai 基础设施的情况下，依然利用 Claude Code 的 WebFetch 功能获取外部信息，极大地提升了工具在特定场景下的可用性。
2. 降低排查成本：明确了问题的根源在于预检查而非目标网站，避免了开发者在代理配置、DNS 解析等外围环节进行无谓的调试。
3. 文档与功能的差距：该配置项未纳入官方文档，反映了开源项目或快速迭代产品中常见的“文档滞后”现象。这也提醒用户，在遇到文档未覆盖的复杂问题时，查阅 GitHub Issues 和源码配置可能是更有效的解决途径。
4. 安全权衡：跳过预检查意味着用户需自行承担抓取目标网站的安全风险。虽然 WebFetch 本身旨在辅助开发，但用户应确保抓取来源的可信度，避免引入恶意内容。