OpenClaw Web Tools로 실시간 데이터 검색 및 추출하기

LLM 서비스를 개발하다 보면 모델이 학습하지 못한 최신 정보가 필요할 때가 정말 많아요. 하지만 매번 API를 직접 연동하거나 복잡한 크롤링 로직을 짜는 건 번거로운 일이죠. 실시간 뉴스를 가져오거나 특정 웹사이트의 내용을 분석해야 할 때, 더 간단하고 효율적인 방법이 필요합니다.

OpenClaw는 이런 고민을 해결하기 위해 web_search와 web_fetch라는 두 가지 가벼운 도구를 제공해요. 브라우저 자동화 없이도 빠르게 웹 데이터를 가져올 수 있는 방법을 소개할게요.

필요한 것

OpenClaw 설치 및 설정 완료
지원되는 검색 서비스 중 하나 이상의 API Key:
- Perplexity Search API
- Brave Search API
- Gemini (Google Search grounding)
- Grok (xAI)
- Kimi (Moonshot)
(선택 사항) web_fetch 성능 향상을 위한 Firecrawl API Key

빠른 시작

5분 안에 웹 검색 기능을 설정하고 실행하는 방법이에요.

설정 명령어 실행: 터미널에서 openclaw configure --section web을 입력하세요.
Provider 및 API Key 선택: 안내에 따라 사용하려는 검색 서비스와 API Key를 입력합니다.
환경 변수 등록 (선택 사항): 설정 파일 대신 .env 파일에 BRAVE_API_KEY나 PERPLEXITY_API_KEY를 직접 넣어도 작동해요.
검색 테스트: 설정이 끝나면 바로 web_search를 통해 실시간 정보를 가져올 수 있습니다.

검색 Provider 선택하기

OpenClaw는 다양한 Provider를 지원해요. 상황에 맞는 서비스를 선택해 보세요.

Provider	장점	단점	API Key
Perplexity Search API	빠르고 구조화된 결과, 도메인/언어/지역 필터 제공, 콘텐츠 추출 지원	—	`PERPLEXITY_API_KEY`
Brave Search API	빠르고 구조화된 결과	필터링 옵션이 적음, AI 사용 약관 적용	`BRAVE_API_KEY`
Gemini	Google Search grounding 기반, AI가 합성한 답변 제공	Gemini API Key 필요	`GEMINI_API_KEY`
Grok	xAI의 웹 기반 응답	xAI API Key 필요	`XAI_API_KEY`
Kimi	Moonshot의 웹 검색 기능	Moonshot API Key 필요	`KIMI_API_KEY` / `MOONSHOT_API_KEY`

별도로 Provider를 지정하지 않으면 Brave > Gemini > Kimi > Perplexity > Grok 순서로 사용 가능한 API Key를 자동 감지해서 사용해요.

설정 예시

Perplexity Search 사용 시

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // PERPLEXITY_API_KEY 환경 변수로도 설정 가능
        },
      },
    },
  },
}

Gemini (Google Search grounding) 사용 시

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          apiKey: "AIza...", // GEMINI_API_KEY 환경 변수로도 설정 가능
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

web_search 주요 파라미터

도구를 호출할 때 다음과 같은 파라미터를 사용할 수 있어요.

query: 검색어 (필수)
count: 결과 개수 (1-10, 기본값 5)
country: ISO 국가 코드 (예: “US”, “KR”)
language: ISO 언어 코드 (예: “en”, “ko”)
freshness: 시간 필터 (day, week, month, year)
domain_filter: 도메인 허용/차단 목록 (Perplexity 전용)

사용 예시 (Perplexity 전용 도메인 필터):

await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

web_fetch로 콘텐츠 읽기

web_fetch는 특정 URL의 내용을 HTML에서 마크다운이나 텍스트로 추출해 줍니다. JavaScript를 실행하지 않는 순수 HTTP GET 방식이라 매우 빨라요.

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "YOUR_FIRECRAWL_API_KEY",
        },
      },
    },
  },
}

문제 해결

API Key 오류: API Key가 설정되지 않은 상태에서 web_search를 호출하면 설정 방법과 문서 링크가 포함된 안내 메시지가 반환돼요.
콘텐츠 추출 실패: web_fetch는 기본적으로 Readability를 사용하고 실패 시 Firecrawl(설정된 경우)을 시도해요. 두 방법 모두 실패하면 에러가 발생합니다.
JS 렌더링 필요: web_fetch는 JavaScript를 실행하지 않아요. 리액트나 뷰로 만든 사이트 혹은 로그인이 필요한 페이지는 Browser tool을 사용해야 합니다.
개인 네트워크 접근: web_fetch는 보안을 위해 내부망(private/internal) 호스트네임 접근을 차단합니다.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.