Tools
Tavily
Tavily는 AI 애플리케이션용으로 설계된 검색 API입니다. OpenClaw는 이를 두 가지 방식으로 제공합니다.
- 범용 검색 도구의
web_search제공자로 사용 - 명시적인 Plugin 도구인
tavily_search및tavily_extract로 사용
Tavily는 LLM이 사용하기에 최적화된 구조화된 결과를 반환하며, 검색 깊이 설정, 주제 필터링, 도메인 필터, AI 생성 답변 요약, URL 콘텐츠 추출(JavaScript로 렌더링되는 페이지 포함)을 지원합니다.
| 속성 | 값 |
|---|---|
| Plugin ID | tavily |
| 패키지 | @openclaw/tavily-plugin |
| 인증 | TAVILY_API_KEY 환경 변수 또는 apiKey 구성 |
| 기본 URL | https://api.tavily.com(기본값), 재정의하려면 TAVILY_BASE_URL 환경 변수 또는 baseUrl 구성 |
| 시간 제한 | 검색 30초, 추출 60초(기본값) |
| 도구 | tavily_search, tavily_extract |
시작하기
Plugin 설치
openclaw plugins install @openclaw/tavily-pluginAPI 키 발급
tavily.com에서 Tavily 계정을 만든 다음 대시보드에서 API 키를 생성합니다.
Plugin 및 제공자 구성
{ plugins: { entries: { tavily: { enabled: true, config: { webSearch: { apiKey: "tvly-...", // TAVILY_API_KEY가 설정된 경우 선택 사항 baseUrl: "https://api.tavily.com", }, }, }, }, }, tools: { web: { search: { provider: "tavily", }, }, },}검색 실행 확인
에이전트에서 web_search를 실행하거나 tavily_search를 직접 호출합니다.
도구 레퍼런스
tavily_search
범용 web_search 대신 Tavily 전용 검색 제어 옵션이 필요할 때 사용합니다.
| 매개변수 | 유형 | 제약 조건 / 기본값 | 설명 |
|---|---|---|---|
query |
문자열 | 필수 | 검색 쿼리 문자열입니다. |
search_depth |
열거형 | basic(기본값), advanced |
advanced는 느리지만 관련성이 높습니다. |
topic |
열거형 | general(기본값), news, finance |
주제 계열로 필터링합니다. |
max_results |
정수 | 1~20, 기본값 5 |
결과 수입니다. |
include_answer |
불리언 | 기본값 false |
Tavily의 AI 생성 답변 요약을 포함합니다. |
time_range |
열거형 | day, week, month, year |
최신성에 따라 결과를 필터링합니다. |
include_domains |
문자열 배열 | (없음) | 지정한 도메인의 결과만 포함합니다. |
exclude_domains |
문자열 배열 | (없음) | 지정한 도메인의 결과를 제외합니다. |
검색 깊이에 따른 장단점:
| 깊이 | 속도 | 관련성 | 적합한 용도 |
|---|---|---|---|
basic |
빠름 | 높음 | 범용 쿼리(기본값) |
advanced |
느림 | 최고 | 정밀한 조사 및 사실 확인 |
tavily_extract
하나 이상의 URL에서 정제된 콘텐츠를 추출할 때 사용합니다. JavaScript로 렌더링되는 페이지를 처리하며, 원하는 콘텐츠만 추출하도록 쿼리 중심 청킹을 지원합니다.
| 매개변수 | 유형 | 제약 조건 / 기본값 | 설명 |
|---|---|---|---|
urls |
문자열 배열 | 필수, 1~20 | 콘텐츠를 추출할 URL입니다. |
query |
문자열 | (선택 사항) | 이 쿼리와의 관련성에 따라 추출된 청크의 순위를 재조정합니다. |
extract_depth |
열거형 | basic(기본값), advanced |
JS 비중이 높은 페이지, SPA 또는 동적 표에는 advanced를 사용합니다. |
chunks_per_source |
정수 | 1~5, query 필요 |
URL당 반환되는 청크 수입니다. query 없이 설정하면 오류가 발생합니다. |
include_images |
불리언 | 기본값 false |
결과에 이미지 URL을 포함합니다. |
추출 깊이에 따른 장단점:
| 깊이 | 사용 시점 |
|---|---|
basic |
단순한 페이지. 먼저 이 옵션을 사용하세요. |
advanced |
JS로 렌더링되는 SPA, 동적 콘텐츠, 표 |
적합한 도구 선택
| 요구 사항 | 도구 |
|---|---|
| 특수 옵션이 없는 빠른 웹 검색 | web_search |
| 깊이, 주제, AI 답변을 지정한 검색 | tavily_search |
| 특정 URL에서 콘텐츠 추출 | tavily_extract |
고급 구성
API 키 확인 순서
Tavily 클라이언트는 다음 순서로 API 키를 찾습니다.
plugins.entries.tavily.config.webSearch.apiKey(SecretRefs를 통해 확인)- Gateway 환경의
TAVILY_API_KEY
둘 다 없으면 tavily_search와 tavily_extract 모두 설정 오류를 발생시킵니다.
사용자 지정 기본 URL
프록시를 통해 Tavily를 사용하는 경우 plugins.entries.tavily.config.webSearch.baseUrl을 재정의하거나 TAVILY_BASE_URL을 설정합니다. 구성 값이 환경 변수보다 우선합니다. 기본값은 https://api.tavily.com입니다.
`chunks_per_source`에는 `query` 필요
tavily_extract는 query 없이 chunks_per_source를 전달하는 호출을 거부합니다. Tavily는 쿼리 관련성에 따라 청크의 순위를 지정하므로 쿼리가 없으면 이 매개변수는 의미가 없습니다.
