웹 검색

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 호환 프록시 base 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 응답을 해당 제공자 호스트 이름에 대해서만 허용합니다. 그 밖의 프라이빗, 루프백, 링크 로컬 및 메타데이터 대상은 계속 차단됩니다.

이 자동 허용은 임의의 web_fetch URL에는 적용되지 않습니다. web_fetch의 경우, 신뢰할 수 있는 프록시가 해당 합성 범위를 소유한 경우에만 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 인증을 재사용할 수 있으며, OLLAMA_API_KEY로 구성된 경우 직접 https://ollama.com 검색을 호출할 수 있습니다(순서 110)
12. SearXNG -- SEARXNG_BASE_URL 또는 plugins.entries.searxng.config.webSearch.baseUrl(순서 200)

제공자가 감지되지 않으면 Brave로 폴백합니다(누락된 키 오류가 발생해 키를 구성하라는 메시지가 표시됩니다).

# 구성

{
  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와 알려진 설치 가능 Provider Plugin을 기준으로 검증됩니다. "brvae" 같은 오타는 자동 감지로 조용히 대체되지 않고 구성 검증에 실패합니다. 구성된 Provider가 알려져 있지만 소유 Plugin을 사용할 수 없으면, OpenClaw는 시작을 복원력 있게 유지하고 경고를 보고하므로 openclaw doctor --fix를 실행해 Plugin을 설치하거나 활성화할 수 있습니다. 동일한 경고 동작은 서드 파티 Plugin을 제거한 뒤 남아 있는 plugins.entries.<plugin> 블록 같은 오래된 Plugin 증거에도 적용됩니다.

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.*를 구성하세요. Grok 웹 검색과 동일한 XAI_API_KEY 대체값을 사용합니다. 레거시 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 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 possible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

# 예시

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

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await 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 호스트를 통한 키 없는 웹 검색