Cómo usar un proxy con OkHttp (Guía completa 2026)
TL;DR
Un proxy de OkHttp se configura en OkHttpClient.Builder, no en una Request individual. Usa .proxy(proxy) para una ruta explícita o déjalo sin establecer para que proxySelector elija rutas.
Los proxies autenticados necesitan proxyAuthenticator, que responde a un desafío 407 con Proxy-Authorization. Detente cuando ese encabezado ya esté presente para que las credenciales incorrectas no creen un bucle de autenticación.
Reutiliza instancias de OkHttpClient en lugar de crear una por solicitud. Un pequeño grupo de clientes preconstruidos proporciona una rotación de endpoint predecible sin descartar grupos de conexiones y grupos de hilos.
HTTPS sigue pasando a través de un proxy HTTP utilizando CONNECT. Mantén la verificación de TLS habilitada porque el proxy cambia la ruta, no los requisitos del certificado de destino.
Prueba la ruta antes de escalar. Compara la IP de salida observada, valida la respuesta y clasifica los errores de conexión del proxy por separado de los errores HTTP de destino.
¿Qué es un Proxy de OkHttp?
Un proxy de OkHttp es un servidor intermediario seleccionado por un OkHttpClient para conexiones HTTP y HTTPS salientes. La aplicación envía tráfico al proxy, que lo reenvía al destino y devuelve la respuesta. OkHttp sigue manejando solicitudes, respuestas, agrupación, tiempos de espera y TLS; el proxy controla la ruta de red y la IP de origen visible para el destino.
OkHttp utiliza el modelo java.net.Proxy de Java. La actual dice que un explícito tiene prioridad sobre . Si no se establece un proxy explícito, el selector puede elegir uno de la política del sistema o de la aplicación. Pasar obliga a una conexión directa en su lugar.
Esta configuración estándar funciona con una puerta de enlace interna, un proxy de depuración o un endpoint gestionado como Nstproxy Residential Prime Proxies. Un proxy cambia el enrutamiento; no otorga permiso para acceder a un recurso ni reemplaza límites de tasa y términos específicos de destino.
¿Por qué usar un Proxy con OkHttp?
Un proxy con OkHttp es útil cuando una aplicación de Java o Android necesita una salida controlada, QA localizado, verificación de anuncios, recopilación de datos públicos o separación entre clases de tráfico. También puede hacer que un camino de red sea reproducible: el código identifica la ruta seleccionada mientras que las operaciones pueden cambiar el endpoint fuera de un despliegue.
El modelo de sesión debe seguir el flujo de trabajo. Varias solicitudes pertenecientes a un inicio de sesión o flujo de compra pueden necesitar una ruta estable, mientras que comprobaciones no relacionadas pueden usar rotación. La visión general de rotación de IP de Nstproxy explica ese patrón de red; la aplicación aún necesita concurrencia limitada, validación de respuestas y límites de reintentos.
OkHttp está diseñado para la reutilización del cliente. Reutilizar un cliente preserva su grupo de conexiones y recursos de ejecutor. Si las cargas de trabajo necesitan diferentes políticas de proxy, crea un pequeño número de clientes de larga duración—uno por política o endpoint—en lugar de construir un nuevo cliente para cada llamada.
Requisitos Previos
Los ejemplos requieren Java 8 o más reciente, Gradle, OkHttp 5.5.0, un destino autorizado y un host y puerto de proxy. El repositorio actual de OkHttp enumera Java 8+ y Android 5.0+ como líneas de base compatibles, mientras que la página del artefacto de OkHttp en Maven Central proporciona metadatos de lanzamiento actuales.
Hay tres métodos prácticos de proxy en OkHttp: adjuntar un proxy explícito, responder a un desafío de proxy autenticado o rotar entre un grupo de clientes reutilizables. Cada ejemplo en Java a continuación fue compilado y ejecutado con OkHttp 5.5.0 contra un proxy local construido a propósito. Las pruebas confirmaron solicitudes HTTP de forma absoluta, un reintento de autenticación 407 exitoso y un enrutamiento determinístico a través de dos endpoints.
Método 1: Configurar un Proxy Explícito
Utilice un proxy explícito cuando cada solicitud de un cliente deba seguir la misma ruta. Cree un Proxy en Java, adjúntelo al constructor y limite tanto el tiempo de conexión como el tiempo total de llamada.
La prueba ejecutada devolvió HTTP 200 y mostró GET http://example.test/ip HTTP/1.1 en el proxy local. Para un destino HTTPS, OkHttp primero solicita a un proxy HTTP que cree un túnel con CONNECT y luego realiza TLS con el destino a través de ese túnel. No desactive la verificación de certificados para resolver un problema de enrutamiento o CA local.
Método 2: Agregar Autenticación de Nombre de Usuario y Contraseña del Proxy
Utilice proxyAuthenticator cuando el endpoint requiera autenticación básica de proxy. El autenticador se ejecuta después de que el proxy devuelve 407 Proxy Authentication Required; debe agregar credenciales una vez y detenerse si la misma solicitud ya tiene el encabezado.
El proxy de verificación devolvió deliberadamente 407 en la primera solicitud. OkHttp llamó al autenticador, reintentó una vez y el proxy confirmó que la segunda solicitud contenía una autorización válida. La protección del bucle es importante: devolver otra solicitud después de que las credenciales ya han fallado puede repetir desafíos hasta que se alcance el límite de seguimiento de OkHttp.
Las credenciales del proxy son diferentes de las credenciales de destino. Usa proxyAuthenticator para el desafío 407 del proxy y authenticator para el desafío 401 del servidor de origen. Nunca envíes Proxy-Authorization como un encabezado de destino ordinario.
Método 3: Rotar un grupo de puntos finales del proxy
Usa clientes preconstruidos cuando la aplicación debe elegir entre varios puntos finales distintos. Este ejemplo mantiene un cliente reutilizable por punto final y los selecciona en orden rotativo. La rotación del lado del proveedor a través de una puerta de enlace suele ser más simple; la rotación del lado del cliente es útil cuando la identidad y la salud del punto final deben seguir siendo visibles para la aplicación.
importjava.net.InetSocketAddress;importjava.net.Proxy;importjava.time.Duration;importjava.util.ArrayList;importjava.util.List;importjava.util.concurrent.atomic.AtomicInteger;importokhttp3.OkHttpClient;importokhttp3.Request;importokhttp3.Response;publicfinalclassProxyRotatorio{privatefinalList<OkHttpClient> clients;privatefinalAtomicInteger next =newAtomicInteger();privateProxyRotatorio(List<InetSocketAddress> endpoints){this.clients =newArrayList<>();for(InetSocketAddress endpoint : endpoints){Proxy proxy =newProxy(Proxy.Type.HTTP, endpoint); clients.add(newOkHttpClient.Builder().proxy(proxy).connectTimeout(Duration.ofSeconds(5)).callTimeout(Duration.ofSeconds(15)).build());}}privateOkHttpClientnextClient(){return clients.get(Math.floorMod(next.getAndIncrement(), clients.size()));}publicstaticvoidmain(String[] args)throwsException{String proxyHost =requireEnv("PROXY_HOST");String[] ports =requireEnv("PROXY_PORTS").split(",");String targetUrl =System.getenv().getOrDefault("TARGET_URL","https://httpbin.org/ip");List<InetSocketAddress> endpoints =newArrayList<>();for(String port : ports){ endpoints.add(newInetSocketAddress(proxyHost,Integer.parseInt(port.trim())));}if(endpoints.size()<2){thrownewIllegalArgumentException("Se requieren al menos dos puertos de proxy");}ProxyRotatorio pool =newProxyRotatorio(endpoints);Request request =newRequest.Builder().url(targetUrl).build();for(int i =0; i < endpoints.size(); i++){try(Response response = pool.nextClient().newCall(request).execute()){if(!response.isSuccessful()){
thrownewIllegalStateException("Estado inesperado: "+ response.code());}System.out.println(response.body().string());}}}privatestaticStringrequireEnv(String name){String value =System.getenv(name);if(value ==null|| value.isBlank()){thrownewIllegalArgumentException(name +" es requerido");}return value;}}
La ejecución en vivo reportó puertos proxy 18180 y 18182 en ese orden. En producción, almacene un ID de punto final no secreto junto a cada cliente, registre el éxito y la latencia por ID, y ponga en cuarentena temporalmente los puntos finales que fallan repetidamente. No imprima la URL del punto final si incluye credenciales.
Proxy Explícito vs ProxySelector
Utilice .proxy(proxy) para una política de cliente fija y proxySelector para un enrutamiento consciente del destino. Un selector puede devolver diferentes valores de Proxy de Java para diferentes URI y recibir notificaciones de connectFailed. La documentación de java.net.Proxy define representaciones de proxy HTTP, SOCKS y directas.
No configure ambos y espere que se mezclen. OkHttp consulta a proxySelector solo cuando el proxy explícito es nulo. Si un servicio debe eludir el proxy para hosts internos, ya sea cree un cliente directo o implemente un selector cuyo método select(URI) devuelva Proxy.NO_PROXY para esos hosts. Esto es más claro que confiar en una configuración a nivel de máquina inadvertida.
ProxySelector puede proporcionar rutas de respaldo, pero no es automáticamente un motor de rotación de solicitud por solicitud. La reutilización de conexión y la recuperación de ruta afectan qué ruta se utiliza. Utilice un gateway de proveedor para la rotación a nivel de red o un grupo de clientes deliberado cuando cada llamada de aplicación deba tener una elección de punto final auditable.
Cómo verificar un proxy OkHttp
Verifique un proxy OkHttp comprobando la ruta y la respuesta juntas. Envíe una solicitud directa y una solicitud a través del proxy a un punto final de reflexión IP autorizado, luego compare las direcciones de origen informadas. Un estado exitoso por sí solo no prueba que el proxy manejara la llamada.
Valide el estado de la respuesta, el tipo de contenido y los campos del cuerpo requeridos. Un intermediario o destino puede devolver una página de bloqueo HTML con HTTP 200. El glosario de solicitudes HTTP es una referencia útil para el límite de solicitud/respuesta.
A continuación, pruebe los modos de falla. Utilice un puerto no válido para confirmar el tiempo de espera de conexión, credenciales no válidas para confirmar un resultado 407 limitado, y un objetivo autorizado lento para confirmar el tiempo de espera de la llamada. Los escuchadores de eventos de OkHttp pueden registrar el DNS, la conexión, TLS y el tiempo de respuesta sin exponer secretos. Para la vista de la misma ruta en otro idioma, la guía de proxy Guzzle ofrece un útil chequeo cruzado.
Elegir una ruta Nstproxy para OkHttp
Los Proxies Residenciales Prime de Nstproxy son adecuados para aplicaciones OkHttp que necesitan una ruta residencial autenticada con controles de sesión y ubicación expuestos por el flujo de trabajo del producto actual. Java solo necesita un host estándar, puerto, nombre de usuario y contraseña; no se requiere un SDK específico del proveedor para la conexión del proxy en sí. Revise los modelos de facturación Residenciales Prime actuales y pruebe el objetivo exacto antes de seleccionar una ruta para producción.
Prefiera una puerta de enlace cuando el proveedor maneje la rotación. Esto mantiene la configuración de OkHttp pequeña y preserva la reutilización del cliente.
Utilice un comportamiento persistente para sesiones de múltiples solicitudes. Mantenga las llamadas relacionadas en una ruta para la ventana de sesión requerida.
Utilice un grupo de aplicaciones solo cuando el control a nivel de punto final sea necesario. Agregue seguimiento de salud, reintentos limitados e identificadores de ruta no secretos antes de aumentar la concurrencia.
Una aplicación de Android puede usar las mismas API de generador OkHttp, pero enviar credenciales proxy de larga duración dentro de un binario móvil es arriesgado. Prefiera credenciales de corta duración o una capa de red del lado del servidor cuando sea posible. Consulte la opinión sobre servidores proxy para Android para alternativas a nivel de plataforma.
Errores comunes de proxy OkHttp y soluciones
Los errores de proxy de OkHttp son más fáciles de solucionar cuando la capa de conexión se separa de la respuesta del destino.
Síntoma
Causa probable
Solución práctica
407 Proxy Authentication Required
Credenciales proxy faltantes o rechazadas
Confirme el nombre de usuario / contraseña, utilice proxyAuthenticator y deténgase después de que el encabezado ya se haya intentado.
Tiempo de espera de conexión o ConnectException
Host/puerto incorrecto, ruta inalcanzable o política de red
Verifique el punto final y mantenga un connectTimeout corto; no intente indefinidamente.
Fallo en el apretón de manos TLS
Configuración de confianza inválida, intercepción o desajuste de nombre de host
Repare la CA o ruta; mantenga habilitada la verificación de certificado y nombre de host.
El proxy parece no utilizarse
Proxy.NO_PROXY explícito, política de selector o un cliente diferente manejó la llamada
Registra un ID de cliente/ruta no secreto y compara los resultados de IP de salida directa versus bajo proxy.
403 o 429
El destino rechazó o limitó la solicitud
Reduce la tasa de solicitudes, confirma la autorización y sigue las reglas del destino.
Intentos repetidos de 407
El autenticador devuelve una nueva solicitud después de que las credenciales ya han fallado
Retorna null cuando Proxy-Authorization ya está presente.
Reintenta solo fallos transitorios y utiliza retroceso. Para solicitudes que cambian el estado, añade protección de idempotencia antes de reintentar. Un nuevo IP de proxy no puede convertir una solicitud inválida en una válida.
Conclusión
La configuración de proxy de OkHttp más limpia es un Proxy explícito para una ruta estable, proxyAuthenticator para un desafío 407, o un pequeño conjunto de clientes reutilizables para la rotación de puntos finales auditable. Mantén las credenciales fuera de la fuente, utiliza tiempos de espera limitados, preserva la verificación de TLS y confirma tanto la ruta de salida como la semántica de la respuesta.
Comienza con un destino autorizado y un punto final. Registra una línea base exitosa, luego añade rotación o lógica de selector solo cuando la aplicación puede identificar rutas que fallan y tomar una decisión de retroceso deliberada.
Experimenta Nstproxy — Comienza tu Prueba Gratuita Hoy
Crea un punto final autenticado, conecta un cliente OkHttp reutilizable y verifica la ruta observada antes de escalar.
Crea un java.net.Proxy con el tipo de proxy y InetSocketAddress, luego pásalo a new OkHttpClient.Builder().proxy(proxy).build(). Reutiliza el cliente resultante para llamadas que compartan esa ruta.
P: ¿Cómo agrego un nombre de usuario y contraseña de proxy en OkHttp?
Configura proxyAuthenticator y devuelve una solicitud de seguimiento que contenga Proxy-Authorization, comúnmente construida con Credentials.basic(user, password). Retorna null si ese encabezado ya está presente para evitar intentos fallidos repetidos.
P: ¿OkHttp soporta HTTPS a través de un proxy HTTP?
Sí. OkHttp utiliza el método HTTP CONNECT para crear un túnel a través del proxy, luego realiza TLS con el destino. La ruta del proxy no justifica desactivar la verificación de certificados o nombres de host.
P: ¿Un proxy explícito de OkHttp anula ProxySelector?
Sí. La configuración de proxy explícita de OkHttp tiene prioridad; proxySelector se consulta solo cuando el proxy explícito es nulo. Usa Proxy.NO_PROXY cuando un cliente debe conectarse siempre directamente.
P: ¿Debería crear un nuevo OkHttpClient para cada solicitud rotativa?
No. Construye un conjunto limitado de clientes reutilizables—uno por punto final o política de enrutamiento—y selecciona entre ellos. Esto preserva los grupos de conexión y evita crear repetidamente recursos de ejecutor.
Ivy Lin
Aug. 20th 2026
110M+ IP reales con 99.9% de acceso exitoso
Respuesta media ultrarrapida ~0.5s para tareas de alta concurrencia
Desde solo $0.1/GB
Acceso inmediato a pools premium de proxies residenciales, datacenter, IPv6 e ISP.
