웹 도구

OpenClaw는 두 가지 경량 웹 도구를 제공합니다:

web_search — Brave Search API (기본값) 또는 Perplexity Sonar (직접 또는 OpenRouter를 통해)를 통해 웹 검색.
web_fetch — HTTP 가져오기 + 읽을 수 있는 추출 (HTML → markdown/text).

이들은 브라우저 자동화가 아닙니다. JS가 많은 사이트 또는 로그인의 경우 Browser tool을 사용하세요.

작동 방식

web_search는 구성된 프로바이더를 호출하고 결과를 반환합니다.
- Brave (기본값): 구조화된 결과 반환 (제목, URL, 스니펫).
- Perplexity: 실시간 웹 검색의 인용과 함께 AI 합성 답변 반환.
결과는 쿼리별로 15분간 캐시됩니다 (구성 가능).
web_fetch는 일반 HTTP GET을 수행하고 읽을 수 있는 콘텐츠를 추출합니다 (HTML → markdown/text). JavaScript를 실행하지 않습니다.
web_fetch는 기본적으로 활성화됩니다 (명시적으로 비활성화하지 않는 한).

검색 프로바이더 선택

프로바이더	장점	단점	API 키
Brave (기본값)	빠르고 구조화된 결과, 무료 티어	전통적인 검색 결과	BRAVE_API_KEY
Perplexity	AI 합성 답변, 인용, 실시간	Perplexity 또는 OpenRouter 액세스 필요	OPENROUTER_API_KEY 또는 PERPLEXITY_API_KEY

프로바이더별 세부 사항은 Brave Search setup 및 Perplexity Sonar를 참조하세요.

구성에서 프로바이더를 설정합니다:

{
  tools: {
    web: {
      search: {
        provider: "brave"  // 또는 "perplexity"
      }
    }
  }
}

예제: Perplexity Sonar로 전환 (직접 API):

{
  tools: {
    web: {
      search: {
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...",
          baseUrl: "https://api.perplexity.ai",
          model: "perplexity/sonar-pro"
        }
      }
    }
  }
}

Brave API 키 받기

https://brave.com/search/api/에서 Brave Search API 계정을 만듭니다
대시보드에서 Data for Search 플랜을 선택하고 ("Data for AI"가 아님) API 키를 생성합니다.
openclaw configure --section web을 실행하여 구성에 키를 저장합니다 (권장), 또는 환경에 BRAVE_API_KEY를 설정합니다.

Brave는 무료 티어 및 유료 플랜을 제공합니다; 현재 제한 및 가격은 Brave API 포털을 확인하세요.

키를 설정할 위치 (권장)

권장: openclaw configure --section web을 실행합니다. 키를 ~/.openclaw/openclaw.json의 tools.web.search.apiKey 아래에 저장합니다.

환경 대안: Gateway 프로세스 환경에 BRAVE_API_KEY를 설정합니다. Gateway 설치의 경우 ~/.openclaw/.env에 넣습니다 (또는 서비스 환경). Env vars를 참조하세요.

Perplexity 사용 (직접 또는 OpenRouter를 통해)

Perplexity Sonar 모델에는 내장된 웹 검색 기능이 있으며 인용과 함께 AI 합성 답변을 반환합니다. OpenRouter를 통해 사용할 수 있습니다 (신용 카드 불필요 - 암호화폐/선불 지원).

OpenRouter API 키 받기

https://openrouter.ai/에서 계정을 만듭니다
크레딧을 추가합니다 (암호화폐, 선불 또는 신용 카드 지원)
계정 설정에서 API 키를 생성합니다

Perplexity 검색 설정

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          // API 키 (OPENROUTER_API_KEY 또는 PERPLEXITY_API_KEY가 설정된 경우 선택 사항)
          apiKey: "sk-or-v1-...",
          // Base URL (생략된 경우 키 인식 기본값)
          baseUrl: "https://openrouter.ai/api/v1",
          // 모델 (기본값 perplexity/sonar-pro)
          model: "perplexity/sonar-pro"
        }
      }
    }
  }
}

환경 대안: Gateway 환경에 OPENROUTER_API_KEY 또는 PERPLEXITY_API_KEY를 설정합니다. Gateway 설치의 경우 ~/.openclaw/.env에 넣습니다.

base URL이 설정되지 않은 경우 OpenClaw는 API 키 소스에 따라 기본값을 선택합니다:

PERPLEXITY_API_KEY 또는 pplx-... → https://api.perplexity.ai
OPENROUTER_API_KEY 또는 sk-or-... → https://openrouter.ai/api/v1
알 수 없는 키 형식 → OpenRouter (안전한 대체)

사용 가능한 Perplexity 모델

모델	설명	최적 용도
perplexity/sonar	웹 검색을 사용한 빠른 Q&A	빠른 조회
perplexity/sonar-pro (기본값)	웹 검색을 사용한 다단계 추론	복잡한 질문
perplexity/sonar-reasoning-pro	사고 사슬 분석	심층 연구

web_search

구성된 프로바이더를 사용하여 웹을 검색합니다.

요구 사항

tools.web.search.enabled는 false가 아니어야 합니다 (기본값: 활성화)
선택한 프로바이더의 API 키:
- Brave: BRAVE_API_KEY 또는 tools.web.search.apiKey
- Perplexity: OPENROUTER_API_KEY, PERPLEXITY_API_KEY 또는 tools.web.search.perplexity.apiKey

구성

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // BRAVE_API_KEY가 설정된 경우 선택 사항
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15
      }
    }
  }
}

도구 매개변수

query (필수)
count (1–10; 구성의 기본값)
country (선택 사항): 지역별 결과를 위한 2자 국가 코드 (예: "DE", "US", "ALL"). 생략하면 Brave가 기본 지역을 선택합니다.
search_lang (선택 사항): 검색 결과의 ISO 언어 코드 (예: "de", "en", "fr")
ui_lang (선택 사항): UI 요소의 ISO 언어 코드
freshness (선택 사항, Brave만): 발견 시간별 필터 (pd, pw, pm, py 또는 YYYY-MM-DDtoYYYY-MM-DD)

예제:

// 독일 특정 검색
await web_search({
  query: "TV online schauen",
  count: 10,
  country: "DE",
  search_lang: "de"
});

// 프랑스어 UI로 프랑스어 검색
await web_search({
  query: "actualités",
  country: "FR",
  search_lang: "fr",
  ui_lang: "fr"
});

// 최근 결과 (지난 주)
await web_search({
  query: "TMBG interview",
  freshness: "pw"
});

web_fetch

URL을 가져오고 읽을 수 있는 콘텐츠를 추출합니다.

요구 사항

tools.web.fetch.enabled는 false가 아니어야 합니다 (기본값: 활성화)
선택적 Firecrawl 대체: tools.web.fetch.firecrawl.apiKey 또는 FIRECRAWL_API_KEY를 설정합니다.

구성

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "FIRECRAWL_API_KEY_HERE", // FIRECRAWL_API_KEY가 설정된 경우 선택 사항
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1일)
          timeoutSeconds: 60
        }
      }
    }
  }
}

도구 매개변수

url (필수, http/https만)
extractMode (markdown | text)
maxChars (긴 페이지 잘라내기)

참고:

web_fetch는 먼저 Readability (주요 콘텐츠 추출)를 사용한 다음 Firecrawl (구성된 경우)을 사용합니다. 둘 다 실패하면 도구는 오류를 반환합니다.
Firecrawl 요청은 봇 우회 모드를 사용하고 기본적으로 결과를 캐시합니다.
web_fetch는 기본적으로 Chrome과 유사한 User-Agent 및 Accept-Language를 보냅니다; 필요한 경우 userAgent를 재정의합니다.
web_fetch는 비공개/내부 호스트 이름을 차단하고 리디렉션을 재확인합니다 (maxRedirects로 제한).
web_fetch는 최선의 노력 추출입니다; 일부 사이트는 브라우저 도구가 필요합니다.
키 설정 및 서비스 세부 사항은 Firecrawl을 참조하세요.
응답은 반복 가져오기를 줄이기 위해 캐시됩니다 (기본값 15분).
도구 프로필/허용 목록을 사용하는 경우 web_search/web_fetch 또는 group:web을 추가합니다.
Brave 키가 누락된 경우 web_search는 문서 링크가 있는 짧은 설정 힌트를 반환합니다.