Claude Code 第三方 API 环境下 WebFetch 失效的完整解决方案

问题描述

在使用 Claude Code 的过程中，如果你通过第三方 API（如阿里云 DashScope、DeepSeek、智谱 GLM 等国内大模型平台）接入而非 Anthropic 官方 API，你很可能会遇到以下两种 WebFetch 故障之一：

故障一：安全预检失败

Fetch(https://huggingface.co/microsoft/VibeVoice-Realtime-0.5B)
  Error: Unable to verify if domain xxx is safe to fetch. 
  This may be due to network restrictions or enterprise security policies blocking claude.ai.

故障二：抓取成功但不返回结果

Fetch(https://example.com/article)
  Received 53.3KB (200 OK)

Bash(curl -s "https://example.com/article" -H "User-Agent: ...")
  ...（Claude Code 默默回退到 curl 获取原始 HTML）

Claude Code 会自行降级到 curl + grep 的方式提取网页文本，虽然勉强能用，但丧失了对网页内容的结构化理解和摘要能力。

根因分析：WebFetch 的三步工作流

很多人在排查时直接跳到"怎么修"，但搞清楚 WebFetch 的内部机制才能避免盲修。根据官方文档和相关社区的逆向分析，WebFetch 并非简单的"发个 HTTP 请求 → 返回内容"，而是分为三步：

第一步：安全预检（Preflight Check）

Claude Code 在访问目标网址前，会先向 Anthropic 的安全服务器发起查询，确认目标域名是否安全。这一步走的是 Anthropic 自家的域名，在"不稳定的网络环境 + 第三方 API 中转"的双重条件下，几乎不可能正常连接。

第二步：内容抓取

预检通过后，Claude Code 通过后端 API 服务去目标 URL 拉取页面内容。这一步的稳定性取决于你的 API 后端的网络出口。

第三步：摘要处理

这是最关键也最容易被忽略的一步。抓回来的网页内容（可能是几十 KB 甚至几百 KB）不会直接塞给主模型——那样 Token 消耗太大了。Claude Code 内部会调用一个独立的小模型对内容做摘要或预处理，再将精简后的结果交给主模型分析。

这个小模型由独立的环境变量控制：

• 旧版变量名：ANTHROPIC_SMALL_FAST_MODEL
• 新版变量名：ANTHROPIC_DEFAULT_HAIKU_MODEL（ANTHROPIC_SMALL_FAST_MODEL 已标记为 deprecated，但实测仍可用）

Claude Code 内部硬编码的默认值是 claude-haiku-4-5-20251001，显然，你的第三方 API 后端不认识这个模型名，于是返回 model not supported，整个 WebFetch 流程就此中断。

总结：故障一对应第一步失败，故障二对应第三步失败。两个环节都跟第三方 API 环境不兼容有关，但修复的关键配置项不同。

解决方案

方案一：手动修改配置文件（最直接）

编辑 ~/.claude/settings.json（Windows 下为 %USERPROFILE%\.claude\settings.json），添加以下配置：

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "your-api-key",
        "ANTHROPIC_BASE_URL": "https://your-provider-base-url",
        "ANTHROPIC_MODEL": "qwen3.5-plus",
        "ANTHROPIC_SMALL_FAST_MODEL": "glm-4.7"
    },
    "skipWebFetchPreflight": true
}

关键配置项说明：

关于小模型选型：

模型名的选择取决于你使用的 API 后端支持什么。以下是一些常见的可用模型：

• 阿里云 DashScope Coding Plan：qwen3.5-plus、glm-4.7、kimi-k2.5、glm-5、MiniMax-M2.5、qwen3-coder-plus
• 字节方舟 Coding Plan：Doubao 系列、GLM 系列、DeepSeek 系列
• 其他兼容 OpenAI 格式的后端：取决于具体平台

需要注意，摘要速度与所选模型有关——用 glm-4.7 这类较大模型做摘要会比原生的 haiku 模型慢一些，但功能上是正常的。

方案二：使用 claude-code-proxy（服务端代理）

claude-code-proxy（2.7k Stars）是一个将 Claude API 请求转换为 OpenAI 格式请求的本地代理服务。它的优势在于在服务端统一处理模型映射，不需要在每台客户端的 Claude Code 里分别配置小模型参数。

工作原理：

Claude Code  →  claude-code-proxy  →  OpenAI-compatible API Provider
    (将 Claude 格式的 /v1/messages 请求转换为 OpenAI 格式)

核心配置（.env 文件）：

OPENAI_API_KEY="sk-your-openai-api-key"
OPENAI_BASE_URL="https://api.openai.com/v1"
BIG_MODEL="gpt-4o"          # 对应 Claude Opus 级别请求
MIDDLE_MODEL="gpt-4o"       # 对应 Claude Sonnet 级别请求（默认回退到 BIG_MODEL）
SMALL_MODEL="gpt-4o-mini"   # 对应 Claude Haiku 级别请求（包括 WebFetch 摘要）

当 Claude Code 发出 WebFetch 请求时，内部调用的小模型（haiku 级别）会被 proxy 自动路由到 SMALL_MODEL。这样就不需要在客户端的 settings.json 里额外配置 ANTHROPIC_SMALL_FAST_MODEL。

启动方式：

# 安装依赖
uv sync

# 启动 proxy（默认监听 0.0.0.0:8082）
python start_proxy.py

# 使用 Claude Code
ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY="any-value" claude

注意：如果你使用了 claude-code-proxy，客户端的 ANTHROPIC_BASE_URL 应该指向 proxy 地址（如 http://localhost:8082），而不是直接指向 OpenAI 或其他后端。安全预检的跳过（skipWebFetchPreflight）仍然需要在客户端的 settings.json 中配置。

方案三：使用 CC Switch（GUI 桌面工具，推荐新手）

CC Switch（49K Stars，GitHub Trending 第一）是一个基于 Tauri 2 构建的桌面工具，用图形界面管理所有 AI CLI 工具的 API Provider。如果你不想手动编辑 JSON 配置文件，这是门槛最低的方案。

CC Switch 的核心能力：

对于 WebFetch 问题的意义：

CC Switch 本质上帮你管理了 settings.json 中的所有配置项——包括 skipWebFetchPreflight、模型映射（BIG/MIDDLE/SMALL）以及 API Base URL。当你通过 CC Switch 添加一个 Provider 时，它会自动将对应的模型映射写入配置文件。你只需要确认小模型（Haiku 级别）的映射指向了一个实际可用的模型即可。

安装与使用：

# macOS（推荐 Homebrew）
brew tap farion1231/ccswitch
brew install --cask cc-switch

# Windows：下载 .msi 安装包
# Linux：下载 .deb / .rpm / .AppImage

下载地址：GitHub Releases

快速配置流程：

1. 启动 CC Switch，选择要管理的应用（Claude Code）
2. 点击 "+" 添加 Provider，从内置 50+ 预设中选择或手动填写 API Key、Base URL、模型名
3. 确保 Haiku/Small 模型映射到一个可用的模型
4. 点击"启用"，CC Switch 自动写入配置，Claude Code 无需重启即可生效

三方案对比

常见问题

Q1：配置了小模型后 WebFetch 仍然失败？

首先确认小模型名在你的 API 后端上是真实可用的。可以先用普通的聊天请求测试该模型是否正常响应。其次检查 ANTHROPIC_BASE_URL 是否正确——它应该指向你后端的 Anthropic 兼容接口，而非 OpenAI 接口。

Q2：跳过安全预检有什么风险？

Claude Code 的 agent 可能访问到恶意链接。如果你 fetch 的 URL 都是你在 prompt 中明确指定的（而非让 agent 自主发现的），这个风险是可控的。如果你的 agent 运行在自动化 pipeline 里且 fetch URL 来源不可控，建议在 settings.json 中同时使用 allowed_domains 做域名白名单。

Q3：WebSearch 也失效了怎么办？

WebSearch 与 WebFetch 是独立的工具，但故障原因类似——WebSearch 同样依赖小模型处理搜索结果摘要。修复方法与 WebFetch 一致：配置 ANTHROPIC_SMALL_FAST_MODEL。另外需要注意，某些第三方 API 后端（如阿里云 Coding Plan）的 WebSearch 功能可能仅支持自家模型（如 qwen 系列），用第三方模型调用会失败。

Q4：ANTHROPIC_SMALL_FAST_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 有什么区别？

前者是旧版环境变量名，在官方文档中已标记为 deprecated；后者是新版名称。在 Claude Code 2026 年 5 月之后的版本中，两者实测均可用。推荐两个都配置，设置为相同值，不会有副作用。

Q5：用了 claude-code-proxy 还需要客户端配置吗？

skipWebFetchPreflight: true 仍然需要客户端配置——因为安全预检是 Claude Code 客户端直接发起的，不经过 proxy。模型映射（SMALL_MODEL）在 proxy 服务端配置即可，客户端不需要再设 ANTHROPIC_SMALL_FAST_MODEL。

完整配置参考

纯手动配置（适用于阿里云 DashScope Coding Plan）

{
    "env": {
        "ANTHROPIC_AUTH_TOKEN": "your-dashscope-api-key",
        "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
        "ANTHROPIC_MODEL": "qwen3.5-plus",
        "ANTHROPIC_SMALL_FAST_MODEL": "glm-4.7",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7"
    },
    "skipWebFetchPreflight": true
}

配合 claude-code-proxy 使用

proxy 端 .env：

OPENAI_API_KEY="sk-your-key"
OPENAI_BASE_URL="https://api.openai.com/v1"
BIG_MODEL="gpt-4o"
SMALL_MODEL="gpt-4o-mini"

Claude Code 端 ~/.claude/settings.json：

{
    "env": {
        "ANTHROPIC_BASE_URL": "http://localhost:8082",
        "ANTHROPIC_AUTH_TOKEN": "any-value"
    },
    "skipWebFetchPreflight": true
}

参考来源

• Claude Code Web Fetch 排障与解决 - kozumi（博客园）
• claude code 第三方 API 使用 WebFetch 的问题 - vito wang（知乎）
• Claude Code 设置 - 官方文档
• Web Fetch Tool - Claude Platform Docs
• claude-code-proxy（GitHub）
• CC Switch（GitHub）