Solução completa de erros do Claude Code WebFetch: 4 passos para resolver o problema Unable to verify if domain

Camada 4 · Ignorar WebFetch Substituição de Bash(curl:*) · ou integração com fetch-mcp / servidor Playwright MCP 🎯 Cenários onde o contêiner CI / preflight não funciona de forma alguma · contornar completamente o preflight do claude.ai 15 min Solução definitiva

Nível 1: Variáveis de ambiente de proxy e NO_PROXY

Este é o primeiro obstáculo comum para usuários na China. O Claude Code segue as variáveis de ambiente de proxy padrão, lendo-as na seguinte ordem de prioridade:

https_proxy > HTTPS_PROXY > http_proxy > HTTP_PROXY

Configuração mínima para macOS / Linux:

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

Você também pode adicionar diretamente ao bloco env em ~/.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"
  }
}

⚠️ Detalhe importante: Você deve incluir os domínios de serviço proxy de API da APIYI (api.apiyi.com / vip.apiyi.com) na variável NO_PROXY! Caso contrário, a invocação do modelo do Claude Code passará pelo proxy, o que é lento e pode ser interceptado pelo nó do proxy. Recomendamos que a API utilize o NO_PROXY para conexão direta com a APIYI, enquanto o preflight do WebFetch utiliza o proxy para acessar o claude.ai; manter esses dois caminhos separados é o mais estável.

Proxy com autenticação básica (comum em ambientes corporativos):

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

Nota: O Claude Code não suporta proxy SOCKS — se o seu proxy for apenas SOCKS, use privoxy ou v2ray para converter SOCKS para HTTP.

Nível 2: Pré-autorização de permissão WebFetch(domain:xxx)

Às vezes, o preflight funciona, mas o Claude Code continua perguntando "se você permite buscar este domínio" a cada vez. Adicione os domínios usados com frequência em permissions.allow para que o Claude pare de perguntar:

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

Consulta rápida da sintaxe de regras:

🎯 Sugestão de gerenciamento: Em cenários corporativos, recomenda-se usar managed-settings.json para criar uma lista de permissões (whitelist) de domínios, localizada em /Library/Application Support/ClaudeCode/managed-settings.json (macOS) ou /etc/claude-code/managed-settings.json (Linux), combinada com allowManagedPermissionRulesOnly: true para forçar todos os desenvolvedores a seguirem a regra. Equipes de desenvolvimento que utilizam a API do Claude via apiyi.com também podem usar o mesmo conjunto de regras para garantir que as políticas de permissão do Claude Code e da invocação do modelo no backend sejam unificadas.

Nível 3: Certificados CA corporativos e interceptação TLS

Se sua empresa utiliza produtos de segurança com interceptação TLS, como Zscaler / CrowdStrike / Cato Networks, eles reemitirão certificados HTTPS, fazendo com que o runtime Node.js do Claude Code reporte erros SSL como UNABLE_TO_GET_ISSUER_CERT.

Solução: Exporte o certificado CA raiz da empresa e aponte para ele:

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

Ou adicione ao ~/.claude/settings.json:

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

Valores opcionais para CLAUDE_CODE_CERT_STORE:

Autenticação mTLS bidirecional (ambientes corporativos mais rigorosos):

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="your-passphrase"

Nível 4: Contornar o WebFetch usando Bash curl ou MCP

Se os três níveis acima não resolverem, a maneira mais confiável é não usar o WebFetch — deixe o Claude usar o curl diretamente via ferramenta Bash, ou conecte um servidor MCP de fetch de terceiros.

Opção A: Permitir que o Bash use curl/wget

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

Em seguida, diga ao Claude na conversa: "Por favor, use o curl para obter o conteúdo da página inicial de www.weather.com.cn" — ele pulará o WebFetch e usará o Bash diretamente. Este caminho não dispara o preflight, e a configuração do proxy só precisa garantir que o site de destino seja acessível.

Opção B: Conectar fetch-mcp ou Playwright MCP

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

As solicitações de rede da ferramenta MCP são iniciadas pelo próprio processo do servidor MCP e não passam pela cadeia de preflight do Claude Code, aumentando significativamente a estabilidade. Para sites dinâmicos que exigem a execução de JavaScript, o Playwright MCP é mais adequado.

Matriz de comparação de soluções de diagnóstico WebFetch ★ Quanto mais, mais adequado · Veja qual coluna tem mais tons escuros

dimensões de avaliação

A. Configuração de proxy HTTPS_PROXY

B. Pré-autorização de permissões WebFetch(domínio)

C. CA Corporativa NODE_EXTRA_CA_CERTS

D. Contornar o WebFetch Bash curl + MCP

Dificuldade de configuração ★★★★☆ ★★★★★ ★★☆☆☆ ★★★★☆

resolver a abrangência de problemas ★★★★★ ★★☆☆☆ ★★★☆☆ ★★★★★

impacto no desempenho ★★★☆☆ ★★★★★ ★★★★☆ ★★★★☆

Conformidade corporativa ★★★☆☆ ★★★★★ ★★★★★ ★★★☆☆

Adaptação nacional ★★★★☆ ★★★☆☆ ★★☆☆☆ ★★★★★

💡 Recomendação de combinação para usuários nacionais: A(base de proxy) + B(domínio comum) + D(fallback)

Casos práticos de resolução de problemas com o WebFetch do Claude Code

Agora que cobrimos a teoria, vamos analisar o fluxo completo de resolução em três cenários reais.

Cenário 1: Captura do weather.com.cn em um MacBook na China (cenário de screenshot)

Sintoma: O comando fetch para www.weather.com.cn retorna repetidamente "Unable to verify".

Passos para diagnóstico:

# Passo 1 Confirmar o status do proxy
echo $HTTPS_PROXY  # Deve exibir algo como http://127.0.0.1:7890

# Passo 2 Verificar manualmente se claude.ai está acessível
curl -I https://claude.ai/code/ -x http://127.0.0.1:7890
# Se retornar 403 + cf-mitigated, significa que o Cloudflare bloqueou, vá para o Passo 3
# Se retornar 200, o preflight está ok, verifique as permissões

# Passo 3 Mudar a estratégia no Claude Code — usar Bash + curl
# Diga diretamente no chat:
# "Não use o WebFetch, use o curl para capturar a página inicial de http://www.weather.com.cn"

Configuração 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:*)"
    ]
  }
}

🎯 Dica prática na China: A combinação mais estável para usuários locais é: "API via APIYI apiyi.com + WebFetch via proxy + fallback para curl quando necessário". Ao adicionar o base_url da APIYI ao NO_PROXY, as requisições de API do Claude Code não são desviadas pelo proxy, mantendo a latência e a estabilidade equivalentes a uma conexão direta com o exterior.

Cenário 2: Máquina corporativa + interceptação TLS do Zscaler

Sintoma: O WebFetch retorna SELF_SIGNED_CERT_IN_CHAIN ou UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Solução:

# Passo 1 Obtenha o certificado CA raiz da empresa com o TI (geralmente .pem ou .crt)
# Passo 2 Configure o Claude Code para confiar nesta CA
export NODE_EXTRA_CA_CERTS=~/certs/company-zscaler-root.pem

# Passo 3 Confie também no repositório de certificados do sistema (o Zscaler geralmente já está injetado)
export CLAUDE_CODE_CERT_STORE=bundled,system

# Passo 4 Reinicie o Claude Code

Cenário 3: Execução headless em Docker / CI

Sintoma: Funciona localmente, mas o WebFetch falha 100% das vezes no CI.

Causa: O container não possui proxy nem navegador, e a proteção contra bots do Cloudflare identifica o cliente CLI e recusa a conexão.

Solução: Desabilite o WebFetch e force o uso do Bash no CI:

# .github/workflows/claude.yml ou similar
env:
  CLAUDE_CODE_DISABLE_WEBFETCH: "true"  # Se esta variável de ambiente for suportada

Ou via parâmetro de inicialização --disallowedTools:

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

🎯 Sugestão de integração CI: Em ambientes conteinerizados, aponte a chave API para um nó de serviço proxy de API estável da APIYI (apiyi.com) para evitar falhas no CI devido a oscilações na rede internacional. Recomendamos configurar ANTHROPIC_BASE_URL=https://vip.apiyi.com + ANTHROPIC_API_KEY=sk-xxx nos secrets do GitHub Actions / GitLab CI. Com a estratégia de desativação do WebFetch, a estabilidade das tarefas do Claude Code no CI pode chegar a mais de 99%.

Melhores práticas de engenharia para erros no WebFetch do Claude Code

É fácil fazer um demo funcionar, mas para garantir que todos na equipe usem o Claude Code de forma estável, há alguns pontos cruciais.

Prática 1: managed-settings.json unificado

Distribua um managed-settings.json unificado para a equipe, evitando que cada um precise configurar manualmente:

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

Caminhos dos arquivos:

Prática 2: Estratégia de fallback de três níveis

Deixe clara a prioridade de seleção de ferramentas no CLAUDE.md para que o Claude tente na ordem correta:

## Prioridade das ferramentas de web scraping

1. Priorize o WebFetch (domínios pré-autorizados)
2. Se o WebFetch falhar, faça o fallback para o curl via Bash
3. Para sites dinâmicos, use o Playwright MCP
4. Nunca use `curl -k` para ignorar erros de certificado

Ao adicionar isso ao `CLAUDE.md`, o Claude **alternará automaticamente para o curl** quando encontrar erros no WebFetch, melhorando significativamente a experiência do usuário.

### Prática 3: Script de verificação de integridade (preflight)

Crie um script de diagnóstico rápido para executar antes de qualquer troubleshooting:

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

echo "=== Variáveis de Ambiente ==="
env | grep -iE "proxy|claude_code|node_extra"

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

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

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

echo "=== Resolução DNS ==="
nslookup claude.ai

Se claude.ai/code/ retornar 403 com o cabeçalho de resposta cf-mitigated, é um problema clássico de preflight do Cloudflare — aplique diretamente a solução de camada 4.

🎯 Dica de diagnóstico: Quando o Claude Code apresentar anomalias, 80% dos problemas podem ser localizados com este script. Para usuários na China, recomendamos adicionar vip.apiyi.com como um nó de encaminhamento de API à sua lista de verificação — se o APIYI estiver acessível, mas o site oficial da Anthropic não, utilize o serviço proxy de API da APIYI (apiyi.com) para continuar trabalhando e evitar que problemas de rede bloqueiem seu fluxo de desenvolvimento.

FAQ: Erros comuns do WebFetch no Claude Code

Q1: Por que a mensagem de erro diz "enterprise security policies blocking claude.ai", se minha empresa não instalou nenhum software de segurança?

Esta é uma mensagem imprecisa da Anthropic. O que realmente está bloqueando é a proteção contra bots do Cloudflare antes do acesso ao claude.ai. O Cloudflare identifica o processo CLI como um bot e retorna um JS Challenge; como o CLI não consegue completar o desafio, ele exibe esse erro. Geralmente não tem relação com as políticas de TI da sua empresa.

Q2: O serviço proxy de API da APIYI pode resolver erros do WebFetch?

Parcialmente. O APIYI (apiyi.com) apenas encaminha solicitações de API para api.anthropic.com, permitindo que o diálogo com o Modelo de Linguagem Grande e as decisões de invocação do modelo funcionem de forma estável. No entanto, o preflight do WebFetch é feito contra o claude.ai (não o api.anthropic.com), caminho que o APIYI não cobre — isso precisa ser resolvido via proxy local. Recomendamos uma abordagem combinada: use a conexão direta da APIYI para a API e um proxy para o preflight; os dois caminhos não interferem entre si.

Q3: Existe uma configuração skipWebFetchPreflight?

Há discussões na comunidade, mas até abril de 2026, não há documentação oficial. A issue #39896 do GitHub menciona que este é um recurso esperado pela comunidade para pular a verificação de preflight. Até que seja oficialmente suportado, recomendamos usar a solução de camada 4 (Bash curl + domínios pré-autorizados) para contornar o problema; o efeito é equivalente e mais controlável.

Q4: Ativei o proxy global no Clash, por que o WebFetch ainda apresenta erro?

O modo de proxy global do Clash não define variáveis de ambiente automaticamente. O Claude Code é um processo CLI Node.js que lê apenas variáveis de ambiente como HTTPS_PROXY, ele não detecta as configurações de proxy do sistema. Você precisa exportar explicitamente as variáveis de proxy no seu shell profile ou adicioná-las ao bloco env em ~/.claude/settings.json.

Q5: O WebFetch funcionou, mas o resultado está incompleto, com apenas metade do conteúdo?

Isso ocorre devido ao limite max_content_tokens do Claude Code. Não é possível ajustar isso nas regras de permissão, mas se você invocar a ferramenta web_fetch diretamente via API do Claude (fora do CLI do Claude Code), você pode definir "max_content_tokens": 100000 para aumentar a quantidade de captura por página. Nesse cenário, recomendamos a conexão direta via APIYI (apiyi.com) para maior flexibilidade.

Q6: É possível evitar erros desativando completamente o WebFetch?

Sim. Adicione o parâmetro ao iniciar:

claude --disallowedTools WebFetch

Ou no settings.json:

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

Ao permitir Bash(curl:*), o Claude mudará automaticamente para o uso do curl, o que, para muitos usuários, resulta em uma experiência melhor.

Q7: Como configurar o Claude Code no GitHub Actions / GitLab CI?

Em containers de CI, recomendamos 100% desativar o WebFetch — containers não possuem ambiente de navegador e o preflight quase sempre falhará. Ao mesmo tempo, aponte as solicitações de API para o nó estável da APIYI (apiyi.com):

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

Resumo de Erros e Lista de Ações para o Claude Code WebFetch

Ao analisar o cenário, o erro Claude Code WebFetch deve-se, na verdade, às limitações de design do Cloudflare preflight + CLI sem navegador, e não a problemas na sua rede ou políticas de TI. Em resumo:

✅ A "tríade" para usuários no Brasil/China: API via APIYI apiyi.com (conexão direta) + Proxy local para o preflight do claude.ai + Bash curl como fallback. Isso resolve 90% dos erros de WebFetch.

Lista de Ações Práticas

Execute estes 5 passos por ordem de prioridade:

1. Configurar proxy: Defina HTTPS_PROXY + HTTP_PROXY e adicione o domínio da APIYI ao NO_PROXY.
2. Pré-autorizar domínios: Adicione os sites que você acessa com frequência em permissions.allow dentro de WebFetch(domain:...).
3. Tratar CA corporativo: Se estiver em um ambiente com Zscaler ou CrowdStrike, configure NODE_EXTRA_CA_CERTS.
4. Preparar fallback: Permita Bash(curl:*) para que o Claude alterne automaticamente quando encontrar bloqueios.
5. Script de verificação de saúde: Adicione o claude-code-doctor.sh à cadeia de ferramentas da sua equipe.

Melhores práticas para usuários domésticos · Arquitetura de caminho e camada dividida Desacoplamento do caminho da API e do caminho WebFetch · sem interferência mútua

máquina local do desenvolvedor Claude Code CLI Configuração NO_PROXY: api.apiyi.com

① Caminho da API APIYI encaminhamento transparente vip.apiyi.com (conexão direta)

② Caminho de Preflight proxy local 127.0.0.1:7890

③ Fallback Bash(curl:*) Conexão direta ao site de destino

Anthropic API api.anthropic.com inferência do modelo + decisão de ferramentas

claude.ai/code/ endpoint de verificação de domínio (Proteção Cloudflare)

site de destino weather.com.cn e outros conexão direta (sem necessidade de preflight)