OpenClaw Tavily Web Search 스킬 가이드

OpenClaw Tavily Web Search 스킬 개요

Tavily Web Search 스킬은 OpenClaw를 AI 에이전트 및 LLM 애플리케이션에 특화된 AI 최적화 검색 엔진인 Tavily Search API에 연결합니다. 원시 링크만 반환하는 기존 검색 API와 달리, Tavily는 여러 소스를 분석하고 OpenClaw 에이전트가 즉시 활용할 수 있는 구조화된 관련 콘텐츠를 반환합니다.

Tavily는 100만 명 이상의 개발자가 사용하며 월 1억 건 이상의 요청을 처리합니다. OpenAI, Anthropic, LangChain 및 기타 주요 AI 플랫폼에서 신뢰받고 있습니다. SOC 2 인증, 데이터 무보관 정책, 내장 프롬프트 인젝션 방지 기능을 갖추고 있어 에이전트에 웹 접근 권한을 부여하는 가장 안전한 방법 중 하나입니다.

일반적인 워크플로:

1. OpenClaw에 최신 정보가 필요한 질문을 합니다.
2. 에이전트가 최적화된 쿼리로 Tavily API를 호출합니다.
3. Tavily가 웹을 검색하고 여러 소스에서 관련 콘텐츠를 추출한 후, 인용이 포함된 구조화된 요약을 2초 이내에 반환합니다.

이 스킬은 리서치 작업, 팩트 체킹, 최신 이벤트 조회, 에이전트의 학습 데이터 범위를 넘어서는 정보가 필요한 모든 워크플로에 적합합니다. 프라이버시 중심 쿼리를 위한 Brave Search 스킬 및 리포지토리 문서 리서치를 위한 DeepWiki 스킬과 함께 사용하면 좋습니다.

Tavily Web Search 스킬 사전 요구 사항

Tavily Web Search 스킬을 설치하기 전에 다음을 확인하세요:

• OpenClaw이 설치되어 실행 중 (v1.0+)
• Tavily API 키 — tavily.com에서 가입 (무료 티어 월 1,000 크레딧 포함)
• 스킬 관리를 위한 clawhub CLI 설치 완료

설정 확인:

# OpenClaw 버전 확인
openclaw --version

# Tavily API 키가 설정되어 있는지 확인
echo $TAVILY_API_KEY

추가 소프트웨어 설치는 필요하지 않습니다. 이 스킬은 Tavily의 클라우드 API와 통신하므로 OpenClaw 자체 외에 로컬 종속성이 없습니다.

Tavily Web Search 스킬 설치 방법

한 줄 명령으로 Tavily Web Search 스킬을 설치합니다:

npx clawhub@latest install tavily-web-search

설치 확인:

clawhub list

설치된 스킬 목록에 tavily-web-search가 표시되어야 합니다.

Tavily Web Search 스킬 구성

이 스킬은 인증을 위해 Tavily API 키가 필요합니다. app.tavily.com에서 무료 키를 발급받을 수 있습니다.

API 키 설정

# Tavily API 키를 환경 변수로 설정
export TAVILY_API_KEY=tvly-your-api-key-here

영구적으로 적용하려면 셸 프로필(~/.bashrc, ~/.zshrc 또는 동등한 파일)에 export 라인을 추가하세요.

검색 모드

이 스킬은 필요에 따라 조합할 수 있는 두 가지 검색 깊이와 두 가지 주제 모드를 지원합니다:

| 모드 | 속도 | 범위 | 적합한 용도 | |------|------|------|------------| | Basic | 1-2초 | 양호 | 간단한 팩트 확인, 단순 조회 | | Advanced | 5-10초 | 우수 | 복합 리서치, 포괄적 답변 |

| 주제 | 범위 | 적합한 용도 | |------|------|------------| | General | 전체 기간 웹 콘텐츠 | 상시 유효 주제, 문서, 튜토리얼 | | News | 최근 7일, 뉴스 소스 | 시사 이벤트, 속보, 시장 동향 |

에이전트는 쿼리에 따라 적절한 모드를 자동으로 선택하지만, 프롬프트에 "심층 검색해줘" 또는 "최신 뉴스 검색해줘"를 지정하여 수동으로 변경할 수 있습니다.

중요: API 키를 설정 파일에 하드코딩하거나 버전 관리에 커밋하지 마세요. 환경 변수 또는 1Password와 같은 시크릿 매니저를 사용하세요.

Tavily Web Search 스킬 사용 예시

1. 간단한 팩트 조회

사용자: "Next.js의 최신 안정 버전이 뭐야?"

에이전트가 기본 Tavily 검색을 실행하고, 공식 소스에서 버전 번호를 추출한 후, Next.js 릴리스 노트 링크와 함께 간결한 답변을 반환합니다.

2. 심층 리서치

사용자: "이커머스 사이트에서 서버 사이드 렌더링과 정적 사이트 생성의 장단점을 비교해줘."

에이전트가 고급 검색을 수행하고, 여러 블로그 게시물, 문서 페이지, 사례 연구에서 인사이트를 수집한 후, 각 포인트에 인용을 포함한 구조화된 비교를 반환합니다.

3. 최신 이벤트 및 뉴스

사용자: "이번 주 AI 업계에서 무슨 일이 있었어?"

에이전트가 뉴스 모드로 전환하여 최근 7일간 검색하고, 주요 AI 뉴스 기사 요약과 원본 기사 링크를 반환합니다.

4. 도메인 특화 리서치

사용자: "MDN과 TypeScript 공식 문서에서만 템플릿 리터럴 타입 사용법을 검색해줘."

에이전트가 도메인 필터링을 사용하여 developer.mozilla.org와 typescriptlang.org만 포함시키고, 신뢰할 수 있는 소스에서만 결과를 가져옵니다.

5. 콘텐츠 추출

사용자: "Tavily API 요금 페이지의 전체 콘텐츠를 추출하고 요금제를 요약해줘."

에이전트가 원시 콘텐츠 추출을 사용하여 전체 페이지 콘텐츠를 가져온 후, 각 요금제의 기능과 제한 사항을 구조화된 형태로 정리합니다.

보안 및 모범 사례

Tavily Web Search 스킬 사용 시 다음 가이드라인을 따르세요:

• API 키를 보호하세요. 환경 변수 또는 시크릿 매니저에 저장하세요. 채팅 로그에 공유하거나, Git에 커밋하거나, 클라이언트 측 코드에 노출하지 마세요.
• 검색 결과를 신뢰할 수 없는 입력으로 취급하세요. 웹 콘텐츠에는 부정확하거나 오래되었거나 조작된 정보가 포함될 수 있습니다. 중요한 사실은 항상 여러 소스에서 확인한 후 조치하세요. 일반적인 가이드라인은 안전 체크리스트를 참조하세요.
• 사용량을 모니터링하세요. 무료 티어는 월 1,000 크레딧을 제공합니다. 기본 검색은 1크레딧, 고급 검색은 2크레딧이 소비됩니다. app.tavily.com에서 사용량을 확인하여 예상치 못한 초과를 방지하세요.
• 민감한 쿼리에는 도메인 필터링을 사용하세요. 정확성이 중요한 경우, 포함 도메인 필터를 사용하여 신뢰할 수 있는 도메인(공식 문서, 정부 사이트, 저명한 출판물)으로 결과를 제한하세요.
• 속도 제한에 유의하세요. 반복문에서 빠르게 연속 쿼리를 보내지 마세요. 스킬이 속도 제한을 원활하게 처리하지만, 과도한 요청은 일시적으로 접근이 제한될 수 있습니다.

일반적인 오류 해결

"Invalid API key"

Tavily API 키가 없거나, 형식이 잘못되었거나, 만료되었습니다.

1. 키가 설정되어 있는지 확인: echo $TAVILY_API_KEY
2. tvly-로 시작하는지 확인하세요 — Tavily 키는 항상 이 접두사를 사용합니다.
3. 키가 올바르지만 여전히 실패하면 app.tavily.com에서 새 키를 생성하세요.

"Rate limit exceeded"

현재 요금제의 요청 한도를 초과했습니다.

1. app.tavily.com에서 현재 사용량을 확인하세요.
2. 무료 티어인 경우, 다음 달 1일 월간 초기화를 기다리세요.
3. 더 높은 한도가 필요하면 유료 요금제로 업그레이드하거나, 고급 모드가 필요하지 않은 곳에서는 기본 모드를 사용하여 쿼리를 최적화하세요.

"No results found"

쿼리에 일치하는 결과가 없습니다. 매우 좁은 범위이거나 지나치게 구체적인 검색에서 발생할 수 있습니다.

1. 검색어를 넓히세요 — 지나치게 구체적인 필터를 제거하세요.
2. 도메인 필터링을 사용 중이라면, 대상 도메인에 실제로 관련 콘텐츠가 있는지 확인하세요.
3. 주제가 최근 이벤트가 아니라면 뉴스 모드에서 일반 모드로 전환해보세요.