Como corrigir CAPTCHAs dos motores no SearXNG

O que significa um erro de CAPTCHA no SearXNG

Os erros de CAPTCHA do SearXNG são gerados pelos motores que a sua instância consulta. O seu servidor pediu resultados a um motor, mas o motor respondeu com uma página de desafio em vez dos resultados. O SearXNG registou um erro nesse motor porque não havia conteúdo para analisar na resposta. A sua instância está saudável. Uma máquina que não controla decidiu que o seu pedido não parecia ter sido feito por uma pessoa.

Esse facto determina todas as correções abaixo. A decisão foi tomada no próprio hardware do motor, por isso nada na sua settings.yml pode substituí-la. Pode alterar o endereço de origem do pedido, escolher os motores que a instância consulta e definir o comportamento da instância quando um motor começa a recusar pedidos.

Duas falhas que parecem iguais e como distingui-las

A primeira falha ocorre quando a sua própria instância responde HTTP 429 (demasiados pedidos) ao seu próprio browser. Esse é o limitador do SearXNG, a camada de deteção de bots que fica à frente do endpoint de pesquisa. É executado no seu servidor e pode ser configurado por si. o limitador que devolve 429 aos seus próprios utilizadores é um problema separado, com configurações diferentes, e nenhuma das recomendações abaixo se aplica a esse caso.

A segunda falha ocorre a montante. A página de resultados carrega normalmente, mas um ou mais motores não aparecem nos resultados ou apresentam um aviso de erro. Nada na sua instância recusou o pedido. Um motor recusou o seu servidor.

• A página não carrega ou o endpoint de pesquisa responde 429: verifique o seu limitador.
• A página carrega, mas os resultados são escassos, ou um motor aparece assinalado com um erro: verifique o serviço a montante e continue a ler.

As duas falhas podem ocorrer na mesma instância e influenciam-se mutuamente, porque um limitador configurado de forma demasiado permissiva permite a entrada de tráfego que aumenta a taxa de consultas enviadas. Diagnostique cada uma separadamente.

Por que os mecanismos do SearXNG retornam erros de CAPTCHA em um VPS, mas não no meu laptop?

Isso acontece por causa do endereço de origem da solicitação. A sua conexão doméstica usa um endereço de uma faixa de um ISP (provedor de serviços de internet) para consumidores, compartilhada ao longo do tempo por muitas pessoas comuns. O seu VPS usa um endereço de uma faixa de datacenter, e essas faixas são públicas: qualquer pessoa pode consultar quais endereços pertencem a um provedor de hospedagem. Um mecanismo que pretende impedir scrapers começa tratando as solicitações provenientes de faixas de hospedagem como suspeitas, porque muito pouco do tráfego dessas faixas é gerado por uma pessoa usando um navegador.

Outros fatores também se somam ao endereço. A sua instância envia uma solicitação por mecanismo para cada pesquisa do usuário. Assim, mesmo poucos usuários geram, a partir de um único endereço, uma taxa que nenhuma pessoa isolada produz. O SearXNG não mantém uma sessão com o mecanismo nem envia um cookie persistente, por design. Portanto, cada solicitação chega sem histórico associado. O endereço também pode ter um histórico que você não criou, porque os provedores reutilizam endereços e o ocupante anterior pode ter feito scraping a partir dele durante meses.

A recusa nem sempre aparece como uma falha evidente. Um mecanismo pode responder com 403, com 429 ou com HTTP 200 e uma página de desafio no corpo da resposta. Esse último caso confunde, porque uma verificação do código de status indica que o mecanismo está funcionando, enquanto o SearXNG encontra zero resultados na resposta. Por isso, consulte o relatório de erros da sua própria instância em vez de executar curl no mecanismo e verificar apenas a linha de status.

Leia o que a sua instância reporta antes de alterar qualquer coisa

Cada correção abaixo começa pelo nome do mecanismo que está a falhar e pelo motivo que a sua instância registou para esse mecanismo. O SearXNG disponibiliza ambos. A página /stats lista os mecanismos com as respetivas contagens de erros e níveis de fiabilidade. O endpoint /stats/errors devolve os detalhes do erro em JSON, que é mais fácil de guardar e comparar na semana seguinte. Abra-os no navegador que normalmente utiliza para aceder à instância.

O log do contentor regista os mesmos eventos à medida que ocorrem. O nome do serviço apresentado aqui é o utilizado no ficheiro compose publicado com a documentação do contentor. Use o seu se for diferente.

docker compose logs -f core

Execute uma pesquisa que falhe enquanto o log estiver a ser monitorizado. Deverá aparecer uma entrada para o mecanismo que falhou à medida que a pesquisa é executada. Registe o nome do mecanismo e a string exata do motivo apresentada pela sua instância. Não copie o nome de um mecanismo de uma publicação de blog, incluindo esta. O conjunto de mecanismos que bloqueiam endereços de datacenters muda de mês para mês. O mecanismo que falha consigo pode funcionar perfeitamente para o autor do texto que está a ler.

Se a página de resultados não apresentar nenhum erro, mas os resultados forem escassos, consulte display_error_messages para esse mecanismo. O valor predefinido é true. Uma instância que o tenha desativado está a ocultar a única mensagem de que precisa.

Como o SearXNG repete tentativas e suspende um mecanismo que falha

O SearXNG não continua a insistir num mecanismo que recusa os pedidos. Um mecanismo que falha é suspenso. Enquanto está suspenso, é completamente ignorado. É assim que um mecanismo avariado passa a ficar silenciosamente indisponível.

Há duas camadas que controlam este comportamento. Ambas ficam em search:, dentro de settings.yml. Confirme estes nomes de chaves e valores em searx/settings.yml para a versão que está efetivamente a executar antes de colar qualquer conteúdo. Estes valores mudaram entre versões. Além disso, o exemplo na página da documentação das definições ainda mostra suspensões mais longas do que as do ficheiro que o SearXNG carrega na realidade. Na versão disponibilizada em searx/settings.yml em 17 October 2026, os valores predefinidos são:

search:
  ban_time_on_fail: 5
  max_ban_time_on_fail: 120
  suspended_times:
    SearxEngineAccessDenied: 180
    SearxEngineCaptcha: 3600
    SearxEngineTooManyRequests: 180
    cf_SearxEngineCaptcha: 1296000
    cf_SearxEngineAccessDenied: 86400
    recaptcha_SearxEngineCaptcha: 604800

A primeira camada trata falhas comuns, como um timeout. A suspensão começa após ban_time_on_fail segundos e aumenta a cada falha consecutiva, até max_ban_time_on_fail. Por predefinição, o limite é de dois minutos. Assim, um mecanismo instável recupera automaticamente poucos minutos depois de o problema desaparecer.

A segunda camada trata as falhas descritas neste guia. Quando o SearXNG reconhece a resposta como um desafio ou uma recusa, em vez de um erro genérico, aplica a entrada correspondente de suspended_times. A maioria desses valores é muito maior. 180 segundos correspondem a três minutos, para uma recusa simples ou um 429. 3600 correspondem a uma hora, para um CAPTCHA genérico. 86400 correspondem a um dia completo. 604800 correspondem a uma semana. 1296000 correspondem a quinze dias. As chaves com o prefixo cf_ aplicam-se quando o desafio é reconhecido como um desafio do Cloudflare. As chaves com o prefixo recaptcha_ aplicam-se quando é reconhecido como reCAPTCHA.

Isto explica o sintoma que mais tempo desperdiça. Encontra a causa, corrige-a e o mecanismo continua sem devolver resultados durante uma hora, ou durante vários dias depois de um desafio do Cloudflare. Continua suspenso. A suspensão fica guardada no processo em execução. Por isso, reiniciar o contentor limpa-a e a pesquisa seguinte tenta novamente usar o mecanismo. Um reinício simples resolve este caso. Antes de começar a recriar imagens sem necessidade, vale a pena saber quando um reinício é suficiente e quando é necessário recriar o contentor. Se o mecanismo falhar novamente logo depois do reinício, a correção não funcionou.

Uma definição por mecanismo exige um aviso. retry_on_http_error repete um pedido quando o mecanismo responde com os códigos de estado que indicar. Se o mecanismo estiver a bloquear o servidor, repetir os pedidos envia ainda mais tráfego para o sistema que já determinou que o servidor é um bot. Deixe esta definição inalterada, exceto quando estiver a contornar um mecanismo que falha de forma genuinamente intermitente.

A documentação do túnel SSH upstream e o que ele não resolve

Verificada em 17 de outubro de 2026, a documentação de administração do SearXNG resolve este problema com um túnel manual. Abra um proxy SOCKS através do seu servidor, configure o browser do desktop para o utilizar e responda manualmente ao desafio enquanto o motor vê o endereço do servidor.

ssh -q -N -D 8080 user@example.org

-D 8080 abre um servidor SOCKS local na porta 8080 que encaminha o tráfego através da ligação SSH. -N não executa nenhum comando remoto e -q mantém a saída silenciosa, por isso um túnel funcional não imprime nada e não termina. Verifique-o a partir de um segundo terminal:

curl -x socks://127.0.0.1:8080 http://ipecho.net/plain
curl http://ipecho.net/plain

O primeiro comando deve imprimir o endereço do servidor e o segundo deve imprimir o endereço do desktop. Duas respostas idênticas significam que o pedido não está a passar pelo túnel. Em seguida, configure as definições de rede do browser para utilizar um proxy SOCKS5 em 127.0.0.1 na porta 8080, abra no browser o mesmo verificador de endereços para confirmar que apresenta o endereço do servidor e visite o motor que está a apresentar o desafio. Responda ao desafio nesse local.

Agora, a parte importante. Quatro fatores limitam este método. O cookie que o motor fornece fica no browser do desktop, e o SearXNG não tem acesso aos cookies do browser. Portanto, a única coisa que pode ajudar a sua instância é o que o motor regista associado ao próprio endereço. Esse registo expira segundo um prazo definido pelo motor, que não o publica. Nenhuma parte do procedimento é automatizada, por isso terá de voltar ao teclado da próxima vez. Numa instância utilizada por outras pessoas, a taxa de consultas que acionou o desafio continua ativa, por isso o desafio volta a aparecer.

Use este método para pôr uma instância a funcionar esta tarde. Não baseie uma instância nele.

Solução duradoura: remova ou reduza o peso dos mecanismos que bloqueiam as pesquisas

A resposta duradoura mais simples é deixar de consultar um mecanismo que não atende o seu servidor. O seu settings.yml começa com use_default_settings: true na imagem do contentor. Isso significa que uma entrada em engines: com um name correspondente substitui apenas as chaves que indicar e mantém o restante da definição predefinida.

use_default_settings: true

engines:
  - name: <engine name from your stats page>
    disabled: true
  - name: <another engine name>
    weight: 0.3

disabled: true desativa o mecanismo por predefinição, mas mantém-no na página de preferências. Assim, um utilizador que precise dele pode voltar a ativá-lo para as suas próprias pesquisas. inactive: true remove-o completamente das definições do utilizador. É essa a opção adequada para um mecanismo que nunca funcionará a partir do seu endereço. weight tem outra função: ajusta o peso dos resultados desse mecanismo quando o SearXNG os combina e ordena. Um peso inferior a 1 mantém um mecanismo marginal disponível sem permitir que assuma o controlo da primeira página.

Reinicie o contentor depois de editar, faça algumas pesquisas e verifique novamente /stats. Uma página de estatísticas limpa, com seis mecanismos funcionais, é mais útil do que uma página cheia de erros com vinte mecanismos.

Correção duradoura: enviar pedidos de saída através de um proxy

O SearXNG pode enviar os pedidos de saída aos motores através de um proxy, o que altera o endereço que o motor vê. Configure esta opção globalmente em outgoing: ou por motor quando apenas um motor tiver o problema.

outgoing:
  request_timeout: 3.0
  extra_proxy_timeout: 10
  proxies:
    all://:
      - socks5h://user:password@proxy:1080

engines:
  - name: <engine name>
    proxies:
      http: socks5h://user:password@proxy:1080
      https: socks5h://user:password@proxy:1080

Prefira socks5h:// a socks5:// quando quiser que o proxy resolva o nome do host, porque h faz com que o nome seja enviado para o proxy em vez de ser resolvido no seu servidor. Aumente também o tempo limite. request_timeout tem o valor predefinido de 3.0 segundos. Um proxy acrescenta uma viagem de ida e volta a cada pedido, e os motores que antes respondiam dentro do prazo começam a falhar com erros de tempo limite. extra_proxy_timeout existe precisamente para este caso e acrescenta segundos quando um proxy está em uso. Especifique-o como um número inteiro, por exemplo 10. Ao contrário de request_timeout, que aceita valores decimais, extra_proxy_timeout é um número inteiro no esquema de definições. Por isso, um valor como 10.0 é rejeitado como settings.yml inválido, embora o exemplo comentado na página de documentação das definições de saída o apresente dessa forma.

Custos da utilização de um proxy:

• O operador do proxy vê quais os motores consultados pela sua instância e quando. O TLS (segurança da camada de transporte) impede que os termos de pesquisa apareçam nos respetivos logs, porque a consulta está dentro do pedido cifrado, mas o padrão e o momento do seu tráfego ficam visíveis para esse operador.
• Um endereço de saída partilhado é partilhado com todos os outros utilizadores que pagam por ele. Se esses utilizadores fizerem scraping, herdará a reputação deles, por vezes mais depressa do que o bloqueio que tentava evitar.
• As pools de proxies residenciais baratos são frequentemente construídas a partir de dispositivos de consumidores cujos proprietários não aceitaram conscientemente transportar tráfego. Saiba o que está a comprar.
• using_tor_proxy: true encaminha o tráfego através do Tor, mas os endereços dos nós de saída são publicados integralmente, e um motor que bloqueie intervalos de centros de dados normalmente bloqueia os nós de saída com a mesma ou maior facilidade.
• As pesquisas passam a depender de um serviço externo ao seu servidor. Esse serviço pode falhar segundo o seu próprio calendário e levar os seus resultados consigo.

Um proxy desloca o bloqueio em vez de o remover, e a privacidade da sua instância passa a incluir uma entidade terceira. Se o principal motivo para alojar o serviço por conta própria for uma explicação curta sobre privacidade, pondere isso em relação a o que uma instância alojada por si realmente oculta e o que não oculta antes de aderir a qualquer serviço.

Correção duradoura: executar deliberadamente um conjunto menor de motores

A opção que a maioria das pessoas ignora é aceitar menos motores. O valor do SearXNG está na combinação dos resultados, e a combinação de seis motores que respondem sempre é melhor do que vinte em que metade fica suspensa durante horas ou dias. Monitorize /stats durante uma semana e mantenha os motores que apresentam um histórico consistente a partir do seu endereço.

Os motores aos quais se autentica com uma chave de API comportam-se de forma diferente, porque o motor sabe quem é e aplica uma quota, em vez de tentar determinar se é uma pessoa. A contrapartida é uma conta, uma chave armazenada no seu ficheiro de definições e, normalmente, uma cobrança. Para um ou dois motores importantes para si, esse é muitas vezes o caminho menos problemático.

Tenha as outras ferramentas em conta ao tomar esta decisão. Um motor suspenso fica invisível para qualquer ferramenta que leia resultados através da API, porque a API JSON que o Open WebUI e ferramentas semelhantes consultam simplesmente devolve menos resultados, em vez de devolver um erro que a ferramenta consiga detetar. Se houver alguma tarefa automatizada dependente da sua instância, consulte /stats/errors segundo um agendamento, em vez de esperar que alguém se queixe de que as respostas pioraram.

Vale a pena insistir?

Responda contando os utilizadores. Uma instância para uma pessoa envia poucas pesquisas por dia a partir de um endereço, uma taxa que muitos motores nunca contestam. Quando um motor apresenta um desafio, a correção é simples: remova-o e quase não notará a sua falta. Esta é a experiência habitual de executar o SearXNG para si próprio num VPS pequeno, e não requer túnel nem proxy.

Uma instância pública ou partilhada é uma máquina diferente que executa o mesmo software. A taxa de consultas é o fator que desencadeia os desafios e aumenta com cada utilizador adicionado, por isso os desafios surgem mais depressa do que qualquer configuração consegue compensar. Planeie desde o início um conjunto menor de motores e lembre-se de que qualquer proxy adicionado passa a transportar as pesquisas de outras pessoas através da sua conta.

Os clientes automatizados ficam entre estes dois casos, mas aproximam-se do mais difícil. Um agente que executa várias pesquisas para responder a uma pergunta gera picos que nenhum utilizador humano produz, por isso uma instância para a qual encaminha agentes de programação e ferramentas de pesquisa encontra desafios mais cedo do que a mesma instância utilizada manualmente. Se esse for o seu caso, escolha o conjunto de motores com base na fiabilidade e não na abrangência, e permita que o agente trabalhe com resultados que consiga realmente obter.

A regra é esta: insista num motor quando ele for a razão para alojar a instância por conta própria e remova-o quando não for.

FAQ

Porque é que um motor do SearXNG continua sem devolver resultados depois de eu corrigir o problema?

Porque continua suspenso. Quando o SearXNG deteta um desafio ou uma recusa de um motor, deixa de fazer consultas a esse motor durante o período definido em search.suspended_times. Os valores predefinidos fornecidos variam entre três minutos e quinze dias, consoante o tipo de recusa. A suspensão fica guardada no processo em execução. Por isso, reiniciar o contentor elimina a suspensão e a pesquisa seguinte tenta consultar novamente o motor. Se o motor falhar outra vez logo depois do reinício, a correção não funcionou.

Um erro de CAPTCHA de um motor é igual ao erro 429 que a minha instância devolve?

Não. São respostas em sentidos opostos. Um erro 429 enviado pela sua instância ao browser resulta do limitador do próprio SearXNG, que decidiu que o seu pedido parecia automatizado. Esse comportamento pode ser configurado por si. Um erro de CAPTCHA ou de bloqueio é uma recusa do motor upstream ao seu servidor. Essa decisão é tomada numa infraestrutura que não controla. Se a página de resultados carregar e apenas faltarem alguns motores, está perante o segundo caso.

Uma VPN ou um proxy no meu servidor resolve os CAPTCHAs dos motores?

Por vezes, mas tem custos. Encaminhar os pedidos de saída através de outgoing.proxies altera o endereço que o motor vê. Isso pode remover um bloqueio associado ao intervalo de endereços do seu datacenter. O operador do proxy passa a ver que motores consulta e quando os consulta. Além disso, um endereço de saída partilhado pode trazer a reputação de outros clientes. A latência adicional também pode causar timeouts, a menos que aumente request_timeout e extra_proxy_timeout. O Tor está disponível através de using_tor_proxy, mas os endereços de saída são públicos e são frequentemente sujeitos a desafios.

Posso fazer com que o SearXNG resolva o CAPTCHA automaticamente?

Não existe uma definição para isso. O método documentado pelo projeto é manual: um túnel SSH SOCKS, o seu próprio browser e a sua intervenção no desafio. Qualquer solução criada para responder automaticamente aos desafios contraria a política declarada do motor e deixa de funcionar silenciosamente sempre que o desafio muda. Nesse caso, passa a manter um scraper em vez de executar uma instância de pesquisa. Remover os motores que bloqueiam o seu endereço é a solução que continua a funcionar.