웹 검색

web_search 도구는 구성된 제공업체를 사용해 웹을 검색하고 결과를 반환합니다. 결과는 쿼리별로 15분 동안 캐시됩니다(구성 가능).

OpenClaw에는 X(이전 Twitter) 게시물을 위한 x_search와 가벼운 URL 가져오기를 위한 web_fetch도 포함되어 있습니다. 이 단계에서는 web_fetch는 로컬에 머무르며, web_search와 x_search는 내부적으로 xAI Responses를 사용할 수 있습니다.

빠른 시작

openclaw configure --section web

await web_search({ query: "OpenClaw plugin SDK" });

await x_search({ query: "dinner recipes" });

제공업체 선택

제공업체 비교

자동 감지

기본 OpenAI 웹 검색

직접 OpenAI Responses 모델은 OpenClaw 웹 검색이 활성화되어 있고 관리형 제공업체가 고정되어 있지 않을 때 OpenAI의 호스팅 web_search 도구를 자동으로 사용합니다. 이는 번들 OpenAI Plugin의 제공업체 소유 동작이며, OpenAI 호환 프록시 기본 URL이나 Azure 경로가 아닌 기본 OpenAI API 트래픽에만 적용됩니다. OpenAI 모델에 대해 관리형 web_search 도구를 유지하려면 tools.web.search.provider를 brave 같은 다른 제공업체로 설정하거나, 관리형 검색과 기본 OpenAI 검색을 모두 비활성화하려면 tools.web.search.enabled: false를 설정하세요.

기본 Codex 웹 검색

Codex 지원 모델은 선택적으로 OpenClaw의 관리형 web_search 함수 대신 제공업체 기본 Responses web_search 도구를 사용할 수 있습니다.

• tools.web.search.openaiCodex 아래에서 구성합니다
• Codex 지원 모델(openai-codex/* 또는 api: "openai-codex-responses"를 사용하는 제공업체)에만 활성화됩니다
• 관리형 web_search는 Codex가 아닌 모델에 계속 적용됩니다
• mode: "cached"가 기본값이자 권장 설정입니다
• tools.web.search.enabled: false는 관리형 검색과 기본 검색을 모두 비활성화합니다

{  tools: {    web: {      search: {        enabled: true,        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

기본 Codex 검색이 활성화되어 있지만 현재 모델이 Codex 지원 모델이 아닌 경우, OpenClaw는 일반 관리형 web_search 동작을 유지합니다.

네트워크 안전

관리형 web_search 제공업체 호출은 OpenClaw의 보호된 fetch 경로를 사용합니다. 신뢰할 수 있는 제공업체 API 호스트의 경우, OpenClaw는 해당 제공업체 호스트 이름에 대해서만 198.18.0.0/15 및 fc00::/7 범위의 Surge, Clash, sing-box fake-IP DNS 응답을 허용합니다. 그 외의 private, loopback, link-local 및 metadata 대상은 계속 차단됩니다.

이 자동 허용은 임의의 web_fetch URL에는 적용되지 않습니다. web_fetch의 경우, 신뢰할 수 있는 프록시가 해당 synthetic 범위를 소유하는 경우에만 tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange 및 tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange를 명시적으로 활성화하세요.

웹 검색 설정

문서와 설정 흐름의 제공업체 목록은 알파벳순입니다. 자동 감지는 별도의 우선순위를 유지합니다.

provider가 설정되어 있지 않으면 OpenClaw는 다음 순서로 제공업체를 확인하고 준비된 첫 번째 제공업체를 사용합니다.

먼저 API 기반 제공업체:

1. Brave -- BRAVE_API_KEY 또는 plugins.entries.brave.config.webSearch.apiKey(순서 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY 또는 plugins.entries.minimax.config.webSearch.apiKey(순서 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY 또는 models.providers.google.apiKey(순서 20)
4. Grok -- XAI_API_KEY 또는 plugins.entries.xai.config.webSearch.apiKey(순서 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY 또는 plugins.entries.moonshot.config.webSearch.apiKey(순서 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY 또는 plugins.entries.perplexity.config.webSearch.apiKey(순서 50)
7. Firecrawl -- FIRECRAWL_API_KEY 또는 plugins.entries.firecrawl.config.webSearch.apiKey(순서 60)
8. Exa -- EXA_API_KEY 또는 plugins.entries.exa.config.webSearch.apiKey; 선택적 plugins.entries.exa.config.webSearch.baseUrl은 Exa 엔드포인트를 재정의합니다(순서 65)
9. Tavily -- TAVILY_API_KEY 또는 plugins.entries.tavily.config.webSearch.apiKey(순서 70)

그 다음 키가 필요 없는 대체 옵션:

10. DuckDuckGo -- 계정이나 API 키가 필요 없는 키 미사용 HTML 대체 옵션(순서 100)
11. Ollama Web Search -- 구성된 로컬 Ollama 호스트에 연결할 수 있고 ollama signin으로 로그인되어 있을 때 이를 통한 키 미사용 대체 옵션입니다. 호스트가 필요로 할 경우 Ollama 제공업체 bearer auth를 재사용할 수 있으며, OLLAMA_API_KEY로 구성된 경우 직접 https://ollama.com 검색을 호출할 수 있습니다(순서 110)
12. SearXNG -- SEARXNG_BASE_URL 또는 plugins.entries.searxng.config.webSearch.baseUrl(순서 200)

제공업체가 감지되지 않으면 Brave로 대체됩니다(구성하라는 missing-key 오류가 표시됩니다).

구성

{  tools: {    web: {      search: {        enabled: true, // default: true        provider: "brave", // or omit for auto-detection        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

Provider별 구성(API 키, 기본 URL, 모드)은 plugins.entries.<plugin>.config.webSearch.* 아래에 있습니다. Gemini는 전용 웹 검색 구성과 GEMINI_API_KEY 이후 더 낮은 우선순위의 대체값으로 models.providers.google.apiKey 및 models.providers.google.baseUrl도 재사용할 수 있습니다. 예시는 Provider 페이지를 참조하세요.

tools.web.search.provider는 번들 및 설치된 Plugin 매니페스트가 선언한 웹 검색 Provider ID와 비교해 검증됩니다. "brvae" 같은 오타는 자동 감지로 조용히 대체되는 대신 구성 검증에 실패합니다. 구성된 Provider에 오래된 Plugin 증거만 있는 경우, 예를 들어 서드 파티 Plugin을 제거한 뒤 남은 plugins.entries.<plugin> 블록이 있는 경우에도 OpenClaw는 시작을 견고하게 유지하고 경고를 보고하므로, Plugin을 다시 설치하거나 openclaw doctor --fix를 실행해 오래된 구성을 정리할 수 있습니다.

web_fetch 대체 Provider 선택은 별도입니다.

• tools.web.fetch.provider로 선택합니다
• 또는 해당 필드를 생략하고 OpenClaw가 사용 가능한 자격 증명에서 준비된 첫 번째 웹 가져오기 Provider를 자동 감지하게 합니다
• 샌드박스되지 않은 web_fetch는 contracts.webFetchProviders를 선언한 설치된 Plugin Provider를 사용할 수 있습니다. 샌드박스된 가져오기는 번들 전용으로 유지됩니다
• 현재 번들 웹 가져오기 Provider는 Firecrawl이며, plugins.entries.firecrawl.config.webFetch.* 아래에서 구성됩니다

openclaw onboard 또는 openclaw configure --section web 중 Kimi를 선택하면 OpenClaw가 다음 항목도 요청할 수 있습니다.

• Moonshot API 리전(https://api.moonshot.ai/v1 또는 https://api.moonshot.cn/v1)
• 기본 Kimi 웹 검색 모델(기본값은 kimi-k2.6)

x_search의 경우 plugins.entries.xai.config.xSearch.*를 구성하세요. 이는 채팅과 동일한 xAI 인증 프로필이나 Grok 웹 검색에서 사용하는 XAI_API_KEY / Plugin 웹 검색 자격 증명을 사용합니다. 기존 tools.web.x_search.* 구성은 openclaw doctor --fix로 자동 마이그레이션됩니다. openclaw onboard 또는 openclaw configure --section web 중 Grok을 선택하면 OpenClaw가 같은 키로 선택적 x_search 설정도 제공할 수 있습니다. 이는 Grok 경로 안의 별도 후속 단계이며, 별도의 최상위 웹 검색 Provider 선택지가 아닙니다. 다른 Provider를 선택하면 OpenClaw는 x_search 프롬프트를 표시하지 않습니다.

API 키 저장

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "YOUR_KEY", // pragma: allowlist secret          },        },      },    },  },}

export BRAVE_API_KEY="YOUR_KEY"

도구 매개변수

x_search

x_search는 xAI를 사용해 X(이전 Twitter) 게시물을 쿼리하고 인용이 포함된 AI 종합 답변을 반환합니다. 자연어 쿼리와 선택적 구조화 필터를 허용합니다. OpenClaw는 이 도구 호출을 처리하는 요청에서만 내장 xAI x_search 도구를 활성화합니다.

x_search 구성

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true,            model: "grok-4-1-fast-non-reasoning",            baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // optional if an xAI auth profile or XAI_API_KEY is set            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL          },        },      },    },  },}

plugins.entries.xai.config.xSearch.baseUrl가 설정되어 있으면 x_search는 <baseUrl>/responses로 게시합니다. 해당 필드가 생략되면 plugins.entries.xai.config.webSearch.baseUrl, 그다음 기존 tools.web.search.grok.baseUrl, 마지막으로 공개 xAI 엔드포인트로 대체됩니다.

x_search 매개변수

x_search 예시

await x_search({  query: "dinner recipes",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Per-post stats: use the exact status URL or status ID when possibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

예시

// Basic searchawait web_search({ query: "OpenClaw plugin SDK" }); // German-specific searchawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Recent results (past week)await web_search({ query: "AI developments", freshness: "week" }); // Date rangeawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Domain filtering (Perplexity only)await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

도구 프로필

도구 프로필 또는 허용 목록을 사용하는 경우 web_search, x_search 또는 group:web을 추가하세요.

{  tools: {    allow: ["web_search", "x_search"],    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)  },}

관련 항목

• Web Fetch -- URL을 가져오고 읽기 쉬운 콘텐츠를 추출합니다
• Web Browser -- JS가 많은 사이트를 위한 전체 브라우저 자동화
• Grok Search -- web_search Provider로 사용하는 Grok
• Ollama Web Search -- Ollama 호스트를 통한 키 없는 웹 검색