Claude Code 웹 검색이 작동하지 않나요? 4가지 해결법과 가장 안정적인 대안

Claude Code 웹 검색이 작동하지 않나요? 당신만 그런 것이 아닙니다. 권한 거부, “Did 0 searches” 결과, 조용히 실패하는 문제까지, Anthropic의 내장 WebSearch 도구는 개발자들에게 꾸준한 스트레스 요인이었습니다. 이 가이드에서는 가장 흔한 네 가지 원인과 각각의 해결법, 그리고 절대 잘 깨지지 않는 대안까지 정리합니다.

왜 Claude Code 웹 검색은 자주 고장 날까

Claude Code의 기본 WebSearch 도구 (web_search) 는 외부 연동이 아니라 Claude 모델 자체에 내장되어 있습니다. 즉, 문제가 생기면 일반적인 도구 오류가 아니라 Claude의 추론 계층 내부에서 깨지기 때문에 디버깅이 더 어렵습니다.

가장 흔한 네 가지 실패 유형은 다음과 같습니다.

이 중 어느 것도 당신 잘못이 아닙니다. 모두 문서화된 버그이며, 일부는 GitHub에 몇 달째 열린 상태로 남아 있습니다.

해결법 1: 권한 설정 확인하기

가장 흔한 문제: settings.json 안의 permissions 블록이 자신도 모르게 WebSearch를 막고 있는 경우입니다.

1단계: 설정 파일 찾기

cat ~/.claude/settings.json

2단계: 다음 패턴이 있는지 확인하기

문제가 되는 경우 — Edit(*) 가 WebSearch를 막음:

{
  "permissions": {
    "allow": ["Edit(*)"],
    "deny": []
  }
}

allow 목록 안의 Edit(*) 와일드카드는 Claude Code가 모든 WebSearch 호출마다 권한을 요구하게 만들 수 있고, 일부 버전에서는 조용히 거부되기도 합니다.

수정 예시:

{
  "permissions": {
    "allow": [
      "Edit(*)",
      "WebSearch(*)",
      "WebFetch(*)"
    ],
    "deny": []
  }
}

3단계: 충돌하는 deny 규칙 확인하기

deny 블록에 WebSearch(**) 또는 WebFetch(**) 가 있다면 삭제하세요.

// ❌ 이 설정은 웹 검색을 막고 플러그인 로딩도 깨뜨립니다
{
  "permissions": {
    "deny": ["WebSearch(**)", "WebFetch(**)"]
  }
}

알려진 GitHub 버그 (#11812): WebFetch/WebSearch를 permissions.deny 에 추가하면 모든 플러그인이 로드되지 않습니다. 설정을 바꾼 뒤 플러그인이 망가졌다면 이게 원인일 가능성이 큽니다.

4단계: 설정 다시 반영하기

# 변경 사항을 적용하려면 Claude Code 세션을 재시작하세요
# settings.json 변경에는 hot-reload가 없습니다

해결법 2: Permissionless 모드 사용해 보기 (단, 주의점 있음)

권한 설정이 문제가 아니라면 Claude Code를 permissionless 모드로 실행해 보세요.

claude --permissionless

하지만 GitHub 이슈 #21091을 주의하세요: permissionless 모드에서도 WebSearch가 거부될 수 있습니다. 이는 Claude Max 구독자에게도 영향을 주는 것으로 확인된 버그입니다. 이 문제에 해당한다면 우회 방법은 다음과 같습니다.

# 내장 WebSearch를 완전히 우회하고 MCP 서버를 사용하세요
# (해결법 3 참고)

해결법 3: 웹 검색용 MCP 서버 사용하기

내장 WebSearch가 고장 났을 때 Claude Code 안에서 가장 안정적인 해결책은 웹 검색을 외부에서 처리하는 MCP 서버를 사용하는 것입니다.

옵션 A: Brave Search MCP Server

# Brave Search MCP server 설치
claude mcp add brave-search -- npx -y @anthropic/mcp-server-brave-search \
  --env BRAVE_API_KEY=your_brave_api_key_here

Brave Search MCP server는 Anthropic이 유지 관리하며, 사실상 가장 “공식”에 가까운 웹 검색 도구입니다. Claude Code가 파싱하고 인용할 수 있는 구조화된 검색 결과를 반환합니다.

장점:

• Anthropic이 유지 관리
• 구조화되어 있어 인용하기 쉬운 결과
• 무료 요금제 제공 (월 2,000회 쿼리)

단점:

• 별도의 Brave API 키 필요
• 전체 페이지 콘텐츠가 아니라 검색 스니펫만 제공
• 호출할 때마다 약 4,000토큰의 도구 설명 오버헤드 발생

옵션 B: Tavily Search MCP Server

claude mcp add tavily -- npx -y @tavily/mcp-server \
  --env TAVILY_API_KEY=your_tavily_key_here

Tavily는 AI 에이전트 검색에 특화되어 있으며, 스니펫뿐 아니라 전체 페이지 콘텐츠도 반환합니다.

옵션 C: SerpAPI MCP Server

claude mcp add serpapi -- npx -y @serpapi/mcp-server \
  --env SERPAPI_API_KEY=your_serpapi_key_here

SerpAPI는 Google 검색 결과를 제공합니다. 가장 유연하지만 비용도 가장 높습니다.

해결법 4: 가장 안정적인 대안 — AnyCap 웹 검색 (MCP 없음, 권한 설정 없음)

추천 대상: 디버깅 없이 웹 검색이 매번 그냥 작동하기를 원하는 개발자.

Claude Code 내장 WebSearch의 진짜 문제는 단순히 버그만이 아닙니다. 더 근본적인 문제는 아키텍처입니다. 웹 검색이 모델 내부 도구로 구현되어 있기 때문에 Claude의 컨텍스트 창, 권한 모델, 레이트 리밋을 함께 공유합니다. 이 중 하나라도 문제가 생기면 웹 검색도 같이 실패합니다.

AnyCap은 다른 방식을 사용합니다. 웹 검색을 Claude Code 컨텍스트 바깥의 외부 기능으로 실행하며, 자체 엔진, 자체 API 키, 자체 출력 포맷을 사용합니다. Claude Code는 그저 일반 CLI 도구처럼 호출하면 됩니다.

설정 방법 (30초 — 이미지 생성과 동일한 설치 방식)

# 이미 이미지 생성을 위해 AnyCap을 설치했다면 건너뛰세요
npx -y skills add anycap-ai/anycap -a claude-code -y
curl -fsSL https://anycap.ai/install.sh | sh
anycap login

Claude Code에서 웹 검색하기

기본 웹 검색:

anycap web search \
  --query "Claude Code web search permission denied fix" \
  --results 5

출력 예시:

Searching for: Claude Code web search permission denied fix...
Found 5 results:

1. GitHub Issue #21091 — WebSearch Tool Blocked Despite Permissionless Mode
   https://github.com/anthropics/claude-code/issues/21091
   Relevant: Confirmed bug — WebSearch denied even with --permissionless flag

2. Reddit r/ClaudeCode — How to grant Claude Code web search permission
   https://reddit.com/r/ClaudeCode/comments/1kouc2z/
   Relevant: Edit(*) in settings.json blocks WebSearch

3-5. [additional results]

Claude Code는 이 결과를 직접 읽고 인용할 수 있습니다. 권한 팝업도 없고, “Did 0 searches”도 없고, settings.json 디버깅도 필요 없습니다.

심층 리서치 (다중 소스):

anycap web deep-research \
  --topic "State of AI coding agents 2026" \
  --depth 3 \
  --output research.md

이 명령은 여러 검색 쿼리를 실행하고, 링크를 따라가며, 콘텐츠를 추출하고, 출처가 포함된 리서치 문서를 만듭니다. 이 모든 작업은 Claude Code의 컨텍스트 창 바깥에서 수행됩니다.

실시간 웹 크롤링 (전체 페이지 콘텐츠):

anycap web crawl \
  --url "https://docs.anthropic.com/en/docs/claude-code/web-search" \
  --format markdown

페이지 전체를 markdown으로 반환하므로 Claude Code가 파싱하고 참조할 수 있습니다.

이 방식이 잘 안 깨지는 이유

비교: 어떤 해결법을 써야 할까?

FAQ

왜 Claude Code는 “Did 0 searches”라고 표시하나요?

이것은 Claude Code의 내부 WebSearch 도구가 실행되었지만 결과를 반환하지 않는 알려진 버그입니다. 브라우저에서는 결과가 나오는 검색어에도 발생할 수 있습니다. 원인은 API 요청의 blocked_domains: [] 파라미터가 잘못 형성되기 때문입니다. 가장 안정적인 해결책은 외부 검색 도구를 사용하는 것입니다 (해결법 3 또는 해결법 4).

Claude Code 웹 검색은 무료인가요?

예. Claude Code의 내장 WebSearch는 Claude 구독 (Pro, Max, Team)에 포함되어 있습니다. 하지만 MCP 기반 대안 (해결법 3)은 일반적으로 별도의 API 키와 별도 요금이 필요합니다. AnyCap 웹 검색은 사용량 기반 과금이며, 무료 크레딧 5달러부터 시작합니다.

Claude Code에서 Google Search를 사용할 수 있나요?

내장 WebSearch 도구로는 불가능합니다. 이 도구는 Anthropic 자체 검색 백엔드를 사용하기 때문입니다. Google 검색 결과가 꼭 필요하다면 SerpAPI MCP server (해결법 3, 옵션 C) 또는 여러 소스를 집계한 결과를 반환하는 AnyCap의 anycap web search를 사용하세요.

왜 claude.ai에서는 웹 검색이 되는데 Claude Code에서는 안 되나요?

Claude Code와 claude.ai는 서로 다른 웹 검색 구현을 사용합니다. claude.ai 웹 인터페이스는 더 성숙한 검색 통합을 갖고 있지만, Claude Code의 터미널 기반 WebSearch는 비교적 새로운 도구라 아직 알려진 버그가 있습니다. 웹에서는 되는데 터미널에서는 안 된다면, Claude Code 전용 문제를 겪는 것이며 대개 권한 설정 또는 “Did 0 searches” 버그가 원인입니다.

Claude Code가 오프라인이어도 AnyCap 웹 검색은 작동하나요?

아니요. 하지만 다른 방법도 마찬가지입니다. AnyCap 웹 검색은 검색 엔진에 실제 HTTP 요청을 보내기 때문에 인터넷 연결이 필요합니다. 대신 필요하지 않은 것은 Claude Code의 WebSearch 도구가 정상 동작하는지, 권한이 승인되었는지, 레이트 리밋 여유가 있는지입니다. 인터넷만 있으면 AnyCap 검색은 작동합니다.

다음 단계

• Claude Code 튜토리얼: 0에서 첫 번째 정상 세션까지 (2026) — AnyCap 연동을 포함한 전체 설정 가이드
• 왜 Claude Code에는 실제 워크플로를 위한 웹 검색이 필요한가 — 코딩 에이전트에 실시간 웹 접근이 필요한 이유
• Claude Code로 이미지 생성하는 방법 (2026) — 웹 검색과 함께 이미지 생성 기능 추가하기
• 왜 Claude Code에는 이미지 생성이 필요한가 — 시각 기능 공백 설명
• Claude Code Agent SDK 가이드 (2026) — Claude를 활용한 멀티 에이전트 오케스트레이션
• 터미널 에이전트 대결: Claude Code vs Codex vs Windsurf — Claude Code를 다른 터미널 에이전트와 비교