Tìm kiếm trên web

Công cụ web_search tìm kiếm trên web bằng nhà cung cấp đã cấu hình của bạn và trả về kết quả. Kết quả được lưu vào bộ nhớ đệm theo truy vấn trong 15 phút (có thể cấu hình).

OpenClaw cũng bao gồm x_search cho bài đăng X (trước đây là Twitter) và web_fetch để tải URL gọn nhẹ. Trong giai đoạn này, web_fetch vẫn chạy cục bộ, trong khi web_search và x_search có thể dùng xAI Responses ở bên dưới.

# Bắt đầu nhanh

openclaw configure --section web

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

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

# Chọn nhà cung cấp

# So sánh nhà cung cấp

# Tự động phát hiện

# Tìm kiếm web OpenAI gốc

Các mô hình OpenAI Responses trực tiếp tự động dùng công cụ web_search được lưu trữ của OpenAI khi tìm kiếm web của OpenClaw được bật và không ghim nhà cung cấp được quản lý nào. Đây là hành vi do nhà cung cấp sở hữu trong Plugin OpenAI đi kèm và chỉ áp dụng cho lưu lượng API OpenAI gốc, không áp dụng cho URL cơ sở proxy tương thích OpenAI hoặc tuyến Azure. Đặt tools.web.search.provider thành nhà cung cấp khác như brave để giữ công cụ web_search được quản lý cho các mô hình OpenAI, hoặc đặt tools.web.search.enabled: false để tắt cả tìm kiếm được quản lý và tìm kiếm OpenAI gốc.

# Tìm kiếm web Codex gốc

Các mô hình có khả năng Codex có thể tùy chọn dùng công cụ web_search Responses gốc của nhà cung cấp thay vì hàm web_search được quản lý của OpenClaw.

• Cấu hình trong tools.web.search.openaiCodex
• Chỉ kích hoạt cho các mô hình có khả năng Codex (openai-codex/* hoặc các nhà cung cấp dùng api: "openai-codex-responses")
• web_search được quản lý vẫn áp dụng cho các mô hình không phải Codex
• mode: "cached" là thiết lập mặc định và được khuyến nghị
• tools.web.search.enabled: false tắt cả tìm kiếm được quản lý và tìm kiếm gốc

{
  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",
          },
        },
      },
    },
  },
}

Nếu tìm kiếm Codex gốc được bật nhưng mô hình hiện tại không có khả năng Codex, OpenClaw giữ hành vi web_search được quản lý thông thường.

# An toàn mạng

Các lệnh gọi nhà cung cấp web_search được quản lý dùng đường dẫn fetch được bảo vệ của OpenClaw. Với các máy chủ API nhà cung cấp đáng tin cậy, OpenClaw cho phép câu trả lời DNS fake-IP của Surge, Clash và sing-box trong 198.18.0.0/15 và fc00::/7 chỉ cho tên máy chủ của nhà cung cấp đó. Các đích riêng tư, loopback, link-local và metadata khác vẫn bị chặn.

Việc cho phép tự động này không áp dụng cho các URL web_fetch tùy ý. Với web_fetch, chỉ bật rõ ràng tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange và tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange khi proxy đáng tin cậy của bạn sở hữu các dải tổng hợp đó.

# Thiết lập tìm kiếm web

Danh sách nhà cung cấp trong tài liệu và luồng thiết lập được sắp xếp theo bảng chữ cái. Tự động phát hiện giữ một thứ tự ưu tiên riêng.

Nếu không đặt provider, OpenClaw kiểm tra nhà cung cấp theo thứ tự này và dùng nhà cung cấp đầu tiên đã sẵn sàng:

Nhà cung cấp dựa trên API trước:

1. Brave -- BRAVE_API_KEY hoặc plugins.entries.brave.config.webSearch.apiKey (thứ tự 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY hoặc plugins.entries.minimax.config.webSearch.apiKey (thứ tự 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey, GEMINI_API_KEY, hoặc models.providers.google.apiKey (thứ tự 20)
4. Grok -- XAI_API_KEY hoặc plugins.entries.xai.config.webSearch.apiKey (thứ tự 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY hoặc plugins.entries.moonshot.config.webSearch.apiKey (thứ tự 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY hoặc plugins.entries.perplexity.config.webSearch.apiKey (thứ tự 50)
7. Firecrawl -- FIRECRAWL_API_KEY hoặc plugins.entries.firecrawl.config.webSearch.apiKey (thứ tự 60)
8. Exa -- EXA_API_KEY hoặc plugins.entries.exa.config.webSearch.apiKey; plugins.entries.exa.config.webSearch.baseUrl tùy chọn ghi đè endpoint Exa (thứ tự 65)
9. Tavily -- TAVILY_API_KEY hoặc plugins.entries.tavily.config.webSearch.apiKey (thứ tự 70)

Sau đó là các phương án dự phòng không cần khóa:

10. DuckDuckGo -- phương án dự phòng HTML không cần khóa, không cần tài khoản hoặc khóa API (thứ tự 100)
11. Ollama Web Search -- phương án dự phòng không cần khóa thông qua máy chủ Ollama cục bộ đã cấu hình của bạn khi có thể truy cập và đã đăng nhập bằng ollama signin; có thể dùng lại xác thực bearer của nhà cung cấp Ollama khi máy chủ cần, và có thể gọi tìm kiếm trực tiếp https://ollama.com khi được cấu hình bằng OLLAMA_API_KEY (thứ tự 110)
12. SearXNG -- SEARXNG_BASE_URL hoặc plugins.entries.searxng.config.webSearch.baseUrl (thứ tự 200)

Nếu không phát hiện nhà cung cấp nào, hệ thống sẽ quay về Brave (bạn sẽ nhận được lỗi thiếu khóa nhắc bạn cấu hình một khóa).

# Cấu hình

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

Cấu hình riêng theo nhà cung cấp (khóa API, URL cơ sở, chế độ) nằm trong plugins.entries.<plugin>.config.webSearch.*. Gemini cũng có thể tái sử dụng models.providers.google.apiKey và models.providers.google.baseUrl làm phương án dự phòng có độ ưu tiên thấp hơn sau cấu hình tìm kiếm web chuyên dụng của nó và GEMINI_API_KEY. Xem các trang nhà cung cấp để biết ví dụ.

tools.web.search.provider được xác thực dựa trên các id nhà cung cấp tìm kiếm web được khai báo bởi manifest Plugin đi kèm và đã cài đặt, cùng với các Plugin nhà cung cấp có thể cài đặt đã biết. Lỗi gõ sai như "brvae" sẽ làm xác thực cấu hình thất bại thay vì âm thầm quay về tự động phát hiện. Nếu nhà cung cấp đã cấu hình được biết đến nhưng Plugin sở hữu không khả dụng, OpenClaw vẫn giữ khởi động ổn định và báo một cảnh báo để bạn có thể chạy openclaw doctor --fix nhằm cài đặt hoặc bật Plugin đó. Hành vi cảnh báo tương tự áp dụng cho bằng chứng Plugin đã cũ, chẳng hạn một khối plugins.entries.<plugin> còn sót lại sau khi gỡ cài đặt Plugin bên thứ ba.

Việc chọn nhà cung cấp dự phòng cho web_fetch là riêng biệt:

• chọn bằng tools.web.fetch.provider
• hoặc bỏ qua trường đó và để OpenClaw tự động phát hiện nhà cung cấp web-fetch sẵn sàng đầu tiên từ thông tin xác thực có sẵn
• web_fetch không chạy trong sandbox có thể dùng các nhà cung cấp Plugin đã cài đặt có khai báo contracts.webFetchProviders; các lần fetch trong sandbox chỉ dùng nhà cung cấp đi kèm
• hiện nay nhà cung cấp web-fetch đi kèm là Firecrawl, được cấu hình trong plugins.entries.firecrawl.config.webFetch.*

Khi bạn chọn Kimi trong openclaw onboard hoặc openclaw configure --section web, OpenClaw cũng có thể hỏi:

• vùng API Moonshot (https://api.moonshot.ai/v1 hoặc https://api.moonshot.cn/v1)
• mô hình tìm kiếm web Kimi mặc định (mặc định là kimi-k2.6)

Đối với x_search, hãy cấu hình plugins.entries.xai.config.xSearch.*. Nó dùng cùng phương án dự phòng XAI_API_KEY như tìm kiếm web Grok. Cấu hình cũ tools.web.x_search.* được openclaw doctor --fix tự động di chuyển. Khi bạn chọn Grok trong openclaw onboard hoặc openclaw configure --section web, OpenClaw cũng có thể cung cấp bước thiết lập x_search tùy chọn với cùng khóa. Đây là một bước tiếp theo riêng trong luồng Grok, không phải một lựa chọn nhà cung cấp tìm kiếm web cấp cao riêng biệt. Nếu bạn chọn nhà cung cấp khác, OpenClaw sẽ không hiển thị lời nhắc x_search.

# Lưu khóa API

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

export BRAVE_API_KEY="YOUR_KEY"

# Tham số công cụ

# x_search

x_search truy vấn các bài đăng X (trước đây là Twitter) bằng xAI và trả về câu trả lời do AI tổng hợp kèm trích dẫn. Nó chấp nhận truy vấn ngôn ngữ tự nhiên và các bộ lọc có cấu trúc tùy chọn. OpenClaw chỉ bật công cụ x_search xAI tích hợp trên yêu cầu phục vụ lệnh gọi công cụ này.

# Cấu hình 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
          },
        },
      },
    },
  },
}

x_search gửi bài đến <baseUrl>/responses khi plugins.entries.xai.config.xSearch.baseUrl được đặt. Nếu trường đó bị bỏ qua, nó quay về plugins.entries.xai.config.webSearch.baseUrl, rồi đến tools.web.search.grok.baseUrl cũ, và cuối cùng là endpoint xAI công khai.

# Tham số x_search

# Ví dụ 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",
});

# Ví dụ

// 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"],
});

# Hồ sơ công cụ

Nếu bạn dùng hồ sơ công cụ hoặc danh sách cho phép, hãy thêm web_search, x_search, hoặc group:web:

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

# Liên quan

• Web Fetch -- fetch một URL và trích xuất nội dung dễ đọc
• Trình duyệt web -- tự động hóa trình duyệt đầy đủ cho các trang nặng JS
• Tìm kiếm Grok -- Grok làm nhà cung cấp web_search
• Tìm kiếm web Ollama -- tìm kiếm web không cần khóa thông qua máy chủ Ollama của bạn