웹 검색 도구

개요

web_search 도구는 에이전트가 인터넷 검색을 수행하여 최신 정보를 가져올 수 있게 한다. 10개의 검색 프로바이더를 지원하며, 15분 캐시를 통해 중복 검색 비용을 절감한다.

지원 프로바이더

프로바이더	특징
Brave	프라이버시 중심, 자체 인덱스
DuckDuckGo	API 키 불필요, 무료
Exa	시맨틱 검색 특화
Firecrawl	웹 스크래핑 + 검색
Gemini	Google AI 기반 검색
Grok	xAI 기반 검색
Kimi	중국어 검색 특화
Perplexity	AI 요약 검색
SearXNG	셀프 호스팅 메타 검색
Tavily	AI 에이전트 최적화 검색

프로바이더 자동 감지

API 키가 설정된 프로바이더를 자동으로 감지하여 우선순위에 따라 사용한다. 수동으로 프로바이더를 지정할 수도 있다.

{
  "tools": {
    "webSearch": {
      "provider": "tavily",
      "apiKey": "${TAVILY_API_KEY}"
    }
  }
}

검색 파라미터

파라미터	타입	설명	기본값
`query`	string	검색 쿼리	(필수)
`count`	number	결과 수	10
`country`	string	국가 코드 (kr, us 등)	자동
`language`	string	언어 코드 (ko, en 등)	자동
`freshness`	string	최신성 필터 (day, week, month)	없음

캐시

검색 결과는 15분간 캐시된다. 동일한 쿼리를 반복 실행해도 캐시 기간 내에는 새로운 API 호출이 발생하지 않는다.

[검색 요청] → 캐시 확인 → 히트 → 캐시 결과 반환
                        → 미스 → 프로바이더 API 호출 → 결과 캐시 → 반환

특수 검색 도구

x_search (트위터 검색)

트위터/X 게시물을 검색하는 전용 도구이다.

x_search("OpenClaw 릴리즈")

web_fetch (URL 조회)

특정 URL의 콘텐츠를 가져온다. 검색이 아닌 직접 URL 접근에 사용한다.

web_fetch("https://example.com/api-docs")

설정

CLI를 통한 대화형 설정

openclaw configure --section web

프로바이더 선택, API 키 입력, 기본 파라미터를 대화형으로 설정한다.

설정 파일 직접 수정

{
  "tools": {
    "webSearch": {
      "provider": "brave",
      "apiKey": "${BRAVE_API_KEY}",
      "defaults": {
        "count": 5,
        "country": "kr",
        "language": "ko"
      }
    }
  }
}

사용 예시

에이전트가 검색을 수행하는 흐름:

사용자가 “최근 OpenClaw 업데이트 알려줘"라고 요청
에이전트가 web_search("OpenClaw latest update 2026") 호출
검색 결과에서 관련 정보 추출
필요시 web_fetch로 상세 페이지 조회
요약하여 사용자에게 응답