Cómo manejar CAPTCHA en los flujos de trabajo web de Kimi Code CLI

TL;DR

• La herramienta FetchURL de Kimi Code CLI puede recuperar contenido web, pero un flujo de trabajo aún debe rechazar un error 403, salida vacía, una página de desafío o contenido que carezca de evidencia esperada antes de considerar el paso como exitoso.
• Mantén la recuperación de desafíos fuera del razonamiento libre del modelo: autoriza primero el objetivo, clasifica el resultado de la recuperación, permite como máximo un intento de recuperación, vuelve a recuperar y verifica el contenido esperado.
• Kimi Code puede descubrir herramientas desde un servidor MCP genérico. CapSolver no requiere una integración nativa confirmada de Kimi; su servidor MCP documentado puede proporcionar una capacidad de CAPTCHA controlada a través del límite estándar de herramientas.
• Limita el camino del Agente a las capacidades de reCAPTCHA v2, reCAPTCHA v3 (incluida la versión Enterprise) y Cloudflare Turnstile documentadas actualmente, y confirma el soporte en tiempo de ejecución antes de comenzar el trabajo.
• Detente ante la falta de autorización, un desafío no soportado, un error terminal de herramienta, un presupuesto de intentos agotado o una verificación fallida después de la recuperación. Envié esos casos a un humano en lugar de buclear.
• La configuración y el fixture de máquina de estados en este guía fueron probados localmente. No se resolvió ninguna CAPTCHA en vivo porque un credencial real de CapSolver y un fixture de desafío autorizado son requisitos previos de implementación.

Introducción: Tratar la recuperación de web como un paso de producción de evidencia

La CLI de Kimi Code puede leer archivos, ejecutar comandos de shell, recuperar páginas web y usar herramientas MCP. Eso lo hace útil para tareas de codificación que dependen de contenido web público o autorizado por el usuario. El caso difícil no siempre es un fallo de red difícil. Una solicitud puede devolver un error que contiene 403, un cuerpo casi vacío o una página de desafío que parece contenido a un agente con validación suelta.

Un flujo de trabajo confiable debe clasificar ese resultado antes de que entre en el contexto del agente. Cuando el fallo es una CAPTCHA soportada en un entorno autorizado, CapSolver puede estar detrás de un límite MCP como una capacidad de recuperación controlada. No debe convertirse en un mecanismo de repetición ilimitada ni en un sustituto de la autorización.

¿Qué significa el manejo de CAPTCHA en la CLI de Kimi Code?

El manejo de CAPTCHA en la CLI de Kimi Code significa detectar que la recuperación de web no produjo la evidencia esperada, enrutar un desafío autorizado y soportado a una herramienta controlada, y luego validar nuevamente la página. No significa tratar cada fallo de recuperación como una CAPTCHA o permitir que el modelo repita llamadas a herramientas hasta que algo cambie.

El repositorio oficial de Kimi Code enumera la recuperación de páginas web, MCP, Skills y Plugins entre las capacidades de la CLI. Su referencia de herramientas integradas define FetchURL con una entrada url y el contenido de la página como salida. El HTML se convierte en texto de cuerpo, mientras que el texto plano y el Markdown se pasan directamente.

Este contrato es deliberadamente pequeño. No promete que el texto devuelto sea el documento deseado, ni define una respuesta estructurada { status, text }. Si un envoltorio de host expone estados HTTP o errores de transporte, normalícelos en un adaptador. Luego valide tanto la evidencia de transporte como la semántica del contenido antes de que el agente consuma el resultado.

Esta separación da al modelo un espacio de decisión estrecho. Puede solicitar una recuperación solo después de que el validador haya producido un estado recuperable; el controlador, no el modelo, impone el presupuesto.

Requisitos previos y límites de confianza

Use este patrón solo para páginas y entornos de prueba que posea o esté autorizado a automatizar. El acceso técnico no otorga permiso para leer datos privados, restringidos, sensibles o no autorizados. Revise los términos del objetivo, políticas aplicables, reglas de manejo de datos y límites de frecuencia antes de habilitar cualquier camino de recuperación.

Necesita:

• Kimi Code CLI con un proyecto confiable y permiso para cargar el servidor MCP deseado.
• Python 3.10 o superior para el paquete actual capsolver-core.
• Los paquetes oficiales capsolver-core y capsolver-mcp desde la guía del servicio MCP de CapSolver https://docs.capsolver.com/en/guide/ai/mcp-service/.
• Una clave de API de CapSolver almacenada en el entorno del proceso o un gestor de secretos, nunca comprometida en .kimi-code/mcp.json.
• Un fixture de página controlada o un flujo de trabajo autorizado explícitamente para pruebas de integración final.
• Reglas de contenido esperado, como un título de página, un encabezado estable o un campo JSON requerido, que distingan el resultado deseado de una página de desafío o página de shell.

La guía oficial de configuración MCP de Kimi admite archivos mcp.json a nivel de usuario y proyecto. Las configuraciones de proyecto requieren confianza, y las llamadas a herramientas MCP individuales pueden requerir aprobación. Mantenga ese límite de aprobación: evite reglas comodín amplias, revise el comando del servidor y permita solo las herramientas que necesita el flujo de trabajo.

Una nota sobre compatibilidad de dependencias del entorno de validación

La validación aislada de este artículo usó Kimi Code CLI 0.38.0, capsolver-core 0.1.0 y capsolver-mcp 0.1.0 en Python 3.12. El 26 de agosto de 2026, una instalación no restringida seleccionó MCP 2.1.1, mientras que el paquete actual de CapSolver MCP importó el módulo MCP 1.x FastMCP. Fijar mcp<2 produjo MCP 1.29.1 y restauró el comando documentado en este fixture aislado.

Trate esa fijación como un trabajo de compatibilidad con fecha, no como un requisito permanente. Revise los paquetes oficiales actuales y elimínelo cuando sus límites de dependencia apoyen MCP 2.x.

Configurar MCP de CapSolver para Kimi Code CLI

CapSolver puede conectarse a través de la configuración estándar MCP de Kimi; esta es una conexión MCP genérica, no una afirmación de una integración nativa de Kimi. Cree un entorno aislado e instale los paquetes documentados:

python3.12 -m venv .venv-capsolver-mcp
.venv-capsolver-mcp/bin/python -m pip install \
  "mcp<2" \
  "capsolver-core @ git+https://github.com/capsolver/capsolver-core-python.git" \
  "capsolver-mcp @ git+https://github.com/capsolver/capsolver-mcp.git"
.venv-capsolver-mcp/bin/capsolver-mcp --help

Establezca CAPSOLVER_API_KEY a través de su almacén de secretos de CI o entorno de proceso local. Luego use un archivo .kimi-code/mcp.json del proyecto como:

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/.venv-capsolver-mcp/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "startupTimeoutMs": 10000,
      "toolTimeoutMs": 30000,
      "enabledTools": [
        "detect_captchas",
        "solve_captcha",
        "solve_on_page",
        "get_balance",
        "get_supported_captchas"
      ]
    }
  }
}

Inicie Kimi desde un proceso donde su gestor de secretos ya haya proporcionado CAPSOLVER_API_KEY; el proceso secundario MCP hereda ese entorno. Kimi también admite un objeto env para un servidor MCP, pero escribir una clave real en un archivo de proyecto conlleva el riesgo de exposición en el control de código fuente. Use una configuración de tiempo de ejecución protegida si su implementación no puede heredar secretos de proceso.

Kimi prefiere herramientas descubiertas con el nombre del servidor, por lo que el modelo ve nombres como mcp__capsolver__detect_captchas. La conexión local para este guía confirmó el descubrimiento de todas las cinco herramientas documentadas. Detuvo intencionalmente antes de llamar a una porque no se suministró una credencial real ni un fixture de desafío autorizado.

Antes de que comience un flujo de trabajo, llame a get_supported_captchas o imponga una lista de permitidos con versión en su controlador. Para este flujo de trabajo del Agente, mantenga la lista de permitidos en reCAPTCHA v2, reCAPTCHA v3 y su variante Enterprise, y Cloudflare Turnstile. Si la detección produce algo más, deténgase para revisión humana.

Redeem Your CapSolver Bonus Code

¡Aumente su presupuesto de automatización instantáneamente!
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional de bonificación en cada recarga — sin límites.
Redémetelo ahora en su Panel de CapSolver

Detectar 403, Contenido Vacío y Éxito Falso de Página de Desafío

Valide un resultado de recuperación antes de que llegue a la memoria de recuperación, resumidor o decisión de codificación. Un clasificador confiable comprueba varios señales independientes:

1. Fallo de transporte: un adaptador de host informa 403 u otro estado no exitoso.
2. Salida delgada: el texto devuelto está vacío o es demasiado corto para contener el documento esperado.
3. Semántica de desafío: el cuerpo contiene marcadores de desafío estables en lugar del contenido solicitado.
4. Falta de evidencia: la respuesta parece plausible pero carece de encabezados, campos o identificadores requeridos.

El siguiente JavaScript probado es un ejemplo a nivel de adaptador. Su objeto { status, text } es un contrato de aplicación normalizado, no el esquema crudo de FetchURL:

const CHALLENGE_MARKERS = [
  /verify you are human/i,
  /captcha/i,
  /cf-chl-/i,
  /g-recaptcha/i,
  /cf-turnstile/i,
];

export function classifyFetchResult(result, expectedTerms = []) {
  const status = Number(result?.status ?? 0);
  const text = String(result?.text ?? "").trim();

  if (status === 403) {
    return { kind: "recoverable", reason: "http_403", status };
  }
  if (status < 200 || status >= 400) {
    return { kind: "terminal", reason: "unexpected_http_status", status };
  }
  if (text.length < 80) {
    return { kind: "recoverable", reason: "empty_or_thin_content", status };
  }
  if (CHALLENGE_MARKERS.some((marker) => marker.test(text))) {
    return { kind: "recoverable", reason: "challenge_page", status };
  }

  const missingTerms = expectedTerms.filter(
    (term) => !text.toLowerCase().includes(term.toLowerCase()),
  );
  if (missingTerms.length > 0) {
    return { kind: "recoverable", reason: "expected_content_missing", status, missingTerms };
  }

  return { kind: "accepted", reason: "expected_content_present", status };
}

Ajuste los umbrales y marcadores contra un fixture propiedad, no contra páginas de terceros arbitrarias. Una coincidencia de marcador es evidencia para inspeccionar, no permiso para continuar. Registre la URL de origen, clase de estado, hash de contenido, regla coincidente y ID de traza, pero redacte datos de página y credenciales de los registros.

Para un diagnóstico más amplio, la guía de errores de CAPTCHA de MCP explica cómo separar fallos de transporte, detección, resolución e inyección. La frontera MCP de Kimi debe recibir esa clasificación estructurada en lugar de una instrucción no restringida de lenguaje natural como "siga intentando".

Ejecutar una sola recuperación controlada y verificar el resultado

Un controlador limitado debe tener solo cuatro resultados terminales: aceptado, recuperado y verificado, detenido o requerido humano. Nunca infiera éxito solo porque una llamada MCP devolvió sin lanzar una excepción.

export async function runBoundedRecovery({
  fetchPage,
  recoverThroughMcp,
  url,
  expectedTerms,
  authorized,
  maxRecoveryAttempts = 1,
}) {
  const evidence = [];
  let recoveryAttempts = 0;

  const first = await fetchPage(url);
  const firstCheck = classifyFetchResult(first, expectedTerms);
  evidence.push({ stage: "initial_fetch", check: firstCheck });

  if (firstCheck.kind === "accepted") {
    return { state: "accepted", recoveryAttempts, evidence };
  }
  if (firstCheck.kind === "terminal") {
    return { state: "stopped", stopReason: firstCheck.reason, recoveryAttempts, evidence };
  }
  if (!authorized) {
    return { state: "human_required", stopReason: "authorization_required", recoveryAttempts, evidence };
  }
  if (maxRecoveryAttempts < 1) {
    return { state: "stopped", stopReason: "recovery_budget_exhausted", recoveryAttempts, evidence };
  }

  recoveryAttempts += 1;
  const recovery = await recoverThroughMcp({
    url,
    reason: firstCheck.reason,
    attempt: recoveryAttempts,
  });
  evidence.push({ stage: "mcp_recovery", result: recovery });

  if (recovery?.status !== "recovered") {
    return {
      state: recovery?.retryable ? "human_required" : "stopped",
      stopReason: recovery?.errorCode ?? "recovery_failed",
      recoveryAttempts,
      evidence,
    };
  }

  const second = await fetchPage(url);
  const secondCheck = classifyFetchResult(second, expectedTerms);
  evidence.push({ stage: "verification_fetch", check: secondCheck });

  if (secondCheck.kind === "accepted") {
    return { state: "recovered_and_verified", recoveryAttempts, evidence };
  }

  return {
    state: "human_required",
    stopReason: "verification_failed_after_recovery",
    recoveryAttempts,
    evidence,
  };
}

El adaptador recoverThroughMcp es donde una capa de orquestación aprobada invoca la herramienta documentada de CapSolver. Su entrada debe incluir la URL autorizada, la evidencia de desafío detectada y el número de intento. Su salida debe normalizar el éxito, un código de error redactado y la reintentabilidad. Mantenga las entradas de tareas específicas del servicio dentro de ese adaptador y verifíquelas contra los documentos oficiales actuales en lugar de pedirle al modelo que invente campos.

La segunda recuperación del controlador es obligatoria. Valídela con los mismos términos esperados y reglas de contenido como la primera solicitud. Un token o respuesta de herramienta es un resultado intermedio; el contenido de la página es la evidencia de aceptación.

Reglas prácticas de detención

Deténgase sin una llamada a la herramienta cuando falte la autorización, la URL deje el conjunto de orígenes aprobados o el validador devuelva un error de transporte terminal. Deténgase después de la llamada a la herramienta cuando el desafío sea no soportado, el servicio informe un error no reintentable, el presupuesto de tiempo se agote o falle la verificación de balance. Requiera un humano después del único intento de recuperación si la recuperación de verificación sigue siendo delgada, desafiada o carece de contenido esperado.

Estas reglas también previenen la contaminación del contexto. Solo el contenido de página aceptado debe ingresar al historial de tareas de Kimi o al almacén de recuperación posterior. Mantenga los cuerpos fallidos en un registro de evidencia cuarentenado con retención corta y redacción.

Observabilidad para flujos de trabajo web de Kimi Code

La observabilidad debe explicar por qué un paso cambió de estado sin exponer secretos ni cuerpos completos de página. Emita un evento estructurado por transición:

{
"traceId": "recuperación-7f2c",
  "stage": "verificación_recuperación",
  "origin": "authorized.example",
  "classification": "contenido_esperado_faltante",
  "recoveryAttempts": 1,
  "finalState": "requiere_humano"
}

Campos útiles incluyen la clase de estado normalizada, la regla del validador, la longitud del contenido, el hash del contenido suprimido, el nombre de la herramienta MCP, el tiempo transcurrido, la cantidad de intentos y el estado final. Nunca registre la clave de la API, un token de desafío completo, datos de página sensibles o una configuración MCP que contenga secretos.

Establezca alertas sobre la tasa de requerimiento humano, la tasa de fallos en la verificación y los tiempos de espera de la herramienta. Un aumento en la tasa de 403 puede indicar un cambio en la política de acceso, un adaptador de recuperación defectuoso o un desafío; no es suficiente evidencia por sí sola para clasificar la causa. Para contexto general del protocolo, consulte qué significa MCP en sistemas de IA.

Uso responsable y controles operativos

Utilice este diseño para automatización pública, propiedad o explícitamente autorizada. Respete los términos, controles de acceso, directivas robots donde sea aplicable, límites de velocidad, minimización de datos y requisitos de retención. No utilice una herramienta CAPTCHA para acceder a contenido privado o restringido o para continuar después de que un sitio haya retirado claramente su permiso.

Mantenga una lista de permitidos, un propietario para cada registro de autorización, una fecha de expiración y un interruptor de emergencia. Aplicar tasas de solicitud bajas y cachear contenido público aceptado cuando sea permitido. Requerir una nueva aprobación cuando el flujo de trabajo cambie de origen, propósito, categoría de datos o frecuencia de ejecución.

La capa MCP debe usar el conjunto mínimo de herramientas y aprobaciones de menor privilegio. La guía de CapSolver para agentes de IA describe el flujo de trabajo soportado; su controlador sigue siendo responsable de la autorización, los límites de intentos, la validación de salida y la detención.

Conclusión: Haga que la recuperación sea medible y limitada

El manejo de CAPTCHA de CLI de Kimi confiable comienza rechazando éxitos falsos. Normalice la evidencia de FetchURL, pruebe el contenido esperado, autorice el objetivo, permita una recuperación soportada y vuelva a recuperar y verificar. Cualquier cosa ambigua o aún desafiada debe detenerse para revisión humana.

El límite MCP genérico mantiene separado el flujo de trabajo web de Kimi de los detalles del servicio, mientras que la máquina de estados controla los reintentos y registra la evidencia. Si su flujo de trabajo de agente autorizado necesita una capa de recuperación de CAPTCHA documentada, evalúe CapSolver con un fixture propiedad antes de habilitarlo en producción.

Preguntas frecuentes

P: ¿Tiene Kimi Code CLI una integración nativa con CapSolver?

No. Este guía utiliza la configuración MCP genérica documentada de Kimi para conectarse al servidor MCP de CapSolver; no afirma una integración nativa ni una asociación oficial.

P: ¿Devuelve FetchURL un objeto de estado HTTP y cuerpo?

No según el contrato documentado de la herramienta integrada. FetchURL toma una URL y devuelve contenido de página; un adaptador de host debe normalizar errores de transporte disponibles o información de estado antes de aplicar el clasificador de ejemplo.

P: ¿Debería desencadenar la recuperación de CAPTCHA cada vez que FetchURL devuelva un 403?

No. Un 403 puede tener varios causas, incluyendo fallo de política o autorización. Clasifique la respuesta, confirme el permiso, detecte un desafío soportado y deténgase cuando la causa sea ambigua.

P: ¿Qué tipos de desafíos pertenecen a este flujo de trabajo de agente?

Mantenga la lista de permitidos a las capacidades reCAPTCHA v2, reCAPTCHA v3 incluyendo Enterprise y Cloudflare Turnstile documentadas actualmente. Confirme el soporte en tiempo de ejecución y deténgase ante cualquier tipo no reconocido.

P: ¿Cuántos intentos de recuperación de CAPTCHA debe realizar un agente?

Este patrón permite un intento de recuperación seguido de una verificación de recuperación. Si la verificación falla, el flujo se detiene y solicita revisión humana en lugar de repetir la llamada a la herramienta.

P: ¿Puede el modelo decidir que la recuperación tuvo éxito a partir de la respuesta MCP sola?

No. Trate la respuesta MCP como un resultado intermedio; repita la recuperación autorizada y valide la evidencia de página esperada antes de aceptar el contenido.