Como lidar com CAPTCHA nos fluxos de trabalho web do Kimi Code CLI

TL;DR

• O FetchURL do Kimi Code CLI pode recuperar conteúdo da web, mas um fluxo de trabalho ainda precisa rejeitar um erro 403, saída vazia, uma página de desafio ou conteúdo que não contenha evidências esperadas antes de considerar a etapa como bem-sucedida.
• Mantenha a recuperação de desafios fora do raciocínio livre do modelo: autorize o alvo primeiro, classifique o resultado da recuperação, permita no máximo uma tentativa de recuperação, recupere novamente e verifique o conteúdo esperado.
• O Kimi Code pode descobrir ferramentas de um servidor MCP genérico. O CapSolver não exige uma integração nativa declarada do Kimi; seu servidor MCP documentado pode fornecer uma capacidade controlada de CAPTCHA através da fronteira padrão de ferramentas.
• Limite o caminho do Agente às capacidades reCAPTCHA v2, reCAPTCHA v3 (incluindo Enterprise) e Cloudflare Turnstile documentadas atualmente, e confirme o suporte em tempo de execução antes de iniciar o trabalho.
• Pare em caso de autorização ausente, desafio não suportado, erro terminal da ferramenta, orçamento de tentativas esgotado ou verificação pós-recuperação falha. Direcione esses casos para um humano em vez de loopar.
• A configuração e o fixture da máquina de estados neste guia foram testados localmente. Nenhum CAPTCHA real foi resolvido, pois um credencial real do CapSolver e um fixture de desafio autorizado são pré-requisitos de implantação.

Introdução: Trate a recuperação da web como uma etapa de produção de evidência

O CLI do Kimi Code pode ler arquivos, executar comandos de shell, buscar páginas da web e usar ferramentas MCP. Isso o torna útil para tarefas de codificação que dependem de conteúdo da web público ou autorizado pelo usuário. O caso difícil nem sempre é uma falha de rede difícil. Uma solicitação pode retornar um erro contendo 403, um corpo quase vazio ou uma página de desafio que parece conteúdo para um agente validado de forma solta.

Um fluxo confiável deve classificar esse resultado antes que ele entre no contexto do agente. Quando a falha for um CAPTCHA suportado em um ambiente autorizado, o CapSolver pode estar atrás de uma fronteira MCP como uma capacidade de recuperação controlada. Ele não deve se tornar um mecanismo de repetição ilimitada ou substituto de permissão.

O que significa o tratamento de CAPTCHA no CLI do Kimi Code?

O tratamento de CAPTCHA no CLI do Kimi Code significa detectar que a recuperação da web não produziu a evidência esperada, rotear um desafio autorizado e suportado para uma ferramenta controlada, e verificar novamente a página. Não significa tratar cada falha de recuperação como um CAPTCHA ou permitir que o modelo repita chamadas de ferramentas até que algo mude.

O repositório oficial do Kimi Code https://github.com/MoonshotAI/kimi-code lista a busca de páginas da web, MCP, Skills e Plugins entre as capacidades do CLI. Sua referência de ferramentas integradas define FetchURL com uma entrada url e conteúdo da página como saída. HTML é convertido em texto do corpo, enquanto texto simples e Markdown são passados diretamente.

Esse contrato é deliberadamente pequeno. Ele não promete que o texto retornado seja o documento desejado, nem define uma resposta estruturada { status, text }. Se um wrapper de host expuser status HTTP ou erros de transporte, normalize-os em um adaptador. Em seguida, valide tanto a evidência de transporte quanto a semântica do conteúdo antes que o agente consuma o resultado.

Essa separação dá ao modelo um espaço de decisão estreito. Ele pode solicitar uma recuperação apenas após o validador ter produzido um estado recuperável; o controlador, não o modelo, impõe o orçamento.

Pré-requisitos e limites de confiança

Use esse padrão apenas para páginas e ambientes de teste que você possua ou esteja autorizado a automatizar. Acesso técnico não concede permissão para ler dados privados, restritos, sensíveis ou não autorizados. Revise os termos do alvo, políticas aplicáveis, regras de tratamento de dados e limites de taxa antes de habilitar qualquer caminho de recuperação.

Você precisa de:

• CLI do Kimi Code com um projeto confiável e permissão para carregar o servidor MCP desejado.
• Python 3.10 ou mais recente para o pacote atual capsolver-core.
• Os pacotes oficiais capsolver-core e capsolver-mcp do guia de serviço MCP da CapSolver.
• Uma chave de API do CapSolver armazenada no ambiente do processo ou em um gerenciador de segredos, nunca comprometida no .kimi-code/mcp.json.
• Um fixture de página controlada ou fluxo de trabalho explicitamente autorizado para testes de integração final.
• Regras de conteúdo esperado, como um título de página, cabeçalho estável ou campo JSON necessário, que distinguem o resultado desejado de um desafio ou página de shell.

O guia oficial de configuração MCP do Kimi suporta arquivos mcp.json de nível de usuário e projeto. Configurações de projeto exigem confiança, e chamadas de ferramenta MCP individuais podem exigir aprovação. Mantenha essa fronteira de aprovação: evite regras com wildcards amplos, revise o comando do servidor e permita apenas as ferramentas que o fluxo de trabalho precisa.

Observação sobre compatibilidade de dependências do ambiente de validação

A validação isolada deste artigo usou Kimi Code CLI 0.38.0, capsolver-core 0.1.0 e capsolver-mcp 0.1.0 no Python 3.12. Em 26 de agosto de 2026, uma instalação sem restrições selecionou MCP 2.1.1, enquanto o pacote atual do CapSolver MCP importou o módulo MCP 1.x FastMCP. Fixar mcp<2 produziu MCP 1.29.1 e restaurou o comando documentado neste fixture isolado.

Trate esse fix como uma solução de compatibilidade datada, não como uma exigência permanente. Verifique os pacotes oficiais atuais e remova-o quando seus limites de dependência suportarem MCP 2.x.

Configure o CapSolver MCP para o CLI do Kimi Code

O CapSolver pode ser conectado por meio da configuração padrão MCP do Kimi Code; esta é uma conexão MCP genérica, não uma reivindicação de integração nativa do Kimi. Crie um ambiente isolado e instale os pacotes 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

Defina CAPSOLVER_API_KEY por meio do seu armazenamento de segredos de CI ou do ambiente do processo local. Em seguida, use um .kimi-code/mcp.json de projeto, 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 o Kimi a partir de um processo onde seu gerenciador de segredos já forneceu CAPSOLVER_API_KEY; o processo filho MCP herda esse ambiente. O Kimi também suporta um objeto env para um servidor MCP, mas escrever uma chave real em um arquivo de projeto corre o risco de exposição no controle de versão. Use uma configuração de tempo de execução protegida se sua implantação não puder herdar segredos do processo.

O Kimi prefixa ferramentas descobertas com o nome do servidor, então o modelo vê nomes como mcp__capsolver__detect_captchas. A troca local para este guia confirmou a descoberta de todas as cinco ferramentas documentadas. Ele parou intencionalmente antes de chamar uma porque nenhuma credencial real ou fixture de desafio autorizado foi fornecida.

Antes que um fluxo de trabalho comece, chame get_supported_captchas ou impeça uma lista de permissão versão em seu controlador. Para este fluxo de trabalho do Agente, mantenha a lista de permissão limitada às capacidades reCAPTCHA v2, reCAPTCHA v3 e sua variante Enterprise, e Cloudflare Turnstile. Se a detecção produzir algo diferente, pare para revisão humana.

Resgate seu código promocional da CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta da CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel da CapSolver

Detecte 403, Conteúdo Vazio e Sucesso Falso de Página de Desafio

Valide um resultado de recuperação antes que ele chegue à memória de recuperação, resumidor ou decisão de codificação. Um classificador confiável verifica vários sinais independentes:

1. Falha de transporte: um adaptador de host relata 403 ou outro status não bem-sucedido.
2. Saída fina: o texto retornado está vazio ou é muito curto para conter o documento esperado.
3. Semântica de desafio: o corpo contém marcadores de desafio estáveis em vez do conteúdo solicitado.
4. Evidência ausente: a resposta parece plausível, mas falta cabeçalhos, campos ou identificadores necessários.

O seguinte JavaScript testado é um exemplo de nível de adaptador. Seu objeto { status, text } é um contrato de aplicativo normalizado, não o esquema bruto 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 os limiares e marcadores contra um fixture proprietário, não contra páginas de terceiros arbitrários. Uma correspondência de marcador é evidência para inspeção, não permissão para prosseguir. Registre a origem da URL, classe de status, hash de conteúdo, regra correspondida e ID de rastreamento, mas redija dados de página e credenciais dos logs.

Para diagnóstico mais amplo, o guia de erro CAPTCHA do MCP explica como separar falhas de transporte, detecção, resolução e injeção. O limite MCP do Kimi deve receber essa classificação estruturada em vez de uma instrução não limitada em linguagem natural, como "continue tentando."

Execute uma única recuperação controlada e verifique o resultado

Um controlador limitado deve ter apenas quatro resultados terminais: aceito, recuperado e verificado, interrompido ou necessário humano. Ele nunca deve inferir sucesso apenas porque uma chamada MCP retornou sem lançar uma exceção.

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,
  };
}

O adaptador recoverThroughMcp é onde uma camada de orquestração aprovada invoca a ferramenta documentada do CapSolver. Sua entrada deve incluir a URL autorizada, a evidência de desafio detectada e o número de tentativa. Sua saída deve normalizar sucesso, código de erro redigido e reutilizabilidade. Mantenha tarefas específicas de serviço dentro desse adaptador e as valide contra os documentos oficiais atuais em vez de pedir ao modelo para inventar campos.

A segunda busca do controlador é obrigatória. Valide-a com os mesmos termos esperados e regras de conteúdo da primeira solicitação. Um token ou resposta de ferramenta é um resultado intermediário; o conteúdo da página é a evidência de aceitação.

Regras práticas de parada

Pare sem chamada de ferramenta quando a autorização estiver ausente, a URL sair do conjunto de origens aprovadas ou o validador retornar um erro de transporte terminal. PARE após a chamada da ferramenta quando o desafio for não suportado, o serviço reportar um erro não reutilizável, o orçamento de tempo expirar ou a verificação de saldo falhar. Requer humano após a única tentativa de recuperação se a busca de verificação ainda estiver fina, desafiada ou sem conteúdo esperado.

Essas regras também previnem a poluição do contexto. Apenas conteúdo de página aceito deve entrar na história da tarefa do Kimi ou armazenamento de recuperação subsequente. Mantenha corpos falhos em um registro de evidência quarentenado com retenção curta e redação.

Observabilidade para fluxos de trabalho da web do Kimi Code

A observabilidade deve explicar por que uma etapa mudou de estado sem expor segredos ou corpos completos de páginas. Emita um evento estruturado por transição:

{
"traceId": "retrieval-7f2c",
  "stage": "verification_fetch",
  "origin": "authorized.example",
  "classification": "expected_content_missing",
  "recoveryAttempts": 1,
  "finalState": "human_required"
}

Campos úteis incluem a classe de status normalizada, regra do validador, comprimento do conteúdo, hash do conteúdo redigido, nome da ferramenta MCP, tempo decorrido, número de tentativas e estado final. Nunca registre a chave da API, um token de desafio completo, dados de página sensíveis ou configuração MCP com segredos.

Defina alertas sobre a taxa de requisição humana, taxa de falha na verificação e tempo limite da ferramenta. Um aumento na taxa de 403 pode indicar uma política de acesso alterada, um adaptador de busca quebrado ou um desafio; não é evidência suficiente por si só para classificar a causa. Para contexto geral do protocolo, consulte o que MCP significa em sistemas de IA.

Uso Responsável e Guardrails Operacionais

Use este design para automação pública, proprietária ou explicitamente autorizada. Respeite os termos, controles de acesso, diretrizes robots, limites de taxa, minimização de dados e requisitos de retenção. Não use uma ferramenta CAPTCHA para acessar conteúdo privado ou restrito ou para continuar após um site ter claramente retirado a permissão.

Mantenha uma lista de permissões, um proprietário para cada registro de autorização, uma data de expiração e um interruptor de desligamento. Aplicar taxas baixas de solicitação e cacheie conteúdo público aceito quando permitido. Requerir uma nova aprovação quando o fluxo de trabalho mudar de origem, propósito, categoria de dados ou frequência de execução.

A camada MCP deve usar o conjunto mínimo de ferramentas e aprovações de menor privilégio. O guia da CapSolver para agentes de IA (https://docs.capsolver.com/en/guide/ai/capsolver-for-ai-agents/) descreve o fluxo de trabalho do Agente suportado; seu controlador permanece responsável por permissões, limites de tentativas, validação de saída e parada.

Conclusão: Tornar a Recuperação Mensurável e Limitada

O tratamento de CAPTCHA confiável para a CLI Kimi começa rejeitando o sucesso falso. Normalize a evidência do FetchURL, teste o conteúdo esperado, autorize o alvo, permita uma recuperação suportada e faça a busca e verificação novamente. Qualquer coisa ambígua ou ainda desafiada deve parar para revisão humana.

A fronteira MCP genérica mantém o fluxo de trabalho da web do Kimi separado dos detalhes do serviço, enquanto a máquina de estados controla as repetições e registra a evidência. Se o seu fluxo de trabalho de agente autorizado precisar de uma camada de recuperação de CAPTCHA documentada, avalie o CapSolver com um fixture proprietário antes de ativá-lo em produção.

Perguntas Frequentes

P: O Kimi Code CLI possui uma integração nativa com o CapSolver?

Não. Este guia usa a configuração MCP genérica documentada do Kimi Code para conectar o servidor MCP do CapSolver; ele não afirma uma integração nativa ou parceria oficial.

P: O FetchURL retorna um objeto de status HTTP e corpo?

Não de acordo com o contrato documentado da ferramenta integrada. O FetchURL recebe uma URL e retorna conteúdo da página; um adaptador de host deve normalizar erros de transporte disponíveis ou informações de status antes de aplicar o classificador de exemplo.

P: Todo 403 do FetchURL do Kimi Code deve disparar recuperação de CAPTCHA?

Não. Um 403 pode ter vários motivos, incluindo falha em política ou autorização. Classifique a resposta, confirme a permissão, detecte um desafio suportado e pare quando a causa for ambígua.

P: Quais tipos de desafio pertencem a este fluxo de trabalho de Agente?

Mantenha a lista de permissões apenas com as capacidades reCAPTCHA v2, reCAPTCHA v3 incluindo Enterprise e Cloudflare Turnstile documentadas atualmente. Confirme o suporte em tempo de execução e pare em qualquer tipo não reconhecido.

P: Quantas tentativas de recuperação de CAPTCHA um agente deve fazer?

Este padrão permite uma tentativa de recuperação seguida por uma verificação de busca. Se a verificação falhar, o fluxo de trabalho para e solicita revisão humana em vez de repetir a chamada da ferramenta.

P: O modelo pode decidir que a recuperação foi bem-sucedida com base apenas na resposta MCP?

Não. Trate a resposta MCP como um resultado intermediário; repita a busca autorizada e valide a evidência da página esperada antes de aceitar o conteúdo.