Dépannage complet de l’erreur WebFetch de Claude Code : 4 étapes pour résoudre le problème Unable to verify if domain

Couche 4 · Contourner WebFetch Remplacement de Bash(curl:*) · ou intégration de fetch-mcp / serveur MCP Playwright 🎯 Scénarios où le conteneur CI / preflight ne fonctionne pas du tout · Contourner complètement le preflight de claude.ai 15 minutes Solution ultime

Niveau 1 : Proxy et variables d'environnement NO_PROXY

C'est le premier obstacle courant pour les utilisateurs en Chine. Claude Code respecte les variables d'environnement de proxy standard, lues dans cet ordre de priorité :

https_proxy > HTTPS_PROXY > http_proxy > HTTP_PROXY

Configuration minimale pour macOS / Linux :

# ~/.zshrc ou ~/.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"

Pour 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"

Vous pouvez également l'ajouter directement dans le bloc env du fichier ~/.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"
  }
}

⚠️ Détail crucial : Vous devez ajouter les domaines de service proxy API d'APIYI (api.apiyi.com / vip.apiyi.com) à NO_PROXY ! Sinon, l'invocation du modèle par Claude Code passera par le proxy, ce qui ralentira les échanges et risque une interception par le nœud de proxy. Nous recommandons de laisser l'API passer par NO_PROXY pour une connexion directe à APIYI, et de laisser le preflight de WebFetch passer par le proxy pour accéder à claude.ai : séparer ces deux flux est la configuration la plus stable.

Proxy avec authentification de base (courant en entreprise) :

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

Note : Claude Code ne prend pas en charge les proxys SOCKS — si votre proxy n'est qu'en mode SOCKS, utilisez privoxy ou v2ray pour convertir SOCKS en HTTP.

Niveau 2 : Pré-autorisation des permissions WebFetch(domain:xxx)

Parfois, le preflight fonctionne, mais Claude Code demande systématiquement "Autoriser l'accès à ce domaine ?". Ajoutez les domaines fréquemment utilisés à permissions.allow pour éviter ces sollicitations :

{
  "permissions": {
    "allow": [
      "WebFetch(domain:www.weather.com.cn)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:developer.mozilla.org)",
      "WebFetch(domain:docs.python.org)"
    ],
    "ask": [
      "WebFetch"
    ]
  }
}

Aide-mémoire pour la syntaxe des règles :

🎯 Conseil de gestion : En entreprise, nous recommandons d'utiliser managed-settings.json pour définir une liste blanche de domaines autorisés, située dans /Library/Application Support/ClaudeCode/managed-settings.json (macOS) ou /etc/claude-code/managed-settings.json (Linux), couplée à allowManagedPermissionRulesOnly: true pour forcer le respect des règles par tous les développeurs. Les équipes de développement qui utilisent l'API Claude via APIYI (apiyi.com) peuvent appliquer la même stratégie pour garantir une cohérence entre les politiques de permissions de Claude Code et celles de l'invocation du modèle en backend.

Niveau 3 : Certificats CA d'entreprise et interception TLS

Si votre entreprise utilise des produits de sécurité avec interception TLS comme Zscaler / CrowdStrike / Cato Networks, ils réémettent des certificats HTTPS, ce qui provoque des erreurs SSL comme UNABLE_TO_GET_ISSUER_CERT dans l'environnement d'exécution Node.js de Claude Code.

Solution : Exportez le certificat racine CA de l'entreprise et pointez vers lui :

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

Ou ajoutez-le dans ~/.claude/settings.json :

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

Valeurs possibles pour CLAUDE_CODE_CERT_STORE :

Authentification mutuelle mTLS (environnements d'entreprise stricts) :

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="votre-phrase-secrete"

Niveau 4 : Contourner WebFetch avec Bash curl ou MCP

Si les trois niveaux précédents ne résolvent pas le problème, la méthode la plus fiable est de ne pas utiliser WebFetch — demandez à Claude d'utiliser directement curl via l'outil Bash, ou connectez un serveur MCP fetch tiers.

Option A : Autoriser Bash à utiliser curl/wget

{
  "permissions": {
    "allow": [
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

Ensuite, demandez simplement à Claude dans la conversation : "Utilise curl pour récupérer le contenu de la page d'accueil de www.weather.com.cn" — il ignorera WebFetch et passera par Bash. Ce chemin ne déclenche absolument aucun preflight, la configuration du proxy doit simplement permettre l'accès au site cible.

Option B : Connecter fetch-mcp ou Playwright MCP

# Installer le serveur MCP fetch tiers
claude mcp add fetch npx -- @modelcontextprotocol/server-fetch

Les requêtes réseau des outils MCP sont initiées par le processus du serveur MCP lui-même, sans passer par la chaîne de preflight de Claude Code, ce qui améliore considérablement la stabilité. Pour les sites dynamiques nécessitant l'exécution de JavaScript, Playwright MCP est plus approprié.

Matrice de comparaison des solutions de dépannage WebFetch ★ Plus il y en a, plus c'est adapté · Regardez quelle colonne a le plus de couleur foncée

Dimensions d’évaluation

A. Configuration du proxy HTTPS_PROXY

B. Préautorisation des droits d’accès WebFetch(domain)

C. Entreprise CA NODE_EXTRA_CA_CERTS

D. Contourner WebFetch Bash curl + MCP

Difficulté de configuration ★★★★☆ ★★★★★ ★★☆☆☆ ★★★★☆

Résoudre l’étendue des problèmes ★★★★★ ★★☆☆☆ ★★★☆☆ ★★★★★

Impact sur les performances ★★★☆☆ ★★★★★ ★★★★☆ ★★★★☆

Conformité d’entreprise ★★★☆☆ ★★★★★ ★★★★★ ★★★☆☆

Adaptation nationale ★★★★☆ ★★★☆☆ ★★☆☆☆ ★★★★★

💡 Recommandation pour les utilisateurs nationaux : A (base de proxy) + B (domaine commun) + D (fallback)

Études de cas pratiques sur le dépannage de Claude Code WebFetch

Maintenant que la théorie est posée, examinons les processus de résolution complets pour trois scénarios réels.

Scénario 1 : MacBook en Chine tentant de récupérer weather.com.cn (scénario de capture d'écran)

Symptôme : La commande fetch sur www.weather.com.cn renvoie continuellement "Unable to verify".

Étapes de dépannage :

# Étape 1 : Vérifier l'état du proxy
echo $HTTPS_PROXY  # Devrait afficher quelque chose comme http://127.0.0.1:7890

# Étape 2 : Vérifier manuellement si claude.ai est accessible
curl -I https://claude.ai/code/ -x http://127.0.0.1:7890
# Si cela renvoie 403 + cf-mitigated, Cloudflare bloque, passez à l'étape 3
# Si cela renvoie 200, le preflight fonctionne, vérifiez les permissions

# Étape 3 : Changer de stratégie dans Claude Code — utiliser Bash + curl
# Dites directement dans la conversation :
# "N'utilise pas WebFetch, utilise curl pour récupérer la page d'accueil de http://www.weather.com.cn"

Configuration finale (~/.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:*)"
    ]
  }
}

🎯 Conseil pratique en Chine : La combinaison la plus stable pour les utilisateurs locaux est : « API via APIYI apiyi.com + WebFetch via proxy + fallback sur curl si nécessaire ». En ajoutant la base_url d'APIYI à NO_PROXY, les requêtes API de Claude Code ne sont pas détournées par le proxy, garantissant une latence et une stabilité identiques à une connexion directe à l'étranger.

Scénario 2 : Machine d'entreprise + interception TLS Zscaler

Symptôme : WebFetch renvoie SELF_SIGNED_CERT_IN_CHAIN ou UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Solution :

# Étape 1 : Récupérer le certificat racine CA de l'entreprise auprès de l'IT (généralement .pem ou .crt)
# Étape 2 : Configurer Claude Code pour faire confiance à ce CA
export NODE_EXTRA_CA_CERTS=~/certs/company-zscaler-root.pem

# Étape 3 : Faire confiance simultanément au magasin de certificats système (Zscaler y est généralement déjà injecté)
export CLAUDE_CODE_CERT_STORE=bundled,system

# Étape 4 : Redémarrer Claude Code

Scénario 3 : Exécution headless dans Docker / CI

Symptôme : Fonctionne en local, mais WebFetch échoue à 100 % en CI.

Cause : Le conteneur ne dispose ni de proxy ni de navigateur, et la protection bot de Cloudflare identifie directement le client CLI et refuse la connexion.

Solution : Désactiver WebFetch et forcer l'utilisation de Bash dans la CI :

# .github/workflows/claude.yml ou similaire
env:
  CLAUDE_CODE_DISABLE_WEBFETCH: "true"  # Si cette variable d'environnement est prise en compte

Ou via les paramètres de lancement --disallowedTools :

claude --disallowedTools WebFetch --allowedTools "Bash(curl:*)"

🎯 Conseil d'intégration CI : Dans un environnement conteneurisé, dirigez la clé API vers le nœud de service proxy API stable d'APIYI (apiyi.com) pour éviter les échecs de CI dus aux instabilités réseau internationales. Nous recommandons de configurer ANTHROPIC_BASE_URL=https://vip.apiyi.com + ANTHROPIC_API_KEY=sk-xxx dans les secrets de GitHub Actions / GitLab CI. Avec la stratégie de désactivation de WebFetch, la stabilité des tâches Claude Code en CI peut atteindre plus de 99 %.

Meilleures pratiques d'ingénierie pour les erreurs WebFetch de Claude Code

Il est facile de faire fonctionner une démo ponctuelle, mais pour garantir une utilisation stable de Claude Code par toute l'équipe, voici quelques points clés.

Pratique 1 : Un fichier managed-settings.json unifié

Distribuez un managed-settings.json unifié à l'équipe pour éviter que chacun ne doive tâtonner de son côté :

{
  "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
}

Emplacement du fichier :

Pratique 2 : Stratégie de fallback à trois niveaux

Définissez clairement la priorité de sélection des outils dans CLAUDE.md pour que Claude les essaie dans l'ordre :

## Priorité des outils de web scraping

1. Priorité à WebFetch (domaines pré-autorisés)
2. En cas d'échec de WebFetch, basculer sur `curl` via Bash
3. Pour les sites dynamiques, utiliser Playwright MCP
4. Ne jamais utiliser `curl -k` pour ignorer les erreurs de certificat

Une fois cette configuration ajoutée au fichier CLAUDE.md, Claude basculera automatiquement sur curl lorsqu'il rencontrera une erreur avec WebFetch, ce qui améliore considérablement l'expérience utilisateur.

### Pratique n°3 : Script de diagnostic "preflight"

Voici un script de diagnostic rapide à exécuter en cas de problème :

```bash
#!/bin/bash
# claude-code-doctor.sh

echo "=== Variables d'environnement ==="
env | grep -iE "proxy|claude_code|node_extra"

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

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

echo "=== Test du service proxy APIYI ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://vip.apiyi.com/

echo "=== Résolution DNS ==="
nslookup claude.ai

Si claude.ai/code/ renvoie une erreur 403 avec l'en-tête cf-mitigated, il s'agit d'un problème classique de preflight Cloudflare. Passez directement à la solution de niveau 4.

🎯 Conseil de diagnostic : 80 % des problèmes liés à Claude Code peuvent être résolus grâce à ce script. Pour les utilisateurs en Chine, nous recommandons d'ajouter vip.apiyi.com à votre liste de vérification. Si APIYI est accessible mais que le site officiel d'Anthropic ne l'est pas, utilisez le service proxy APIYI (apiyi.com) pour poursuivre votre travail sans bloquer votre flux de développement.

FAQ sur les erreurs WebFetch de Claude Code

Q1 : Pourquoi le message d'erreur indique-t-il "enterprise security policies blocking claude.ai" alors que mon entreprise n'a installé aucun logiciel de sécurité ?

Ce message d'erreur d'Anthropic est imprécis. Ce qui bloque réellement, c'est la protection anti-bot Cloudflare devant claude.ai. Cloudflare identifie le processus CLI comme un bot et renvoie un "JS Challenge" que la CLI ne peut pas résoudre. Cela n'a généralement rien à voir avec la politique informatique de votre entreprise.

Q2 : Le service proxy APIYI peut-il résoudre les erreurs WebFetch ?

Partiellement. APIYI (apiyi.com) gère uniquement le transfert des requêtes API vers api.anthropic.com. Les conversations et les décisions d'invocation du modèle fonctionnent parfaitement. Cependant, le preflight de WebFetch cible claude.ai (et non api.anthropic.com), un chemin que APIYI ne couvre pas. Il est recommandé de combiner les deux : utilisez APIYI pour l'API et un proxy local pour le preflight.

Q3 : Existe-t-il une option de configuration skipWebFetchPreflight ?

Le sujet est débattu dans la communauté, mais à ce jour (avril 2026), rien n'est documenté officiellement. L'issue GitHub #39896 mentionne cette attente. En attendant un support officiel, la solution de niveau 4 (Bash curl + domaines pré-autorisés) reste la méthode la plus fiable et contrôlable.

Q4 : J'ai activé le proxy global Clash, pourquoi WebFetch affiche-t-il toujours des erreurs ?

Le mode proxy global de Clash ne définit pas automatiquement les variables d'environnement. Claude Code est un processus Node.js CLI qui ne lit que les variables comme HTTPS_PROXY et ne détecte pas les paramètres de proxy système. Vous devez exporter explicitement les variables de proxy dans votre profil shell ou les ajouter dans le bloc env du fichier ~/.claude/settings.json.

Q5 : WebFetch réussit, mais le résultat est incomplet (tronqué) ?

C'est dû à la limite max_content_tokens de Claude Code. Elle ne peut pas être ajustée via les règles de permission, mais si vous appelez l'outil web_fetch directement via l'API Claude (hors CLI), vous pouvez définir "max_content_tokens": 100000 pour augmenter la capacité de capture. Dans ce cas, l'utilisation d'APIYI (apiyi.com) pour l'API offre une plus grande flexibilité.

Q6 : Peut-on éviter totalement les erreurs en désactivant WebFetch ?

Oui. Ajoutez ce paramètre au démarrage :

claude --disallowedTools WebFetch

Ou dans settings.json :

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

En autorisant Bash(curl:*), Claude basculera automatiquement sur curl, ce qui offre souvent une meilleure expérience.

Q7 : Comment configurer Claude Code dans GitHub Actions / GitLab CI ?

Dans un conteneur CI, il est fortement recommandé de désactiver WebFetch, car l'environnement sans navigateur fera presque systématiquement échouer le preflight. Dirigez également les requêtes API vers le nœud stable d'APIYI (apiyi.com) :

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

Résumé des erreurs Claude Code WebFetch et liste d'actions

Pour faire le point, l'erreur Claude Code WebFetch est fondamentalement liée aux limitations de conception du preflight Cloudflare + l'absence de navigateur dans l'interface CLI. Ce n'est pas un problème lié à votre réseau ou à vos politiques informatiques. En résumé :

✅ La stratégie gagnante pour les utilisateurs en Chine : Utilisez le service proxy API APIYI (apiyi.com) pour une connexion directe + un proxy local pour le preflight de claude.ai + Bash curl comme solution de repli (fallback). Cela permet de contourner 90 % des erreurs WebFetch.

Liste d'actions à mettre en œuvre

Suivez ces 5 étapes par ordre de priorité :

1. Configuration du proxy : Définissez HTTPS_PROXY + HTTP_PROXY, et ajoutez le domaine APIYI à NO_PROXY.
2. Pré-autorisation des domaines : Ajoutez les sites fréquemment consultés dans permissions.allow via WebFetch(domain:...).
3. Gestion des certificats CA d'entreprise : Si vous êtes dans un environnement Zscaler/CrowdStrike, configurez NODE_EXTRA_CA_CERTS.
4. Préparation du fallback : Autorisez Bash(curl:*) pour permettre à Claude de basculer automatiquement en cas de blocage.
5. Script de diagnostic : Intégrez claude-code-doctor.sh à votre chaîne d'outils d'équipe.

Meilleures pratiques pour les utilisateurs nationaux · Architecture segmentée par chemin et par couche Découplage du chemin API et du chemin WebFetch · Aucune influence mutuelle

Machine locale du développeur Claude Code CLI Configuration NO_PROXY : api.apiyi.com

① Chemin API APIYI transfert transparent vip.apiyi.com (connexion directe)

② Chemin Preflight proxy local 127.0.0.1:7890

③ Repli Bash(curl:*) Connexion directe au site cible

API Anthropic api.anthropic.com Inférence du modèle + décision par outils

claude.ai/code/ point de terminaison de vérification de domaine (Protection Cloudflare)

Site cible weather.com.cn et autres Connexion directe (sans preflight)