Claude Code WebFetch 報錯完整排查: 4 步解決 Unable to verify if domain 問題

Layer 4 · 繞開 WebFetch Bash（curl:*） 替代 · 或接入 fetch-mcp / Playwright MCP server 🎯 CI 容器 / preflight 完全不通的場景 · 徹底繞開 claude.ai preflight 15 min 終極方案

第 1 層: 代理與 NO_PROXY 環境變量

這是國內用戶最常見的第一道坎。Claude Code 遵循標準代理環境變量，按以下優先級讀取:

https_proxy > HTTPS_PROXY > http_proxy > HTTP_PROXY

macOS / Linux 最小配置:

# ~/.zshrc 或 ~/.bashrc
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY="localhost，127.0.0.1，::1，api.apiyi.com，vip.apiyi.com"

Windows PowerShell:

$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost，127.0.0.1，api.apiyi.com，vip.apiyi.com"

也可以直接寫入 ~/.claude/settings.json 的 env 塊:

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890"，
    "HTTP_PROXY": "http://127.0.0.1:7890"，
    "NO_PROXY": "localhost，127.0.0.1，api.apiyi.com，vip.apiyi.com"
  }
}

⚠️ 關鍵細節: NO_PROXY 必須把 API易 的中轉域名（api.apiyi.com / vip.apiyi.com）加進去！否則 Claude Code 的 API 調用會經過代理繞一圈，既慢又可能被代理節點劫持。我們建議 API 走 NO_PROXY 直連 API易，WebFetch 的 preflight 走代理訪問 claude.ai，兩條路徑分開走最穩。

基礎認證代理（公司代理常見）:

export HTTPS_PROXY=http://username:[email protected]:8080

注意: Claude Code 不支持 SOCKS 代理——如果你的代理只有 SOCKS 模式，用 privoxy 或 v2ray 把 SOCKS 轉成 HTTP。

第 2 層: 權限預授權 WebFetch（domain:xxx）

有時候 preflight 能跑通，但 Claude Code 仍然每次詢問"是否允許抓取此域名"。把常用域名加到 permissions.allow，Claude 就不會再問:

{
  "permissions": {
    "allow": [
      "WebFetch（domain:www.weather.com.cn）"，
      "WebFetch（domain:github.com）"，
      "WebFetch（domain:developer.mozilla.org）"，
      "WebFetch（domain:docs.python.org）"
    ]，
    "ask": [
      "WebFetch"
    ]
  }
}

完整規則語法速查:

🎯 管理建議: 在企業場景下，推薦用 managed-settings.json 把允許抓取的域名白名單化，放在 /Library/Application Support/ClaudeCode/managed-settings.json（macOS）或 /etc/claude-code/managed-settings.json（Linux），配合 allowManagedPermissionRulesOnly: true 強制所有開發者遵守。通過 API易 apiyi.com 調用 Claude API 的開發團隊也可以用同一套規則，確保 Claude Code 和後端 API 調用的權限策略統一。

第 3 層: 企業 CA 證書與 TLS 攔截

如果你的公司用了 Zscaler / CrowdStrike / Cato Networks 等 TLS 攔截式安全產品，它們會重新簽發 HTTPS 證書，導致 Claude Code 的 Node.js 運行時報 UNABLE_TO_GET_ISSUER_CERT 等 SSL 錯誤。

解決方式: 導出企業根 CA 證書後指向它:

export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem

或寫入 ~/.claude/settings.json:

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/Users/you/certs/company-root-ca.pem"，
    "CLAUDE_CODE_CERT_STORE": "bundled，system"
  }
}

CLAUDE_CODE_CERT_STORE 可選值:

mTLS 雙向認證（更嚴的企業環境）:

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

第 4 層: 繞開 WebFetch，用 Bash curl 或 MCP 替代

如果上面三層都不能解決，最可靠的辦法就是不用 WebFetch——讓 Claude 通過 Bash 工具直接 curl，或者接入第三方 fetch MCP 服務器。

方案 A: 允許 Bash 使用 curl/wget

{
  "permissions": {
    "allow": [
      "Bash（curl:*）"，
      "Bash（wget:*）"
    ]
  }
}

然後在對話中告訴 Claude:"請用 curl 獲取 www.weather.com.cn 的首頁內容"——它會跳過 WebFetch 直接走 Bash。這條路徑完全不觸發 preflight，代理配置只要讓目標站點能訪問就行。

方案 B: 接入 fetch-mcp 或 Playwright MCP

# 安裝第三方 fetch MCP server
claude mcp add fetch npx -- @modelcontextprotocol/server-fetch

MCP 工具的網絡請求由 MCP server 進程自己發起，不經過 Claude Code 的 preflight 鏈路，穩定性顯著提升。對於需要執行 JavaScript 的動態站點，用 Playwright MCP 更合適。

WebFetch 排查方案對比矩陣 ★ 越多代表越合適 · 看哪欄深色最多

評估維度

A. 代理配置 HTTPS_PROXY

B. 權限預授權 WebFetch（domain）

C. 企業 CA NODE_EXTRA_CA_CERTS

D. 繞開 WebFetch Bash curl + MCP

配置難度 ★★★★☆ ★★★★★ ★★☆☆☆ ★★★★☆

解決問題廣度 ★★★★★ ★★☆☆☆ ★★★☆☆ ★★★★★

性能影響 ★★★☆☆ ★★★★★ ★★★★☆ ★★★★☆

企業合規 ★★★☆☆ ★★★★★ ★★★★★ ★★★☆☆

國內適配 ★★★★☆ ★★★☆☆ ★★☆☆☆ ★★★★★

💡 推薦國內用戶組合: A（代理基礎） + B（常用域名） + D（fallback）

Claude Code WebFetch 的實戰排查案例

理論講完，我們看三個真實場景下的完整解決流程。

場景一: 國內 MacBook 抓取 weather.com.cn（截圖場景）

現象: fetch www.weather.com.cn 連續報 Unable to verify。

排查步驟:

# Step 1 確認代理狀態
echo $HTTPS_PROXY  # 應該輸出 http://127.0.0.1:7890 之類

# Step 2 手動驗證 claude.ai 是否可達
curl -I https://claude.ai/code/ -x http://127.0.0.1:7890
# 如果返回 403 + cf-mitigated，說明 Cloudflare 攔了，去 Step 3
# 如果返回 200，說明 preflight 能過，去檢查 permissions

# Step 3 在 Claude Code 裏切換方案——改用 Bash + curl
# 對話中直接說:
# "別用 WebFetch，用 curl 抓 http://www.weather.com.cn 的首頁"

最終配置（~/.claude/settings.json）:

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890"，
    "HTTP_PROXY": "http://127.0.0.1:7890"，
    "NO_PROXY": "localhost，127.0.0.1，api.apiyi.com，vip.apiyi.com"
  }，
  "permissions": {
    "allow": [
      "WebFetch（domain:www.weather.com.cn）"，
      "Bash（curl:*）"，
      "Bash（wget:*）"
    ]
  }
}

🎯 國內實戰提示: 國內用戶最穩的組合是「API 走 API易 apiyi.com + WebFetch 走代理 + 必要時 fallback 到 curl」。API易 的 base_url 加入 NO_PROXY 後，Claude Code 的 API 請求不會被代理繞路，延遲和穩定性與海外直連一致。

場景二: 公司機器 + Zscaler TLS 攔截

現象: WebFetch 報 SELF_SIGNED_CERT_IN_CHAIN 或 UNABLE_TO_VERIFY_LEAF_SIGNATURE。

解決:

# Step 1 從 IT 獲取公司根 CA 證書（通常是 .pem 或 .crt）
# Step 2 配置 Claude Code 信任這個 CA
export NODE_EXTRA_CA_CERTS=~/certs/company-zscaler-root.pem

# Step 3 同時信任系統證書庫（Zscaler 通常已注入）
export CLAUDE_CODE_CERT_STORE=bundled，system

# Step 4 重啓 Claude Code

場景三: Docker / CI 容器內 headless 運行

現象: 本地能跑，CI 裏 WebFetch 100% 失敗。

原因: 容器裏既沒代理也沒瀏覽器，Cloudflare 的 bot 防護直接識別出 CLI 客戶端拒絕連接。

解決: 在 CI 裏禁用 WebFetch、強制走 Bash:

# .github/workflows/claude.yml 或類似
env:
  CLAUDE_CODE_DISABLE_WEBFETCH: "true"  # 如果此環境變量生效

或通過 --disallowedTools 啓動參數:

claude --disallowedTools WebFetch --allowedTools "Bash（curl:*）"

🎯 CI 集成建議: 容器化環境裏，把 API Key 指向 API易 apiyi.com 的穩定中轉節點，避免因海外網絡抖動導致 CI 失敗。我們建議在 GitHub Actions / GitLab CI 的 secrets 裏配置 ANTHROPIC_BASE_URL=https://vip.apiyi.com + ANTHROPIC_API_KEY=sk-xxx，配合 WebFetch 禁用策略，CI 的 Claude Code 任務穩定性可以做到 99% 以上。

Claude Code WebFetch 報錯的工程最佳實踐

跑通單次 demo 容易，要讓團隊裏每個人都穩定使用 Claude Code，還有幾個關鍵點。

實踐一: 統一的 managed-settings.json

給團隊下發統一的 managed-settings.json，避免每個人自己折騰:

{
  "env": {
    "HTTPS_PROXY": "http://corp-proxy:8080"，
    "NODE_EXTRA_CA_CERTS": "/opt/company/ca.pem"，
    "NO_PROXY": "*.corp.example.com，api.apiyi.com，vip.apiyi.com"
  }，
  "permissions": {
    "allow": [
      "WebFetch（domain:*.corp.example.com）"，
      "WebFetch（domain:github.com）"，
      "WebFetch（domain:stackoverflow.com）"，
      "Bash（curl:*）"
    ]，
    "deny": [
      "WebFetch（domain:*）"
    ]
  }，
  "allowManagedPermissionRulesOnly": true
}

文件放置路徑:

實踐二: 三級 fallback 策略

在 CLAUDE.md 裏寫清楚工具選用優先級，讓 Claude 按順序嘗試:

## 網絡抓取工具優先級

1. 首選 WebFetch （已預授權的域名）
2. WebFetch 失敗時， fallback 到 Bash curl
3. 動態站點用 Playwright MCP
4. 永遠不要用 `curl -k` 忽略證書錯誤

這段話進 CLAUDE.md 後，Claude 會在遇到 WebFetch 報錯時自動切換 curl，用戶體驗明顯改善。

實踐三: preflight 健康檢查腳本

寫一個快速診斷腳本，排查時先跑一遍:

#！/bin/bash
# claude-code-doctor.sh

echo "=== 環境變量 ==="
env | grep -iE "proxy|claude_code|node_extra"

echo "=== claude.ai preflight 測試 ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://claude.ai/code/

echo "=== api.anthropic.com 測試 ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://api.anthropic.com/

echo "=== APIYI 中轉測試 ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://vip.apiyi.com/

echo "=== DNS 解析 ==="
nslookup claude.ai

如果 claude.ai/code/ 返回 403 且帶 cf-mitigated 響應頭，就是典型的 Cloudflare preflight 問題——直接上第 4 層方案。

🎯 診斷建議: 當 Claude Code 出現異常時，80% 的問題能通過這套診斷腳本定位。國內用戶建議把 vip.apiyi.com 作爲 API 轉發節點加入檢查清單——如果 APIYI 可達但 Anthropic 官方站點不可達，就走 API易 apiyi.com 的中轉繼續工作，避免被網絡問題堵死全天開發節奏。

Claude Code WebFetch 報錯常見問題 FAQ

Q1: 爲什麼錯誤信息說 "enterprise security policies blocking claude.ai"，但我公司沒裝任何安全軟件？

這是 Anthropic 官方消息設計不準確。真正攔截的是 claude.ai 前的 Cloudflare bot 防護，Cloudflare 把 CLI 進程識別爲 bot 返回 JS Challenge，CLI 無法完成挑戰就報這個錯。跟你公司的 IT 策略通常無關。

Q2: APIYI 的中轉能解決 WebFetch 報錯嗎？

部分能。API易 apiyi.com 只負責轉發 api.anthropic.com 的 API 請求，Claude Code 的模型對話、工具調用決策都能穩定工作。但 WebFetch 的 preflight 打的是 claude.ai（不是 api.anthropic.com），這條路徑 APIYI 不覆蓋——需要通過本地代理解決。建議組合使用:API 走 API易直連，preflight 走代理，兩套路徑互不干擾。

Q3: 有 skipWebFetchPreflight 這個配置項嗎？

社區有討論，但截至 2026 年 4 月官方未正式文檔化。GitHub issue #39896 裏提到這是一個社區期待的功能，用於跳過 preflight 校驗。在正式支持前，推薦用第 4 層方案（Bash curl + 權限預授權域名）繞開這個問題，效果等同且更可控。

Q4: 我開了 Clash 全局代理，爲什麼 WebFetch 還是報錯？

Clash 的全局代理模式不會自動設置環境變量。Claude Code 是個 Node.js CLI 進程，它只讀 HTTPS_PROXY 這些環境變量，不會嗅探系統代理設置。你需要在 shell profile 裏顯式 export 代理變量，或者寫進 ~/.claude/settings.json 的 env 塊。

Q5: WebFetch 成功了但結果不完整，只有一半內容？

這是 Claude Code 的 max_content_tokens 限制。在權限規則裏無法調整，但如果你通過 Claude API 直接調用 web_fetch 工具（非 Claude Code CLI），可以設置 "max_content_tokens": 100000 來加大單頁抓取量。這種場景下推薦通過 API易 apiyi.com 直連 API，靈活度更高。

Q6: 報錯能否通過禁用 WebFetch 徹底避免？

可以。啓動時加參數:

claude --disallowedTools WebFetch

或 settings.json 裏:

{
  "permissions": {
    "deny": ["WebFetch"]
  }
}

配合允許 Bash（curl:*），Claude 會自動改用 curl，對國內用戶體驗反而更好。

Q7: GitHub Actions / GitLab CI 裏用 Claude Code，怎麼配？

CI 容器裏 100% 推薦禁用 WebFetch——容器無瀏覽器環境，preflight 幾乎必掛。同時把 API 請求指向 API易 apiyi.com 的穩定節點:

env:
  ANTHROPIC_BASE_URL: https://vip.apiyi.com
  ANTHROPIC_API_KEY: ${{ secrets.APIYI_KEY }}
  CLAUDE_CODE_DISALLOWED_TOOLS: "WebFetch"

Claude Code WebFetch 報錯總結與行動清單

回顧全文，Claude Code WebFetch 報錯 的本質是 Cloudflare preflight + CLI 無瀏覽器的設計限制，不是你的網絡或 IT 策略問題。一句話總結:

✅ 國內用戶三板斧: API 走 API易 apiyi.com 直連 + 本地代理走 claude.ai preflight + Bash curl 作爲 fallback，90% 的 WebFetch 報錯都能繞開。

落地行動清單

按優先級執行以下 5 步:

1. 配置代理: 設 HTTPS_PROXY + HTTP_PROXY，並把 API易域名加入 NO_PROXY
2. 預授權域名: 把常抓的站點寫進 permissions.allow 的 WebFetch（domain:...）
3. 處理企業 CA: 如果在 Zscaler/CrowdStrike 環境，配 NODE_EXTRA_CA_CERTS
4. 準備 fallback: 允許 Bash（curl:*），讓 Claude 遇阻時自動切換
5. 健康檢查腳本: 把 claude-code-doctor.sh 加入團隊工具鏈

國內用戶最佳實踐 · 分路徑分層架構 API 路徑與 WebFetch 路徑解耦 · 互不影響

開發者本機 Claude Code CLI NO_PROXY 配置: api.apiyi.com

① API 路徑 APIYI 透明轉發 vip.apiyi.com （直連）

② Preflight 路徑 本地代理 127.0.0.1:7890

③ Fallback Bash（curl:*） 直連目標站點

Anthropic API api.anthropic.com 模型推理 + 工具決策

claude.ai/code/ 域名校驗端點 （Cloudflare 防護）

目標網站 weather.com.cn 等 直連（無需 preflight）