웹 검색

web_search는 구성된 제공자를 사용해 웹을 검색하고 정규화된 결과를 반환하며, 검색어별로 15분 동안 캐시합니다(설정 가능). OpenClaw에는 X(이전 Twitter) 게시물용 x_search와 간단한 URL 가져오기용 web_fetch도 포함되어 있습니다. web_fetch는 항상 로컬에서 실행됩니다. Grok이 제공자인 경우 web_search는 xAI Responses를 통하며, x_search는 항상 xAI Responses를 사용합니다.

빠른 시작

openclaw configure --section web

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

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

제공자 선택

제공자 비교

자동 감지

문서와 설정 흐름의 제공자 목록은 알파벳순입니다. 자동 감지는 별도의 고정된 우선순위를 사용하며, 자격 증명이 필요한 제공자(requiresCredential !== false) 중 구성된 자격 증명을 찾은 경우에만 해당 제공자를 선택합니다. 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 OAuth, 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. Parallel -- PARALLEL_API_KEY 또는 plugins.entries.parallel.config.webSearch.apiKey를 통한 유료 Parallel Search API. 선택적 plugins.entries.parallel.config.webSearch.baseUrl은 엔드포인트를 재정의합니다(순서 75).

그다음 구성된 엔드포인트 제공자:

11. SearXNG -- SEARXNG_BASE_URL 또는 plugins.entries.searxng.config.webSearch.baseUrl(순서 200)

Parallel Search (무료), DuckDuckGo, Ollama Web Search, Codex Hosted Search처럼 키가 필요 없는 제공자는 내부 순서 값이 있어도 자동 감지에서 선택되지 않습니다. tools.web.search.provider로 명시적으로 선택하거나 openclaw configure --section web을 통해 선택한 경우에만 사용됩니다. API 기반 제공자가 구성되지 않았다는 이유만으로 OpenClaw가 관리형 web_search 쿼리를 키가 필요 없는 제공자에게 보내지는 않습니다.

OpenAI Responses 모델은 예외입니다. tools.web.search.provider가 설정되지 않은 동안에는 위의 관리형 제공자 대신 OpenAI의 네이티브 웹 검색을 사용합니다(아래 참조). 관리형 경로를 통해 라우팅하려면 tools.web.search.provider를 parallel-free 또는 다른 제공자로 설정하세요.

OpenAI 네이티브 웹 검색

OpenAI Responses 모델(api: "openai-responses", 공급자 openai, 기본 URL이 없거나 공식 OpenAI API 기본 URL 사용)은 OpenClaw 웹 검색이 활성화되어 있고 관리형 공급자가 고정되지 않은 경우 OpenAI에서 호스팅하는 web_search 도구를 자동으로 사용합니다. 이는 번들 OpenAI Plugin에서 공급자가 소유하는 동작이며, OpenAI 호환 프록시 기본 URL이나 Azure 경로에는 적용되지 않습니다. OpenAI 모델에서 관리형 web_search 도구를 계속 사용하려면 tools.web.search.provider를 brave 같은 다른 공급자로 설정하고, 관리형 검색과 네이티브 OpenAI 검색을 모두 비활성화하려면 tools.web.search.enabled: false를 설정하세요.

네이티브 Codex 웹 검색

Codex 앱 서버 런타임은 웹 검색이 활성화되어 있고 관리형 공급자가 선택되지 않은 경우 Codex에서 호스팅하는 web_search 도구를 자동으로 사용합니다. 네이티브 호스팅 검색과 OpenClaw의 관리형 web_search 동적 도구는 상호 배타적이므로, 관리형 검색으로 네이티브 도메인 제한을 우회할 수 없습니다. OpenClaw는 호스팅 검색을 사용할 수 없거나 명시적으로 비활성화했거나 선택한 관리형 공급자로 대체한 경우 관리형 도구를 사용합니다. 프로덕션 앱 서버 트래픽이 사용자가 정의한 web 네임스페이스를 거부하므로 OpenClaw는 Codex의 독립 실행형 web.run 확장을 비활성화된 상태(features.standalone_web_search: false)로 유지합니다.

• 네이티브 검색은 tools.web.search.openaiCodex에서 구성하세요.
• tools.web.search.provider: "codex"를 설정하면 모든 상위 모델에 대해 Codex 호스팅 검색을 관리형 web_search 공급자로 프로비저닝합니다. 각 호출은 범위가 제한된 임시 Codex 앱 서버 턴을 실행하며, Codex가 호스팅된 webSearch 항목을 내보내지 않으면 실패합니다.
• mode: "cached"가 기본 설정이지만 Codex는 제한 없는 앱 서버 턴에서 이를 실시간 외부 액세스로 해석합니다. 실시간 액세스를 명시적으로 요청하려면 "live"를 설정하세요.
• OpenClaw의 관리형 web_search를 대신 사용하려면 tools.web.search.provider를 brave 같은 관리형 공급자로 설정하세요.
• Codex 호스팅 검색을 사용하지 않으려면 tools.web.search.openaiCodex.enabled: false를 설정하세요. 다른 관리형 공급자는 계속 사용할 수 있습니다.
• Codex 네이티브 도구 표면을 제한해도 관리형 web_search는 계속 사용할 수 있습니다.
• allowedDomains가 설정된 경우 호스팅 검색을 사용할 수 없으면 자동 관리형 대체가 실패 시 차단되므로 네이티브 허용 목록을 우회할 수 없습니다.
• 도구가 비활성화된 LLM 전용 실행에서는 네이티브 검색과 관리형 검색이 모두 비활성화됩니다.
• tools.web.search.enabled: false는 관리형 검색과 네이티브 검색을 모두 비활성화합니다.

영구적으로 적용되는 Codex 검색 정책이 변경되면 이미 로드된 앱 서버 스레드가 오래된 호스팅 검색 액세스를 유지하지 못하도록 새 바인딩 스레드를 시작합니다. 턴별 임시 제한에는 일시적으로 제한된 스레드를 사용하며 나중에 재개할 수 있도록 기존 바인딩을 보존합니다.

직접 OpenAI ChatGPT Responses 트래픽에서도 OpenAI가 호스팅하는 web_search 도구를 사용할 수 있습니다. 이 별도 경로는 tools.web.search.openaiCodex.enabled: true를 통해 선택적으로 활성화해야 하며, api: "openai-chatgpt-responses"를 사용하는 적격 openai/* 모델에만 적용됩니다.

{  tools: {    web: {      search: {        enabled: true,        // 선택 사항: Codex가 아닌 상위 모델에서도 Codex 호스팅 검색을 사용합니다.        provider: "codex",        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 대체 수단을 사용할 수 있습니다. Codex 호스팅 검색 대신 OpenClaw 공급자별 네트워크 제어가 필요한 경우 관리형 공급자를 명시적으로 사용하세요.

provider: "codex"를 선택하면 번들 codex Plugin이 활성화되고 위에 표시된 것과 동일한 tools.web.search.openaiCodex 제한이 사용됩니다. 먼저 openclaw models auth login --provider openai로 Codex 앱 서버를 인증하세요. 상위 에이전트는 어떤 모델이나 런타임이든 사용할 수 있으며, 범위가 제한된 검색 작업자만 Codex를 통해 실행됩니다.

네트워크 안전

관리형 HTTP web_search 공급자 호출은 현재 공급자 자체 호스트 이름으로 범위가 제한된 OpenClaw의 보호된 가져오기 경로를 사용합니다. 해당 호스트 이름에 한해서만 OpenClaw는 198.18.0.0/15와 fc00::/7의 Surge, Clash 및 sing-box 가짜 IP DNS 응답을 허용합니다. 그 밖의 사설, 루프백, 링크 로컬 및 메타데이터 대상은 계속 차단됩니다. Codex 호스팅 검색은 예외입니다. 범위가 제한된 작업자가 네트워크 액세스를 Codex 앱 서버의 호스팅 web_search 도구에 위임합니다.

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

구성

{  tools: {    web: {      search: {        enabled: true, // 기본값: true        provider: "brave", // 또는 자동 감지를 사용하려면 생략        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

공급자별 구성(API 키, 기본 URL, 모드)은 plugins.entries.<plugin>.config.webSearch.* 아래에 있습니다. Gemini는 전용 웹 검색 구성과 GEMINI_API_KEY 다음의 낮은 우선순위 대체 값으로 models.providers.google.apiKey와 models.providers.google.baseUrl도 재사용할 수 있습니다. 예시는 공급자 페이지를 참조하세요. Grok은 openclaw models auth login --provider xai --method oauth에서 생성한 xAI OAuth 인증 프로필도 재사용할 수 있으며, API 키 구성은 계속 대체 수단으로 사용됩니다.

tools.web.search.provider는 번들 및 설치된 Plugin 매니페스트에서 선언한 웹 검색 공급자 ID를 기준으로 검증됩니다. "brvae" 같은 오타는 자동 감지로 조용히 대체되지 않고 구성 검증에 실패합니다. 구성된 공급자에 서드 파티 Plugin 제거 후 남은 plugins.entries.<plugin> 블록 같은 오래된 Plugin 증거만 있는 경우 OpenClaw는 시작 복원력을 유지하고 경고를 보고하므로, Plugin을 다시 설치하거나 openclaw doctor --fix를 실행하여 오래된 구성을 정리할 수 있습니다.

web_fetch 대체 공급자 선택은 별개입니다.

• tools.web.fetch.provider로 선택하세요.
• 또는 해당 필드를 생략하면 OpenClaw가 구성된 자격 증명에서 준비된 첫 번째 웹 가져오기 공급자를 자동으로 감지합니다.
• 샌드박스 외부의 web_fetch는 contracts.webFetchProviders를 선언한 설치된 Plugin 공급자를 사용할 수 있습니다. 샌드박스 내 가져오기는 번들 공급자와 검증된 공식 Plugin 설치를 허용하지만 서드 파티 외부 Plugin은 제외합니다.
• 공식 Firecrawl Plugin은 현재 유일한 번들 webFetchProviders 기여자이며 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는 Grok 설정이 완료된 직후 동일한 자격 증명으로 선택적 x_search 설정도 제공합니다. 이는 별도의 최상위 웹 검색 공급자 선택이 아니라 Grok 경로 내의 별도 후속 단계입니다. 다른 공급자를 선택하면 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 구성

enabled를 생략하면 활성 모델의 제공자가 xai이고 xAI 자격 증명을 확인할 수 있을 때만 x_search가 노출됩니다. 활성 모델의 제공자가 xAI가 아닌 것으로 알려진 경우, 제공자 간 사용을 명시적으로 활성화하려면 plugins.entries.xai.config.xSearch.enabled를 true로 설정하세요. 활성 모델 제공자가 없거나 확인되지 않으면 도구는 계속 숨겨집니다. 모든 제공자에서 비활성화하려면 enabled를 false로 설정하세요. xAI 자격 증명은 항상 필요합니다.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // required for a known non-xAI model provider            model: "grok-4.3",            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 엔드포인트(https://api.x.ai/v1) 순으로 대체 사용합니다.

x_search 매개변수

allowed_x_handles와 excluded_x_handles는 함께 사용할 수 없습니다.

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)  },}

관련 문서

• 웹 가져오기 -- URL을 가져와 읽을 수 있는 콘텐츠 추출
• 웹 브라우저 -- JavaScript 의존도가 높은 사이트를 위한 전체 브라우저 자동화
• Grok 검색 -- web_search 제공자로 사용하는 Grok
• Ollama 웹 검색 -- Ollama 호스트를 통한 키 없는 웹 검색