Claude Code WebFetch 오류 완벽 해결: Unable to verify if domain 문제 4단계 해결법

Claude Code에서 http://www.weather.com.cn을 fetch 하려고 할 때, 5번 연속으로 Unable to verify if domain www.weather.com.cn is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.라는 빨간색 오류 메시지를 보셨나요? 마치 "네트워크나 방화벽이 claude.ai를 차단했다"는 것처럼 보이지만, 사실은 그렇지 않습니다. 이 오류 메시지는 사용자와 운영자를 심각하게 오도하고 있습니다.

이 글에서는 Claude Code WebFetch 오류의 진짜 원인을 체계적으로 분석합니다. Anthropic 공식 GitHub 이슈, Claude Code 네트워크 설정 문서, 그리고 커뮤니티 실측 결과를 바탕으로 4단계 해결 방안을 제시합니다. 글 마지막에는 국내 사용자가 APIYI(apiyi.com)를 통해 Claude Code를 사용할 때의 모범 사례를 담았습니다. APIYI는 API 중계만 담당하며, WebFetch의 preflight 문제는 프록시와 설정을 함께 조정해야 해결할 수 있습니다.

Claude Code WebFetch 오류의 진짜 원인

설정을 수정하기 전에 오류 메시지가 실제로 무엇을 의미하는지 파악해야 합니다. Claude Code WebFetch의 이 오류는 전형적인 "감기를 암으로 오해하는" 사례입니다.

오류 메시지 이면의 진실

Claude Code는 WebFetch 호출을 실행하기 전에 먼저 "도메인 안전성 검증"(preflight)을 수행합니다. https://claude.ai/code/에 HTTP 요청을 보내 "이 도메인을 가져와도 되는지" 묻는 것이죠. 문제는 바로 이 단계에서 발생합니다.

단계	실제 상황
① Claude Code 내부 WebFetch 트리거	CLI 프로세스가 대상 URL을 가져올 준비
② Preflight 요청	https://claude.ai/code/에 HTTP 요청 전송
③ Cloudflare Bot 방어 차단	403 + cf-mitigated: challenge + JS Challenge 반환
④ CLI에 브라우저 환경 없음	JavaScript 챌린지 실행 불가
⑤ Preflight 실패	"Unable to verify if domain is safe" 오류 발생
⑥ 대상 URL은 방문조차 안 함	weather.com.cn 접속 가능 여부와는 전혀 무관

즉, 대상 사이트의 접속 가능 여부는 테스트조차 되지 않았습니다. 요청은 두 번째 단계에서 이미 막혔습니다. 오류 메시지에 언급된 "enterprise security policies blocking claude.ai"는 사실이지만, 여기서 말하는 "기업 정책"은 여러분 회사의 IT 정책이 아니라 Anthropic이 claude.ai 앞에 배치한 Cloudflare 방어 규칙입니다.

🎯 핵심 요약: 이는 아키텍처 설계상의 문제로, Anthropic 공식 GitHub 이슈 #39896에서 이미 확인되었습니다. CI/CD, Docker 컨테이너, WSL, SSH 세션, Bedrock 배포 등 모든 headless 환경에서 발생할 수 있습니다. APIYI(apiyi.com)를 통해 API 호출을 중계할 때도 마찬가지입니다. preflight는 api.anthropic.com이 아닌 claude.ai로 향하기 때문입니다.

세 가지 전형적인 실패 시나리오

네트워크 환경에 따라 이 오류는 다양한 요인이 겹쳐 발생할 수 있습니다.

시나리오	대상 사이트	프록시 상태	근본 원인
A. 국내 기기 + 프록시 미사용	해외 사이트	프록시 없음	claude.ai 직결 실패 + preflight 실패
B. 국내 기기 + 프록시 사용	국내 사이트(weather.com.cn)	해외 프록시	프록시를 통해 claude.ai 접속 시 Cloudflare 챌린지 발생 가능
C. 해외 기기 + 프록시 미사용	모든 사이트	프록시 불필요	Cloudflare가 CLI를 봇으로 인식하여 preflight 실패

스크린샷에서 사용자가 www.weather.com.cn을 fetch 하려던 사례는 시나리오 B에 해당합니다. "국내 사이트니까 접속이 되어야 하지 않나?" 싶겠지만, 실제로는 claude.ai로 향하는 preflight에서 문제가 발생한 것이며 대상 사이트와는 아무런 상관이 없습니다.

Claude Code WebFetch 오류 해결을 위한 4단계 점검 경로

근본 원인을 파악했다면, 이제 "영향 범위가 작은 순서"대로 차근차근 점검해 봅시다.

1단계: 프록시 및 NO_PROXY 환경 변수

국내 사용자들에게 가장 흔한 첫 번째 관문입니다. Claude Code는 표준 프록시 환경 변수를 따르며, 다음 우선순위에 따라 읽어 들입니다.

https_proxy > HTTPS_PROXY > http_proxy > HTTP_PROXY

macOS / Linux 최소 설정:

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

또는 ~/.claude/settings.json의 env 블록에 직접 입력할 수도 있습니다.

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

⚠️ 핵심 디테일: NO_PROXY에는 반드시 APIYI의 API 중계 서비스 도메인(api.apiyi.com / vip.apiyi.com)을 추가해야 합니다! 그렇지 않으면 Claude Code의 모델 호출이 프록시를 거쳐 돌아가게 되어 속도가 느려질 뿐만 아니라 프록시 노드에 의해 가로채일 수 있습니다. API 호출은 NO_PROXY를 통해 APIYI로 직접 연결하고, WebFetch의 preflight는 프록시를 통해 claude.ai에 접속하도록 두 경로를 분리하는 것이 가장 안정적입니다.

기본 인증 프록시(회사 프록시에서 흔함):

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

주의: Claude Code는 SOCKS 프록시를 지원하지 않습니다. 프록시가 SOCKS 모드만 지원한다면 privoxy나 v2ray를 사용하여 SOCKS를 HTTP로 변환하세요.

2단계: 권한 사전 승인 WebFetch(domain:xxx)

preflight는 정상인데 Claude Code가 매번 "이 도메인에 대한 접근을 허용하시겠습니까?"라고 묻는 경우가 있습니다. 자주 사용하는 도메인을 permissions.allow에 추가하면 Claude가 더 이상 묻지 않습니다.

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

전체 규칙 문법 요약:

규칙 작성법	적용 범위
WebFetch	모든 WebFetch 호출
WebFetch(domain:example.com)	example.com만
WebFetch(domain:*.example.com)	모든 example.com 하위 도메인
WebFetch(domain:*)	모든 도메인(전체 허용)

🎯 관리 제안: 기업 환경에서는 managed-settings.json을 사용하여 허용 도메인을 화이트리스트로 관리하는 것을 권장합니다. /Library/Application Support/ClaudeCode/managed-settings.json(macOS) 또는 /etc/claude-code/managed-settings.json(Linux)에 배치하고 allowManagedPermissionRulesOnly: true를 설정하여 모든 개발자가 이를 준수하도록 강제할 수 있습니다. APIYI(apiyi.com)를 통해 Claude API를 호출하는 개발팀도 동일한 규칙을 사용하여 Claude Code와 백엔드 API 호출의 권한 정책을 통일할 수 있습니다.

3단계: 기업용 CA 인증서 및 TLS 가로채기

회사에서 Zscaler / CrowdStrike / Cato Networks 등 TLS 가로채기 방식의 보안 제품을 사용하는 경우, 이들이 HTTPS 인증서를 재발급하여 Claude Code의 Node.js 런타임에서 UNABLE_TO_GET_ISSUER_CERT와 같은 SSL 오류가 발생할 수 있습니다.

해결 방법: 기업 루트 CA 인증서를 내보낸 후 해당 경로를 지정하세요.

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

또는 ~/.claude/settings.json에 작성합니다.

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

CLAUDE_CODE_CERT_STORE 설정값:

값	의미
bundled	Claude Code에 포함된 Mozilla CA 모음만 신뢰
system	운영체제의 인증서 저장소만 신뢰
bundled,system(기본값)	둘 다 신뢰

mTLS 상호 인증(더 엄격한 기업 환경):

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"

4단계: WebFetch 우회, Bash curl 또는 MCP로 대체

위의 세 단계로 해결되지 않는다면, 가장 확실한 방법은 WebFetch를 사용하지 않는 것입니다. Claude가 Bash 도구를 통해 직접 curl을 실행하게 하거나, 타사 fetch MCP 서버를 연결하세요.

방법 A: Bash에서 curl/wget 사용 허용

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

그다음 대화창에서 Claude에게 "curl을 사용하여 www.weather.com.cn의 메인 페이지 내용을 가져와 줘"라고 요청하세요. 그러면 WebFetch를 건너뛰고 Bash를 통해 직접 실행합니다. 이 경로는 preflight를 전혀 트리거하지 않으며, 대상 사이트에 접근할 수 있는 프록시 설정만 되어 있으면 됩니다.

방법 B: fetch-mcp 또는 Playwright MCP 연결

# 타사 fetch MCP 서버 설치
claude mcp add fetch npx -- @modelcontextprotocol/server-fetch

MCP 도구의 네트워크 요청은 MCP 서버 프로세스 자체가 수행하므로 Claude Code의 preflight 링크를 거치지 않아 안정성이 크게 향상됩니다. JavaScript 실행이 필요한 동적 사이트의 경우 Playwright MCP를 사용하는 것이 더 적합합니다.

Claude Code WebFetch 실전 트러블슈팅 사례

이론은 여기까지 하고, 실제 세 가지 상황에서의 완벽한 해결 과정을 살펴보겠습니다.

시나리오 1: 국내 MacBook에서 weather.com.cn 크롤링 (스크린샷 상황)

현상: www.weather.com.cn을 fetch할 때 계속해서 Unable to verify 오류가 발생합니다.

해결 단계:

# Step 1 프록시 상태 확인
echo $HTTPS_PROXY  # http://127.0.0.1:7890 등이 출력되어야 함

# Step 2 claude.ai 접속 가능 여부 수동 확인
curl -I https://claude.ai/code/ -x http://127.0.0.1:7890
# 403 + cf-mitigated가 반환되면 Cloudflare 차단이므로 Step 3으로 이동
# 200이 반환되면 preflight는 통과이므로 permissions 확인

# Step 3 Claude Code에서 방식 전환 - Bash + curl 사용
# 대화창에 직접 입력:
# "WebFetch 쓰지 말고, curl로 http://www.weather.com.cn 메인 페이지를 가져와"

최종 설정(~/.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:*)"
    ]
  }
}

🎯 국내 실전 팁: 국내 사용자에게 가장 안정적인 조합은 「API는 APIYI apiyi.com 이용 + WebFetch는 프록시 경유 + 필요시 curl로 폴백」입니다. APIYI의 base_url을 NO_PROXY에 추가하면 Claude Code의 API 요청이 프록시를 우회하지 않아, 해외 직결과 동일한 지연 시간과 안정성을 확보할 수 있습니다.

시나리오 2: 회사 PC + Zscaler TLS 가로채기

현상: WebFetch에서 SELF_SIGNED_CERT_IN_CHAIN 또는 UNABLE_TO_VERIFY_LEAF_SIGNATURE 오류 발생.

해결:

# Step 1 IT 부서에서 회사 루트 CA 인증서(.pem 또는 .crt) 확보
# Step 2 Claude Code가 해당 CA를 신뢰하도록 설정
export NODE_EXTRA_CA_CERTS=~/certs/company-zscaler-root.pem

# Step 3 시스템 인증서 저장소도 함께 신뢰(Zscaler는 보통 이미 주입됨)
export CLAUDE_CODE_CERT_STORE=bundled,system

# Step 4 Claude Code 재시작

시나리오 3: Docker / CI 컨테이너 내 headless 실행

현상: 로컬에서는 잘 되는데, CI 환경에서는 WebFetch가 100% 실패함.

원인: 컨테이너 내부에 프록시나 브라우저가 없어, Cloudflare의 봇 방어 시스템이 CLI 클라이언트의 연결을 즉시 차단함.

해결: CI 환경에서는 WebFetch를 비활성화하고 Bash 사용을 강제:

# .github/workflows/claude.yml 등
env:
  CLAUDE_CODE_DISABLE_WEBFETCH: "true"  # 해당 환경 변수 적용 시

또는 --disallowedTools 실행 인자 사용:

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

🎯 CI 통합 제안: 컨테이너 환경에서는 API 키를 APIYI apiyi.com의 안정적인 중계 노드로 설정하여 해외 네트워크 불안정으로 인한 CI 실패를 방지하세요. GitHub Actions / GitLab CI의 secrets에 ANTHROPIC_BASE_URL=https://vip.apiyi.com + ANTHROPIC_API_KEY=sk-xxx를 설정하고 WebFetch 비활성화 전략을 병행하면, CI 내 Claude Code 작업 안정성을 99% 이상으로 유지할 수 있습니다.

Claude Code WebFetch 오류 해결을 위한 엔지니어링 베스트 프랙티스

단일 데모를 성공시키는 것은 쉽지만, 팀원 모두가 Claude Code를 안정적으로 사용하게 하려면 몇 가지 핵심 포인트가 필요합니다.

실천 1: 통합된 managed-settings.json 사용

팀원들에게 통일된 managed-settings.json을 배포하여 각자 설정하느라 고생하지 않도록 하세요:

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

파일 배치 경로:

플랫폼	경로
macOS	/Library/Application Support/ClaudeCode/managed-settings.json
Linux	/etc/claude-code/managed-settings.json
Windows	C:\ProgramData\ClaudeCode\managed-settings.json

실천 2: 3단계 폴백(Fallback) 전략

CLAUDE.md에 도구 사용 우선순위를 명확히 기재하여 Claude가 순서대로 시도하게 하세요:

## 웹 스크래핑 도구 우선순위

1. WebFetch 우선 사용 (사전 승인된 도메인)
2. WebFetch 실패 시, Bash curl로 폴백(fallback)
3. 동적 사이트는 Playwright MCP 사용
4. `curl -k`를 사용하여 인증서 오류를 무시하는 행위는 절대 금지

```markdown
이 내용을 CLAUDE.md에 추가하면, Claude가 WebFetch 오류 발생 시 자동으로 curl로 전환하여 사용자 경험이 크게 개선됩니다.

실습 3: preflight 상태 점검 스크립트

빠른 진단을 위한 스크립트를 작성해 보세요. 문제 발생 시 가장 먼저 실행하면 좋습니다.

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

echo "=== 환경 변수 ==="
env | grep -iE "proxy|claude_code|node_extra"

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

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

echo "=== APIYI 중계 테스트 ==="
curl -sI -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" \
  https://vip.apiyi.com/

echo "=== DNS 해석 ==="
nslookup claude.ai

만약 claude.ai/code/가 cf-mitigated 응답 헤더와 함께 403을 반환한다면, 전형적인 Cloudflare preflight 문제입니다. 이때는 바로 4계층 솔루션을 적용하세요.

🎯 진단 제언: Claude Code에 이상이 생겼을 때, 이 진단 스크립트로 문제의 80%를 파악할 수 있습니다. 국내 사용자라면 vip.apiyi.com을 API 중계 노드로 체크리스트에 추가하는 것을 권장합니다. APIYI는 접속 가능하지만 Anthropic 공식 사이트가 접속되지 않는다면, APIYI apiyi.com 중계를 통해 개발 흐름이 끊기지 않도록 하세요.

Claude Code WebFetch 오류 FAQ

Q1: "enterprise security policies blocking claude.ai"라는 오류가 뜨는데, 회사에서 보안 소프트웨어를 설치하지 않았어요. 왜 그런가요?

Anthropic의 공식 메시지가 부정확한 경우입니다. 실제로 차단하는 것은 claude.ai 앞단의 Cloudflare 봇 방어 시스템입니다. Cloudflare가 CLI 프로세스를 봇으로 인식하여 JS Challenge를 보내는데, CLI가 이를 완료하지 못하면 해당 오류를 띄웁니다. 보통 회사의 IT 정책과는 무관합니다.

Q2: APIYI 중계를 사용하면 WebFetch 오류를 해결할 수 있나요?

부분적으로 가능합니다. APIYI apiyi.com은 api.anthropic.com의 API 요청만 중계하므로, Claude Code의 모델 호출이나 도구 사용 결정은 안정적으로 작동합니다. 하지만 WebFetch의 preflight는 claude.ai(api.anthropic.com이 아님)를 타겟으로 하므로, 이 경로는 APIYI가 커버하지 않습니다. 로컬 프록시를 통해 해결해야 합니다. API는 APIYI로 직결하고, preflight는 프록시를 타는 방식으로 조합하여 사용하는 것을 추천합니다.

Q3: skipWebFetchPreflight 설정 항목이 있나요?

커뮤니티에서 논의 중이나, 2026년 4월 기준 공식 문서화된 기능은 아닙니다. GitHub 이슈 #39896에서 preflight 검증을 건너뛰는 기능으로 언급된 바 있습니다. 공식 지원 전까지는 4계층 솔루션(Bash curl + 권한 사전 승인 도메인)을 사용하여 문제를 우회하는 것이 가장 효과적이고 제어하기 쉽습니다.

Q4: Clash 글로벌 프록시를 켰는데도 WebFetch 오류가 나요. 왜죠?

Clash의 글로벌 프록시 모드는 환경 변수를 자동으로 설정하지 않습니다. Claude Code는 Node.js CLI 프로세스이므로 HTTPS_PROXY와 같은 환경 변수만 읽으며, 시스템 프록시 설정을 자동으로 감지하지 않습니다. 쉘 프로필에 프록시 변수를 명시적으로 export하거나 ~/.claude/settings.json의 env 블록에 작성해야 합니다.

Q5: WebFetch는 성공했는데 결과가 절반만 나와요.

Claude Code의 max_content_tokens 제한 때문입니다. 권한 규칙에서는 조정할 수 없지만, Claude API를 직접 호출하여 web_fetch 도구를 사용하는 경우(Claude Code CLI가 아닌 경우), "max_content_tokens": 100000으로 설정하여 페이지당 수집량을 늘릴 수 있습니다. 이 경우 APIYI apiyi.com을 통해 API를 직결하는 것이 유연성 면에서 좋습니다.

Q6: WebFetch를 비활성화해서 오류를 완전히 피할 수 있나요?

네, 가능합니다. 시작 시 파라미터를 추가하세요:

claude --disallowedTools WebFetch

또는 settings.json에서 설정합니다:

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

이렇게 설정하고 Bash(curl:*)를 허용하면, Claude가 자동으로 curl을 사용하게 되어 국내 사용자에게는 오히려 더 나은 경험을 제공합니다.

Q7: GitHub Actions / GitLab CI에서 Claude Code를 사용하려면 어떻게 설정하나요?

CI 컨테이너 환경에서는 WebFetch 비활성화를 100% 권장합니다. 컨테이너에는 브라우저 환경이 없어 preflight가 거의 실패하기 때문입니다. 동시에 API 요청을 APIYI apiyi.com의 안정적인 노드로 향하게 하세요:

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

Claude Code WebFetch 오류 요약 및 실행 가이드

전체 내용을 되돌아보면, Claude Code WebFetch 오류의 본질은 Cloudflare preflight + CLI 브라우저 미지원이라는 설계상의 제약 때문이지, 사용자의 네트워크나 IT 정책 문제가 아닙니다. 한 문장으로 요약하자면 다음과 같습니다.

✅ 국내 사용자 필수 전략: API는 APIYI(apiyi.com)를 통해 직결하고, 로컬 프록시는 claude.ai preflight를 거치며, Bash curl을 폴백(fallback)으로 설정하세요. 이렇게 하면 90% 이상의 WebFetch 오류를 우회할 수 있습니다.

실행 가이드 (Action Plan)

우선순위에 따라 다음 5단계를 수행하세요:

1. 프록시 설정: HTTPS_PROXY와 HTTP_PROXY를 설정하고, APIYI 도메인을 NO_PROXY에 추가하세요.
2. 도메인 사전 승인: 자주 크롤링하는 사이트를 permissions.allow의 WebFetch(domain:...)에 등록하세요.
3. 기업용 CA 처리: Zscaler나 CrowdStrike 환경이라면 NODE_EXTRA_CA_CERTS를 설정하세요.
4. 폴백 준비: Bash(curl:*)를 허용하여 Claude가 막혔을 때 자동으로 전환되도록 하세요.
5. 상태 점검 스크립트: claude-code-doctor.sh를 팀 도구 체인에 통합하세요.

🎯 마지막 제언: Claude Code의 네트워크 문제는 프록시, 인증서, 권한 규칙, 도구 우선순위가 복합적으로 얽힌 시스템 엔지니어링의 영역입니다. 먼저 APIYI(apiyi.com)를 통해 API 호출 경로를 안정화(SLA가 가장 확실함)한 다음, WebFetch의 preflight와 CA 문제를 단계별로 해결하는 것을 권장합니다. 해당 플랫폼은 Claude 전 모델과 기본 도구를 지원하여 각 설정 단계가 제대로 작동하는지 빠르게 검증할 수 있습니다.

---

작성자: APIYI 기술팀 | 더 많은 Claude Code 실전 튜토리얼은 help.apiyi.com에서 확인하세요.