[Claude Code 스킬] 웹 도구(WebSearch·WebFetch) — 검색은 사서, 읽기는 요약 조교 | DAKER 커뮤니티

무엇: 검색은 사서, 읽기는 요약 조교

Claude Code에는 웹을 다루는 내장 도구가 두 개 있습니다. WebSearch는 질문을 Anthropic 검색 백엔드로 보내 결과의 제목과 URL 목록만 돌려받습니다 — 페이지 내용은 가져오지 않습니다. 한 번 호출에 내부적으로 최대 8회까지 검색을 정제하며, 도서관 사서처럼 "그 주제 자료는 여기 있어요"라고 서가 위치만 알려주는 역할입니다.

WebFetch는 URL과 "무엇을 뽑아낼지" 서술한 추출 프롬프트를 받아, 페이지를 가져와 HTML을 Markdown으로 변환한 뒤 소형 고속 모델이 그 프롬프트에 대한 답만 생성해 돌려줍니다. 즉 Claude가 받는 것은 원문이 아니라 "요약 조교가 책을 읽고 내 질문에만 답해준 것"입니다. 이 설계는 의도된 손실(lossy by design)입니다 — 긴 페이지 전체를 컨텍스트에 들이붓지 않는 대신, 추출 프롬프트가 조리개 역할은 합니다. 그래서 두 도구는 짝으로 움직입니다: WebSearch가 URL을 찾고, WebFetch가 읽습니다.

언제 쓰나

지식 컷오프 이후의 정보가 필요할 때가 대표적입니다. 라이브러리 최신 버전의 API 변경, 방금 나온 프레임워크 릴리스 노트, 에러 메시지의 알려진 해결책 등을 "추측하지 말고 찾아서" 반영하게 할 수 있습니다. "최신 문서를 확인하고 수정해줘"라고 하면 Claude가 알아서 WebSearch로 찾고 WebFetch로 읽습니다.

반대로 차단해야 할 때도 명확합니다. 사내 코드가 외부로 새어나가는 경로를 줄이고 싶거나, 신뢰할 수 없는 웹 페이지 내용이 컨텍스트로 흘러들어오는 것(프롬프트 인젝션 표면)을 막고 싶다면 permissions의 deny에 WebSearch와 WebFetch를 넣어 도구 자체를 끌 수 있습니다.

사용법

일상 사용은 자연어로 충분합니다:

# 검색 -> 읽기 파이프라인은 Claude가 알아서 구성
> Next.js 15의 캐싱 기본값 변경을 공식 문서에서 확인하고
  우리 fetch 코드가 영향을 받는지 점검해줘

# 특정 페이지를 지목해 읽히기
> https://code.claude.com/docs/en/hooks 를 읽고
  PreToolUse 훅의 입력 JSON 필드만 정리해줘

도메인 접근 제어는 settings.json의 permissions로 합니다. WebFetch는 도메인 단위 지정이 가능하고, WebSearch는 지정자 없이 통째로만 허용/차단합니다:

{
  "permissions": {
    "allow": [
      "WebFetch(domain:code.claude.com)",
      "WebFetch(domain:*.github.com)"
    ],
    "deny": [
      "WebFetch(domain:pastebin.com)",
      "WebSearch"
    ]
  }
}

default 모드에서 WebFetch는 처음 보는 도메인마다 승인 프롬프트를 띄우되, 공식 문서류의 사전 승인 도메인 내장 목록은 프롬프트 없이 통과합니다. 명시적 WebFetch(domain:...) 규칙(deny/ask/allow)은 이 내장 목록보다 우선하므로, 내장 허용 도메인도 원하면 차단할 수 있습니다. 리다이렉트가 다른 호스트로 향하면 따라가지 않고 목적지를 알려줘 Claude가 두 번째 호출로 명시적으로 이동합니다.

팁

1) "페이지에 없다"를 그대로 믿지 마세요. WebFetch 결과는 추출 프롬프트가 물어본 것만 담깁니다. "그 내용은 없다"는 답이 오면 실제로 없는 게 아니라 프롬프트가 안 물어봤을 가능성이 있습니다. 더 구체적인 프롬프트로 재요청하거나, 가공 없는 원본이 필요하면 "curl로 원문을 받아서 봐줘"라고 하세요(Bash 경유라 변환·추출 단계를 건너뜁니다). 같은 URL 재호출은 15분간 캐시되어 빠릅니다.

2) 검색 범위는 도메인 필터로, 다른 검색엔진은 MCP로. WebSearch는 allowed_domains(이 호스트들만) 또는 blocked_domains(제외) 중 하나로 범위를 좁힐 수 있습니다 — "공식 문서 사이트에서만 검색해줘"처럼 자연어로 지시하면 됩니다. 검색 백엔드 자체는 교체 불가이므로, 다른 검색 제공자를 쓰려면 검색 도구를 노출하는 MCP 서버를 연결하는 방식입니다. 참고로 샌드박스의 네트워크 허용목록은 별도 체계라, WebFetch 허용 도메인이라도 샌드박스 안 curl이 접근하려면 sandbox 설정에 따로 등록해야 합니다.

출처

Claude Code 공식 문서 — Tools reference (WebFetch·WebSearch tool behavior)
Claude Code 공식 문서 — Configure permissions (WebFetch 도메인 규칙)
Claude Platform 문서 — Web search tool

Redirecting to [Claude Code 스킬] 웹 도구(WebSearch·WebFetch) — 검색은 사서, 읽기는 요약 조교 | DAKER 커뮤니티...