claude code webfetch unable to verify domain fix es image 0 图示

Solución completa de errores de Claude Code WebFetch: 4 pasos para resolver el problema Unable to verify if domain

por

Si intentas usar fetch con http://www.weather.com.cn en Claude Code y recibes 5 veces seguidas el mismo error en rojo: Unable to verify if domain www.weather.com.cn is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai., parece que es un problema de "bloqueo de red/firewall en claude.ai", pero la realidad es otra: este mensaje de error es profundamente engañoso tanto para los usuarios como para los equipos de operaciones.

claude-code-webfetch-unable-to-verify-domain-fix-es 图示

Este artículo desglosa sistemáticamente la causa raíz del error WebFetch de Claude Code, basándose en issues oficiales de GitHub de Anthropic, la documentación de configuración de red de Claude Code y resultados de pruebas de la comunidad, ofreciendo un plan de resolución de 4 niveles. Al final, incluimos las mejores prácticas para usuarios que utilizan Claude Code a través de APIYI (apiyi.com): APIYI solo se encarga del reenvío de la API, el problema de preflight de WebFetch debe resolverse mediante una combinación de proxy y configuración.

La causa real del error WebFetch de Claude Code

Antes de empezar a cambiar configuraciones, aclaremos qué significa realmente el mensaje de error. Este error de WebFetch en Claude Code es un caso clásico de "confundir un resfriado con cáncer".

La verdad detrás del mensaje de error

Antes de que Claude Code ejecute cualquier llamada WebFetch, realiza una "verificación de seguridad de dominio" (preflight): envía una solicitud HTTP a https://claude.ai/code/ para preguntar: "¿Se puede extraer este dominio?". El problema ocurre precisamente en este paso:

Etapa Lo que sucede realmente
① Claude Code dispara WebFetch El proceso CLI prepara la URL objetivo
② Solicitud de Preflight Envía una solicitud HTTP a https://claude.ai/code/
③ Intercepción de protección Bot de Cloudflare Devuelve 403 + cf-mitigated: challenge + JS Challenge
④ CLI sin entorno de navegador No puede ejecutar el desafío de JavaScript
⑤ Fallo de Preflight Lanza el error "Unable to verify if domain is safe"
⑥ La URL objetivo nunca se visita Tu red no tiene nada que ver con weather.com.cn

En otras palabras, la accesibilidad del sitio objetivo nunca se llega a probar; la solicitud falla en el segundo paso. La mención en el mensaje de error sobre "enterprise security policies blocking claude.ai" es cierta, pero la "política empresarial" no es la de tu empresa, sino las reglas de protección de Cloudflare desplegadas por la propia Anthropic frente a claude.ai.

🎯 Punto clave: Este es un problema de diseño a nivel de arquitectura, confirmado en el issue #39896 del GitHub oficial de Anthropic. Afecta a todos los entornos headless: CI/CD, contenedores Docker, WSL, sesiones SSH y despliegues en Bedrock. Lo mismo ocurre al reenviar llamadas a la API a través de APIYI (apiyi.com), ya que el preflight se dirige a claude.ai y no a api.anthropic.com.

Tres escenarios de fallo típicos

Dependiendo de tu entorno de red, este error puede ser causado por diferentes factores superpuestos:

Escenario Sitio objetivo Estado del proxy Causa raíz
A. Máquina local + Sin proxy Cualquier sitio extranjero Sin proxy Fallo de conexión directa a claude.ai + fallo de preflight
B. Máquina local + Proxy activo Sitio local (weather.com.cn) Proxy a extranjero El preflight accede a claude.ai a través del proxy, pero aún puede recibir el desafío de Cloudflare
C. Máquina extranjera + Sin proxy Cualquier sitio Sin proxy Cloudflare identifica la CLI como un bot, fallo de preflight

El caso del usuario en la captura que intenta hacer fetch a www.weather.com.cn pertenece al Escenario B: parece que "debería poder acceder a un sitio local", pero en realidad es el preflight hacia claude.ai el que falla, sin tener nada que ver con el sitio objetivo.

Ruta de resolución de errores de 4 niveles para WebFetch en Claude Code

Una vez identificada la causa raíz, procedemos a realizar una revisión capa por capa, siguiendo el orden de "menor a mayor impacto".

claude-code-webfetch-unable-to-verify-domain-fix-es 图示

Nivel 1: Variables de entorno de proxy y NO_PROXY

Este es el primer obstáculo común para los usuarios. Claude Code sigue las variables de entorno estándar de proxy, leyéndolas en el siguiente orden de prioridad:

https_proxy > HTTPS_PROXY > http_proxy > HTTP_PROXY

Configuración mínima para macOS / Linux:

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

También puedes escribirlo directamente en el bloque env de ~/.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"
  }
}

⚠️ Detalle clave: ¡Debes incluir el dominio del servicio proxy de API de APIYI (api.apiyi.com / vip.apiyi.com) en NO_PROXY! De lo contrario, la invocación del modelo de Claude Code pasará por el proxy, lo cual es lento y podría ser interceptado por el nodo del proxy. Recomendamos que la API se conecte directamente a APIYI a través de NO_PROXY, mientras que el preflight de WebFetch utilice el proxy para acceder a claude.ai; separar ambas rutas es lo más estable.

Proxy con autenticación básica (común en entornos corporativos):

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

Nota: Claude Code no admite proxies SOCKS. Si tu proxy solo tiene modo SOCKS, utiliza privoxy o v2ray para convertir SOCKS a HTTP.

Nivel 2: Preautorización de permisos WebFetch(domain:xxx)

A veces el preflight funciona, pero Claude Code sigue preguntando cada vez "¿Permitir acceso a este dominio?". Añade los dominios frecuentes a permissions.allow para que Claude deje de preguntar:

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

Referencia rápida de sintaxis de reglas:

Sintaxis de regla Alcance de coincidencia
WebFetch Todas las llamadas de WebFetch
WebFetch(domain:example.com) Solo example.com
WebFetch(domain:*.example.com) Todos los subdominios de example.com
WebFetch(domain:*) Cualquier dominio (equivalente a permitir todo)

🎯 Consejo de gestión: En entornos corporativos, recomendamos usar managed-settings.json para establecer una lista blanca de dominios permitidos, ubicada en /Library/Application Support/ClaudeCode/managed-settings.json (macOS) o /etc/claude-code/managed-settings.json (Linux), junto con allowManagedPermissionRulesOnly: true para obligar a todos los desarrolladores a cumplirla. Los equipos de desarrollo que invocan el modelo de Claude a través de APIYI (apiyi.com) también pueden usar el mismo conjunto de reglas para garantizar que las políticas de permisos de Claude Code y las llamadas a la API del backend sean uniformes.

Nivel 3: Certificados CA corporativos e interceptación TLS

Si tu empresa utiliza productos de seguridad con interceptación TLS como Zscaler / CrowdStrike / Cato Networks, estos volverán a emitir certificados HTTPS, lo que provocará que el entorno de ejecución de Node.js de Claude Code reporte errores SSL como UNABLE_TO_GET_ISSUER_CERT.

Solución: Exporta el certificado CA raíz de la empresa y apúntalo:

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

O escríbelo en ~/.claude/settings.json:

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

Valores posibles para CLAUDE_CODE_CERT_STORE:

Valor Significado
bundled Solo confía en el conjunto de CA de Mozilla incluido en Claude Code
system Solo confía en el almacén de certificados del sistema operativo
bundled,system (predeterminado) Confía en ambos

Autenticación bidireccional mTLS (entornos corporativos más estrictos):

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="tu-contraseña"

Nivel 4: Evitar WebFetch, usar Bash curl o MCP como alternativa

Si ninguno de los tres niveles anteriores resuelve el problema, la forma más fiable es no usar WebFetch: permite que Claude utilice curl directamente a través de la herramienta Bash, o conéctalo a un servidor MCP de fetch de terceros.

Opción A: Permitir que Bash use curl/wget

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

Luego, en la conversación, dile a Claude: "Por favor, usa curl para obtener el contenido de la página principal de www.weather.com.cn"; omitirá WebFetch y usará Bash directamente. Esta ruta no activa el preflight, solo necesitas configurar el proxy para que el sitio de destino sea accesible.

Opción B: Conectar fetch-mcp o Playwright MCP

# Instalar servidor fetch MCP de terceros
claude mcp add fetch npx -- @modelcontextprotocol/server-fetch

Las solicitudes de red de las herramientas MCP son iniciadas por el propio proceso del servidor MCP, sin pasar por el enlace de preflight de Claude Code, lo que mejora significativamente la estabilidad. Para sitios dinámicos que requieren la ejecución de JavaScript, es más adecuado usar Playwright MCP.

claude-code-webfetch-unable-to-verify-domain-fix-es 图示

Casos prácticos de resolución de problemas con WebFetch de Claude Code

Una vez vista la teoría, analicemos el flujo de resolución completo en tres escenarios reales.

Escenario 1: Captura de weather.com.cn en un MacBook en China (escenario de captura de pantalla)

Fenómeno: fetch a www.weather.com.cn reporta continuamente Unable to verify.

Pasos para la resolución:

# Paso 1 Confirmar el estado del proxy
echo $HTTPS_PROXY  # Debería mostrar algo como http://127.0.0.1:7890

# Paso 2 Verificar manualmente si claude.ai es accesible
curl -I https://claude.ai/code/ -x http://127.0.0.1:7890
# Si devuelve 403 + cf-mitigated, significa que Cloudflare bloqueó el acceso, ve al Paso 3
# Si devuelve 200, significa que el preflight funciona, revisa los permisos

# Paso 3 Cambiar la estrategia en Claude Code: usar Bash + curl
# Dile directamente en el chat:
# "No uses WebFetch, usa curl para capturar la página de inicio de http://www.weather.com.cn"

Configuración final (~/.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:*)"
    ]
  }
}

🎯 Consejo práctico en China: La combinación más estable para usuarios locales es: "API a través de APIYI apiyi.com + WebFetch a través de proxy + fallback a curl cuando sea necesario". Al añadir el base_url de APIYI a NO_PROXY, las solicitudes de API de Claude Code no se desvían por el proxy, manteniendo la latencia y estabilidad iguales a una conexión directa al extranjero.

Escenario 2: Máquina corporativa + interceptación TLS de Zscaler

Fenómeno: WebFetch reporta SELF_SIGNED_CERT_IN_CHAIN o UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Solución:

# Paso 1 Obtener el certificado CA raíz de la empresa (normalmente .pem o .crt)
# Paso 2 Configurar Claude Code para confiar en este CA
export NODE_EXTRA_CA_CERTS=~/certs/company-zscaler-root.pem

# Paso 3 Confiar también en el almacén de certificados del sistema (Zscaler suele estar inyectado)
export CLAUDE_CODE_CERT_STORE=bundled,system

# Paso 4 Reiniciar Claude Code

Escenario 3: Ejecución headless en Docker / CI

Fenómeno: Funciona localmente, pero WebFetch falla al 100% en CI.

Causa: El contenedor no tiene proxy ni navegador, y la protección bot de Cloudflare detecta el cliente CLI y rechaza la conexión.

Solución: Deshabilitar WebFetch en CI y forzar el uso de Bash:

# .github/workflows/claude.yml o similar
env:
  CLAUDE_CODE_DISABLE_WEBFETCH: "true"  # Si esta variable de entorno está activa

O mediante el parámetro de inicio --disallowedTools:

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

🎯 Sugerencia de integración CI: En entornos contenedorizados, apunta la clave API hacia el nodo de servicio proxy de API estable de APIYI (apiyi.com) para evitar fallos en CI debido a la inestabilidad de la red internacional. Recomendamos configurar ANTHROPIC_BASE_URL=https://vip.apiyi.com + ANTHROPIC_API_KEY=sk-xxx en los secretos de GitHub Actions / GitLab CI. Junto con la política de deshabilitar WebFetch, la estabilidad de las tareas de Claude Code en CI puede alcanzar más del 99%.

Mejores prácticas de ingeniería para errores de WebFetch en Claude Code

Hacer funcionar una demo es sencillo, pero para que todos en el equipo usen Claude Code de forma estable, hay puntos clave.

Práctica 1: managed-settings.json unificado

Distribuye un managed-settings.json unificado al equipo para evitar que cada uno tenga que configurar lo suyo:

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

Ruta de ubicación del archivo:

Plataforma Ruta
macOS /Library/Application Support/ClaudeCode/managed-settings.json
Linux /etc/claude-code/managed-settings.json
Windows C:\ProgramData\ClaudeCode\managed-settings.json

Práctica 2: Estrategia de fallback de tres niveles

Define claramente la prioridad de selección de herramientas en CLAUDE.md para que Claude las pruebe en orden:


## Prioridad de las herramientas de web scraping

1. Preferencia por WebFetch (dominios preautorizados)
2. Si WebFetch falla, recurrir a Bash curl
3. Para sitios dinámicos, usar Playwright MCP
4. Nunca usar `curl -k` para ignorar errores de certificados

Al incluir esto en CLAUDE.md, Claude cambiará automáticamente a curl cuando WebFetch arroje un error, mejorando notablemente la experiencia del usuario.

Práctica 3: Script de verificación de salud (preflight)

Crea un script de diagnóstico rápido y ejecútalo antes de empezar a investigar:

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

echo "=== Variables de entorno ==="
env | grep -iE "proxy|claude_code|node_extra"

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

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

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

echo "=== Resolución DNS ==="
nslookup claude.ai

Si claude.ai/code/ devuelve un 403 con la cabecera de respuesta cf-mitigated, es un problema típico de preflight de Cloudflare; aplica directamente la solución de capa 4.

🎯 Consejo de diagnóstico: Cuando Claude Code presente anomalías, el 80% de los problemas se pueden localizar con este script. Para usuarios en China, se recomienda añadir vip.apiyi.com como nodo de reenvío de API a la lista de verificación. Si APIYI es accesible pero el sitio oficial de Anthropic no, utiliza el servicio proxy de API de APIYI (apiyi.com) para continuar trabajando y evitar que los problemas de red bloqueen tu ritmo de desarrollo.

Preguntas frecuentes sobre errores de WebFetch en Claude Code

Q1: ¿Por qué el mensaje de error dice "enterprise security policies blocking claude.ai" si mi empresa no tiene instalado ningún software de seguridad?

Este mensaje oficial de Anthropic no es preciso. Lo que realmente bloquea el acceso es la protección contra bots de Cloudflare frente a claude.ai. Cloudflare identifica el proceso CLI como un bot y devuelve un "JS Challenge"; si la CLI no puede completar el desafío, arroja este error. Generalmente no tiene nada que ver con las políticas de TI de tu empresa.

Q2: ¿Puede el servicio proxy de API de APIYI resolver los errores de WebFetch?

Parcialmente. APIYI (apiyi.com) solo se encarga de reenviar las solicitudes de API a api.anthropic.com, permitiendo que las conversaciones con el Modelo de Lenguaje Grande y la toma de decisiones de herramientas de Claude Code funcionen de forma estable. Sin embargo, el preflight de WebFetch apunta a claude.ai (no a api.anthropic.com), una ruta que APIYI no cubre; esto debe resolverse mediante un proxy local. Se recomienda un uso combinado: la API a través de la conexión directa de APIYI y el preflight a través de un proxy; ambas rutas son independientes.

Q3: ¿Existe una opción de configuración llamada skipWebFetchPreflight?

Hay debates en la comunidad, pero hasta abril de 2026 no hay documentación oficial. El issue #39896 de GitHub menciona que es una función esperada por la comunidad para omitir la validación de preflight. Hasta que sea compatible oficialmente, se recomienda usar la solución de capa 4 (Bash curl + dominios preautorizados) para evitar este problema, ya que el efecto es equivalente y más controlable.

Q4: Tengo activado el proxy global de Clash, ¿por qué WebFetch sigue dando error?

El modo proxy global de Clash no configura automáticamente las variables de entorno. Claude Code es un proceso CLI de Node.js que solo lee variables de entorno como HTTPS_PROXY y no detecta la configuración de proxy del sistema. Debes exportar explícitamente las variables de proxy en tu shell profile o incluirlas en el bloque env de ~/.claude/settings.json.

Q5: WebFetch tuvo éxito pero el resultado está incompleto, ¿solo tengo la mitad del contenido?

Esto se debe al límite max_content_tokens de Claude Code. No se puede ajustar en las reglas de permisos, pero si invocas la herramienta web_fetch directamente a través de la API de Claude (no mediante la CLI de Claude Code), puedes configurar "max_content_tokens": 100000 para aumentar la cantidad de extracción por página. En este escenario, se recomienda la conexión directa a la API a través de APIYI (apiyi.com) para mayor flexibilidad.

Q6: ¿Se pueden evitar los errores deshabilitando WebFetch por completo?

Sí. Añade el parámetro al iniciar:

claude --disallowedTools WebFetch

O en settings.json:

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

Al combinarlo con el permiso para Bash(curl:*), Claude cambiará automáticamente a curl, lo cual resulta en una mejor experiencia para los usuarios en China.

Q7: ¿Cómo configurar Claude Code en GitHub Actions / GitLab CI?

En contenedores de CI, se recomienda al 100% deshabilitar WebFetch; los contenedores no tienen entorno de navegador y el preflight casi siempre fallará. Al mismo tiempo, apunta las solicitudes de API al nodo estable de APIYI (apiyi.com):

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

Resumen de errores y lista de acciones para Claude Code WebFetch

Al repasar todo el contenido, la esencia de los errores de Claude Code WebFetch radica en las limitaciones de diseño de Cloudflare preflight + CLI sin navegador, no en tu red o políticas de TI. En resumen:

✅ La estrategia clave para usuarios en China: API a través de APIYI (apiyi.com) con conexión directa + proxy local para el preflight de claude.ai + Bash curl como alternativa (fallback). Esto soluciona el 90% de los errores de WebFetch.

Lista de acciones prácticas

Ejecuta estos 5 pasos por orden de prioridad:

  1. Configurar el proxy: Define HTTPS_PROXY + HTTP_PROXY y añade el dominio de APIYI a NO_PROXY.
  2. Preautorizar dominios: Incluye los sitios que consultas frecuentemente en permissions.allow dentro de WebFetch(domain:...).
  3. Gestionar CA corporativos: Si estás en un entorno con Zscaler o CrowdStrike, configura NODE_EXTRA_CA_CERTS.
  4. Preparar el fallback: Permite Bash(curl:*) para que Claude cambie automáticamente de método cuando encuentre bloqueos.
  5. Script de verificación de salud: Añade claude-code-doctor.sh a la cadena de herramientas de tu equipo.

claude-code-webfetch-unable-to-verify-domain-fix-es 图示

🎯 Consejo final: Los problemas de red de Claude Code son un sistema de ingeniería con múltiples capas acopladas: proxy, certificados, reglas de permisos y prioridades de herramientas son indispensables. Recomendamos usar primero APIYI (apiyi.com) para establecer la ruta de invocación del modelo (esta parte tiene el SLA más controlable) y luego abordar capa por capa los problemas de preflight y CA de WebFetch. La plataforma admite toda la gama de modelos de Claude + herramientas nativas, lo que facilita la verificación rápida de si cada capa de configuración es efectiva.

Autor: Equipo técnico de APIYI | Para más tutoriales prácticos de Claude Code, visita help.apiyi.com

Deja un comentario