웹 도구

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

web_search — Brave Search API, Google 검색 그라운딩이 적용된 Gemini, Grok, Kimi 또는 Perplexity Search API를 사용한 웹 검색.
web_fetch — HTTP 가져오기 + 가독성 추출 (HTML → 마크다운/텍스트).

이것은 브라우저 자동화가 아닙니다. JS 기반 사이트나 로그인이 필요한 경우 브라우저 도구를 사용하세요.

작동 방식

web_search는 설정된 프로바이더를 호출하고 결과를 반환합니다.
결과는 쿼리별로 15분간 캐시됩니다(설정 가능).
web_fetch는 일반 HTTP GET을 수행하고 가독성 있는 콘텐츠를 추출합니다 (HTML → 마크다운/텍스트). JavaScript를 실행하지 않습니다.
web_fetch는 기본적으로 활성화되어 있습니다(명시적으로 비활성화하지 않는 한).

프로바이더별 상세 설정은 Brave Search 설정과 Perplexity Search 설정을 참고하세요.

검색 프로바이더 선택

프로바이더	결과 형태	프로바이더별 필터	참고	API 키
Brave Search API	스니펫이 포함된 구조화된 결과	`country`, `language`, `ui_lang`, 시간	Brave `llm-context` 모드 지원	`BRAVE_API_KEY`
Gemini	AI 합성 답변 + 인용	—	Google Search 그라운딩 사용	`GEMINI_API_KEY`
Grok	AI 합성 답변 + 인용	—	xAI 웹 그라운딩 응답 사용	`XAI_API_KEY`
Kimi	AI 합성 답변 + 인용	—	Moonshot 웹 검색 사용	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
Perplexity Search API	스니펫이 포함된 구조화된 결과	`country`, `language`, 시간, `domain_filter`	콘텐츠 추출 제어 지원; OpenRouter는 Sonar 호환 경로 사용	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`

자동 감지

위 표는 알파벳 순입니다. provider가 명시적으로 설정되지 않으면 런타임 자동 감지가 다음 순서로 프로바이더를 확인합니다:

Brave — BRAVE_API_KEY 환경 변수 또는 tools.web.search.apiKey 설정
Gemini — GEMINI_API_KEY 환경 변수 또는 tools.web.search.gemini.apiKey 설정
Grok — XAI_API_KEY 환경 변수 또는 tools.web.search.grok.apiKey 설정
Kimi — KIMI_API_KEY / MOONSHOT_API_KEY 환경 변수 또는 tools.web.search.kimi.apiKey 설정
Perplexity — PERPLEXITY_API_KEY, OPENROUTER_API_KEY 또는 tools.web.search.perplexity.apiKey 설정

키가 발견되지 않으면 Brave로 폴백합니다(키 누락 오류와 함께 설정 안내가 표시됩니다).

런타임 SecretRef 동작:

웹 도구 SecretRef는 게이트웨이 시작/리로드 시 원자적으로 해석됩니다.
자동 감지 모드에서 OpenClaw는 선택된 프로바이더 키만 해석합니다. 선택되지 않은 프로바이더 SecretRef는 선택될 때까지 비활성 상태입니다.
선택된 프로바이더 SecretRef가 해석되지 않고 프로바이더 환경 폴백이 없으면 시작/리로드가 즉시 실패합니다.

웹 검색 설정

openclaw configure --section web으로 API 키를 설정하고 프로바이더를 선택하세요.

Brave Search

brave.com/search/api에서 Brave Search API 계정을 생성합니다
대시보드에서 Search 플랜을 선택하고 API 키를 생성합니다.
openclaw configure --section web을 실행하여 키를 설정에 저장하거나, 환경에 BRAVE_API_KEY를 설정합니다.

각 Brave 플랜에는 월 $5 무료 크레딧(갱신)이 포함됩니다. Search 플랜은 1,000 요청당 $5이므로 크레딧으로 월 1,000 쿼리를 커버합니다. 예상치 못한 요금을 피하려면 Brave 대시보드에서 사용 제한을 설정하세요. 현재 플랜과 가격은 Brave API 포털을 참고하세요.

Perplexity Search

perplexity.ai/settings/api에서 Perplexity 계정을 생성합니다
대시보드에서 API 키를 생성합니다
openclaw configure --section web을 실행하여 키를 설정에 저장하거나, 환경에 PERPLEXITY_API_KEY를 설정합니다.

레거시 Sonar/OpenRouter 호환을 위해 OPENROUTER_API_KEY를 설정하거나, tools.web.search.perplexity.apiKey에 sk-or-... 키를 설정하세요. tools.web.search.perplexity.baseUrl 또는 model을 설정해도 Perplexity가 chat-completions 호환 경로로 전환됩니다.

자세한 내용은 Perplexity Search API Docs를 참고하세요.

키 저장 위치

설정 사용: openclaw configure --section web을 실행합니다. 프로바이더별 설정 경로에 키를 저장합니다:

Brave: tools.web.search.apiKey
Gemini: tools.web.search.gemini.apiKey
Grok: tools.web.search.grok.apiKey
Kimi: tools.web.search.kimi.apiKey
Perplexity: tools.web.search.perplexity.apiKey

이 필드 모두 SecretRef 객체를 지원합니다.

환경 변수 사용: 게이트웨이 프로세스 환경에 프로바이더 환경 변수를 설정합니다:

Brave: BRAVE_API_KEY
Gemini: GEMINI_API_KEY
Grok: XAI_API_KEY
Kimi: KIMI_API_KEY 또는 MOONSHOT_API_KEY
Perplexity: PERPLEXITY_API_KEY 또는 OPENROUTER_API_KEY

게이트웨이 설치의 경우, ~/.openclaw/.env(또는 서비스 환경)에 넣으세요. 환경 변수를 참고하세요.

설정 예시

Brave Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // BRAVE_API_KEY 설정 시 선택 사항 // pragma: allowlist secret
      },
    },
  },
}

Brave LLM Context 모드:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // BRAVE_API_KEY 설정 시 선택 사항 // pragma: allowlist secret
        brave: {
          mode: "llm-context",
        },
      },
    },
  },
}

llm-context는 표준 Brave 스니펫 대신 그라운딩을 위한 추출된 페이지 청크를 반환합니다. 이 모드에서도 country와 language / search_lang은 작동하지만, ui_lang, freshness, date_after, date_before는 거부됩니다.

Perplexity Search:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // PERPLEXITY_API_KEY 설정 시 선택 사항
        },
      },
    },
  },
}

Perplexity via OpenRouter / Sonar 호환:

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "<openrouter-api-key>", // OPENROUTER_API_KEY 설정 시 선택 사항
          baseUrl: "https://openrouter.ai/api/v1",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

Gemini 사용 (Google Search 그라운딩)

Gemini 모델은 내장 Google Search 그라운딩을 지원하며, 실시간 Google 검색 결과에 기반한 AI 합성 답변과 인용을 반환합니다.

Gemini API 키 발급

Google AI Studio에 접속합니다
API 키를 생성합니다
게이트웨이 환경에 GEMINI_API_KEY를 설정하거나, tools.web.search.gemini.apiKey를 설정합니다

Gemini 검색 설정

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // API 키 (GEMINI_API_KEY 설정 시 선택 사항)
          apiKey: "AIza...",
          // 모델 (기본값 "gemini-2.5-flash")
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

환경 변수 대안: 게이트웨이 환경에 GEMINI_API_KEY를 설정합니다. 게이트웨이 설치의 경우, ~/.openclaw/.env에 넣으세요.

참고

Gemini 그라운딩의 인용 URL은 Google 리다이렉트 URL에서 직접 URL로 자동 해석됩니다.
리다이렉트 해석은 SSRF 가드 경로(HEAD + 리다이렉트 확인 + http/https 검증)를 사용하여 최종 인용 URL을 반환합니다.
리다이렉트 해석은 엄격한 SSRF 기본값을 사용하므로 프라이빗/내부 대상으로의 리다이렉트가 차단됩니다.
기본 모델(gemini-2.5-flash)은 빠르고 비용 효율적입니다. 그라운딩을 지원하는 모든 Gemini 모델을 사용할 수 있습니다.

web_search

설정된 프로바이더로 웹을 검색합니다.

요구 사항

tools.web.search.enabled가 false가 아니어야 합니다 (기본값: 활성)
선택한 프로바이더의 API 키:
- Brave: BRAVE_API_KEY 또는 tools.web.search.apiKey
- Gemini: GEMINI_API_KEY 또는 tools.web.search.gemini.apiKey
- Grok: XAI_API_KEY 또는 tools.web.search.grok.apiKey
- Kimi: KIMI_API_KEY, MOONSHOT_API_KEY 또는 tools.web.search.kimi.apiKey
- Perplexity: PERPLEXITY_API_KEY, OPENROUTER_API_KEY 또는 tools.web.search.perplexity.apiKey
위의 모든 프로바이더 키 필드는 SecretRef 객체를 지원합니다.

설정

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

도구 매개변수

모든 매개변수는 별도로 표시되지 않는 한 Brave 및 네이티브 Perplexity Search API에서 작동합니다.

Perplexity의 OpenRouter / Sonar 호환 경로는 query와 freshness만 지원합니다. tools.web.search.perplexity.baseUrl / model을 설정하거나, OPENROUTER_API_KEY를 사용하거나, sk-or-... 키를 설정하면 Search API 전용 필터에서 명시적 오류가 반환됩니다.

매개변수	설명
`query`	검색 쿼리 (필수)
`count`	반환할 결과 수 (1-10, 기본값: 5)
`country`	2자리 ISO 국가 코드 (예: “US”, “DE”)
`language`	ISO 639-1 언어 코드 (예: “en”, “de”)
`freshness`	시간 필터: `day`, `week`, `month` 또는 `year`
`date_after`	이 날짜 이후의 결과 (YYYY-MM-DD)
`date_before`	이 날짜 이전의 결과 (YYYY-MM-DD)
`ui_lang`	UI 언어 코드 (Brave 전용)
`domain_filter`	도메인 허용/차단 목록 배열 (Perplexity 전용)
`max_tokens`	총 콘텐츠 예산, 기본값 25000 (Perplexity 전용)
`max_tokens_per_page`	페이지당 토큰 제한, 기본값 2048 (Perplexity 전용)

예시:

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

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

// 날짜 범위 검색
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// 도메인 필터링 (Perplexity 전용)
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// 도메인 제외 (Perplexity 전용)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// 더 많은 콘텐츠 추출 (Perplexity 전용)
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

Brave llm-context 모드가 활성화되면 ui_lang, freshness, date_after, date_before는 지원되지 않습니다. 이러한 필터에는 Brave web 모드를 사용하세요.

web_fetch

URL을 가져와 가독성 있는 콘텐츠를 추출합니다.

web_fetch 요구 사항

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

web_fetch 설정

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        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,
        },
      },
    },
  },
}

web_fetch 도구 매개변수

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

참고:

web_fetch는 먼저 Readability(주요 콘텐츠 추출)를 사용하고, 이후 Firecrawl(설정된 경우)을 사용합니다. 둘 다 실패하면 오류를 반환합니다.
Firecrawl 요청은 봇 우회 모드를 사용하며 기본적으로 결과를 캐시합니다.
Firecrawl SecretRef는 Firecrawl이 활성(tools.web.fetch.enabled !== false 및 tools.web.fetch.firecrawl.enabled !== false)일 때만 해석됩니다.
Firecrawl이 활성이고 SecretRef가 해석되지 않으며 FIRECRAWL_API_KEY 폴백도 없으면 시작/리로드가 즉시 실패합니다.
web_fetch는 기본적으로 Chrome 유사 User-Agent와 Accept-Language를 전송합니다. 필요 시 userAgent를 재정의하세요.
web_fetch는 프라이빗/내부 호스트명을 차단하고 리다이렉트를 재확인합니다(maxRedirects로 제한).
maxChars는 tools.web.fetch.maxCharsCap로 제한됩니다.
web_fetch는 파싱 전에 다운로드된 응답 본문 크기를 tools.web.fetch.maxResponseBytes로 제한합니다. 초과된 응답은 잘리며 경고가 포함됩니다.
web_fetch는 최선 노력 추출입니다. 일부 사이트는 브라우저 도구가 필요합니다.
키 설정 및 서비스 세부 정보는 Firecrawl을 참고하세요.
응답은 반복 가져오기를 줄이기 위해 캐시됩니다(기본 15분).
도구 프로파일/허용 목록을 사용하는 경우, web_search/web_fetch 또는 group:web을 추가하세요.
API 키가 없으면 web_search는 문서 링크가 포함된 짧은 설정 힌트를 반환합니다.