Tools
Tavily
Tavily는 AI 애플리케이션을 위해 설계된 검색 API입니다. OpenClaw는 이를 두 가지 방식으로 노출합니다.
- 범용 검색 도구의
web_search제공자로 - 명시적 Plugin 도구인
tavily_search및tavily_extract로
Tavily는 구성 가능한 검색 깊이, 주제 필터링, 도메인 필터, AI 생성 답변 요약, URL 콘텐츠 추출(JavaScript로 렌더링된 페이지 포함)을 통해 LLM 소비에 최적화된 구조화된 결과를 반환합니다.
| 속성 | 값 |
|---|---|
| Plugin ID | tavily |
| 인증 | TAVILY_API_KEY 또는 config apiKey |
| 기본 URL | https://api.tavily.com (기본값) |
| 번들 도구 | tavily_search, tavily_extract |
시작하기
API 키 받기
tavily.com에서 Tavily 계정을 만든 다음, 대시보드에서 API 키를 생성합니다.
Plugin 및 제공자 구성
{ plugins: { entries: { tavily: { enabled: true, config: { webSearch: { apiKey: "tvly-...", // optional if TAVILY_API_KEY is set baseUrl: "https://api.tavily.com", }, }, }, }, }, tools: { web: { search: { provider: "tavily", }, }, },}검색 실행 확인
아무 에이전트에서나 web_search를 트리거하거나, tavily_search를 직접 호출합니다.
도구 참조
tavily_search
범용 web_search 대신 Tavily 전용 검색 제어가 필요할 때 사용합니다.
| 매개변수 | 유형 | 제약 조건 / 기본값 | 설명 |
|---|---|---|---|
query |
string | 필수 | 검색 쿼리 문자열입니다. 400자 미만으로 유지하세요. |
search_depth |
enum | basic (기본값), advanced |
advanced는 더 느리지만 관련성이 더 높습니다. |
topic |
enum | general (기본값), news, finance |
주제 계열로 필터링합니다. |
max_results |
integer | 1-20 | 결과 수입니다. |
include_answer |
boolean | 기본값 false |
Tavily AI 생성 답변 요약을 포함합니다. |
time_range |
enum | day, week, month, year |
최신순 기준으로 결과를 필터링합니다. |
include_domains |
string array | (없음) | 이 도메인의 결과만 포함합니다. |
exclude_domains |
string array | (없음) | 이 도메인의 결과를 제외합니다. |
검색 깊이의 트레이드오프:
| 깊이 | 속도 | 관련성 | 가장 적합한 용도 |
|---|---|---|---|
basic |
더 빠름 | 높음 | 범용 쿼리(기본값). |
advanced |
더 느림 | 가장 높음 | 정밀 조사 및 사실 확인. |
tavily_extract
하나 이상의 URL에서 정제된 콘텐츠를 추출할 때 사용합니다. JavaScript로 렌더링된 페이지를 처리하며, 대상 추출을 위한 쿼리 중심 청킹을 지원합니다.
| 매개변수 | 유형 | 제약 조건 / 기본값 | 설명 |
|---|---|---|---|
urls |
string array | 필수, 1-20 | 콘텐츠를 추출할 URL입니다. |
query |
string | (선택 사항) | 추출된 청크를 이 쿼리와의 관련성 기준으로 다시 정렬합니다. |
extract_depth |
enum | basic (기본값), advanced |
JS가 많은 페이지, SPA 또는 동적 테이블에는 advanced를 사용하세요. |
chunks_per_source |
integer | 1-5; query 필요 |
URL당 반환되는 청크 수입니다. query 없이 설정하면 오류가 발생합니다. |
include_images |
boolean | 기본값 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_extract는 설정 오류를 발생시킵니다.
사용자 지정 기본 URL
프록시를 통해 Tavily를 연결하는 경우 plugins.entries.tavily.config.webSearch.baseUrl을 재정의합니다. 기본값은 https://api.tavily.com입니다.
`chunks_per_source`에는 `query`가 필요함
tavily_extract는 query 없이 chunks_per_source를 전달하는 호출을 거부합니다. Tavily는 쿼리 관련성을 기준으로 청크의 순위를 매기므로, 쿼리가 없으면 이 매개변수는 의미가 없습니다.