Tìm kiếm trên web

web_search tìm kiếm trên web bằng nhà cung cấp đã cấu hình và trả về kết quả đã chuẩn hóa, đượ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 tích hợp x_search cho các bài đăng trên X (trước đây là Twitter) và web_fetch để tải URL theo cách gọn nhẹ. web_fetch luôn chạy cục bộ; web_search định tuyến qua xAI Responses khi Grok là nhà cung cấp, còn x_search luôn sử dụng xAI Responses.

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

Cấu trúc kết quả

web_search chuẩn hóa mọi nhà cung cấp Plugin tích hợp sẵn và bên ngoài tại ranh giới công cụ lõi. Bên gọi nhận chính xác một trong các cấu trúc đóng sau:

type WebSearchOutput =  | {      kind: "error";      provider: string;      error: "provider_error";      message: string;      docs?: string;    }  | {      kind: "results";      provider: string;      query: string;      count: number;      tookMs?: number;      results: Array<{        title: string;        url: string;        snippet?: string;        published?: string;        siteName?: string;      }>;      externalContent: {        untrusted: true;        source: "web_search";        wrapped: true;        provider: string;      };      cached?: true;    }  | {      kind: "answer";      provider: string;      query: string;      tookMs?: number;      content: string;      citations?: Array<{ url: string; title?: string }>;      externalContent: {        untrusted: true;        source: "web_search";        wrapped: true;        provider: string;      };      cached?: true;    }  | {      kind: "raw";      provider: string;      data: unknown;    };

Các nhà cung cấp có cấu trúc sử dụng kind: "results"; các nhà cung cấp tổng hợp sử dụng kind: "answer". Các nhà cung cấp Plugin bên ngoài có tải trọng không khớp với cả hai cấu trúc sẽ được chuyển nguyên trạng dưới dạng kind: "raw" để đảm bảo khả năng tương thích. Các trường dành riêng cho nhà cung cấp như điểm thô, đoạn trích, tìm kiếm liên quan, độ lệch trích dẫn nội tuyến, mã định danh mô hình hoặc siêu dữ liệu phiên sẽ không được chuyển tiếp trong các nhánh đã chuẩn hóa. Hãy sử dụng công cụ chuyên dụng của nhà cung cấp khi phản hồi phong phú hơn của họ là một phần trong quy trình làm việc của bạn.

externalContent.wrapped: true là một dấu hiệu tin cậy mà chính ranh giới này bảo đảm là đúng: văn bản của nhà cung cấp (title, snippet, siteName, content, tiêu đề trích dẫn, message lỗi) được loại bỏ mọi dòng bao bọc có sẵn và được bao bọc lại đúng một lần tại ranh giới lõi, nên không siêu dữ liệu nào của nhà cung cấp có thể giả mạo dấu hiệu này. query luôn là truy vấn được yêu cầu, URL trích dẫn và kết quả phải phân tích được dưới dạng http(s), published phải có dạng ngày ISO, URL được xuất ở dạng chuẩn hóa, và một tải trọng chứa khóa error luôn được báo cáo dưới dạng kind: "error", với mã thô của nhà cung cấp được giữ nguyên bên trong thông báo đã bao bọc. Các tải trọng chuyển tiếp thô giữ nguyên mọi dấu hiệu do nhà cung cấp đặt.

Tự động phát hiện

Danh sách nhà cung cấp trong tài liệu và các luồng thiết lập được sắp xếp theo thứ tự bảng chữ cái. Tính năng tự động phát hiện sử dụng một thứ tự ưu tiên cố định riêng biệt và chỉ chọn nhà cung cấp cần thông tin xác thực (requiresCredential !== false) khi tìm thấy thông tin đó đã được cấu hình. Nếu không đặt provider, OpenClaw sẽ kiểm tra các nhà cung cấp theo thứ tự sau và sử dụng nhà cung cấp sẵn sàng đầu tiên:

Các 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 -- OAuth xAI, 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 sẽ ghi đè điểm cuối Exa (thứ tự 65)
9. Tavily -- TAVILY_API_KEY hoặc plugins.entries.tavily.config.webSearch.apiKey (thứ tự 70)
10. Parallel -- API Parallel Search trả phí qua PARALLEL_API_KEY hoặc plugins.entries.parallel.config.webSearch.apiKey; plugins.entries.parallel.config.webSearch.baseUrl tùy chọn sẽ ghi đè điểm cuối (thứ tự 75)

Sau đó là các nhà cung cấp điểm cuối đã cấu hình:

11. SearXNG -- SEARXNG_BASE_URL hoặc plugins.entries.searxng.config.webSearch.baseUrl (thứ tự 200)

Các nhà cung cấp không cần khóa như Parallel Search (Miễn phí), DuckDuckGo, Ollama Web Search và Codex Hosted Search không bao giờ được chọn qua tính năng tự động phát hiện, mặc dù chúng có giá trị thứ tự nội bộ. Chúng chỉ được sử dụng khi bạn chọn rõ ràng bằng tools.web.search.provider hoặc thông qua openclaw configure --section web. OpenClaw không gửi các truy vấn web_search được quản lý đến nhà cung cấp không cần khóa chỉ vì chưa cấu hình nhà cung cấp dựa trên API nào.

Các mô hình OpenAI Responses là một ngoại lệ: khi chưa đặt tools.web.search.provider, chúng sử dụng tính năng tìm kiếm web gốc của OpenAI thay vì các nhà cung cấp được quản lý ở trên (xem bên dưới). Đặt tools.web.search.provider thành parallel-free (hoặc một nhà cung cấp khác) để thay vào đó định tuyến chúng qua đường dẫn được quản lý.

Tìm kiếm web gốc của OpenAI

Các mô hình OpenAI Responses trực tiếp (api: "openai-responses", nhà cung cấp openai, không có URL cơ sở hoặc có URL cơ sở API OpenAI chính thức) tự động sử dụng công cụ web_search được OpenAI lưu trữ 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 thuộc sở hữu của nhà cung cấp trong Plugin OpenAI đi kèm và không áp dụng cho các URL cơ sở proxy tương thích với OpenAI hoặc các tuyến Azure. Đặt tools.web.search.provider thành một nhà cung cấp khác như brave để duy trì 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ý lẫn tìm kiếm gốc của OpenAI.

Tìm kiếm web gốc của Codex

Runtime app-server của Codex tự động sử dụng công cụ web_search được Codex lưu trữ khi tìm kiếm web được bật và không có nhà cung cấp được quản lý nào được chọn. Tìm kiếm gốc được lưu trữ và công cụ động web_search được quản lý của OpenClaw loại trừ lẫn nhau, do đó tìm kiếm được quản lý không thể bỏ qua các giới hạn miền gốc. OpenClaw sử dụng công cụ được quản lý khi tìm kiếm được lưu trữ không khả dụng, bị tắt rõ ràng hoặc được thay thế bằng một nhà cung cấp được quản lý đã chọn. OpenClaw giữ tiện ích mở rộng web.run độc lập của Codex ở trạng thái tắt (features.standalone_web_search: false) vì lưu lượng app-server trong môi trường sản xuất từ chối không gian tên web do người dùng định nghĩa của tiện ích này.

• Cấu hình tìm kiếm gốc trong tools.web.search.openaiCodex
• Đặt tools.web.search.provider: "codex" để cung cấp Codex Hosted Search làm nhà cung cấp web_search được quản lý cho bất kỳ mô hình cha nào. Mỗi lệnh gọi chạy một lượt app-server Codex tạm thời có giới hạn và sẽ thất bại nếu Codex không phát ra một mục webSearch được lưu trữ.
• mode: "cached" là tùy chọn ưu tiên mặc định, nhưng Codex phân giải nó thành quyền truy cập bên ngoài trực tiếp cho các lượt app-server không bị hạn chế; đặt "live" để yêu cầu rõ ràng quyền truy cập trực tiếp
• Đặt tools.web.search.provider thành một nhà cung cấp được quản lý như brave để sử dụng web_search được quản lý của OpenClaw thay thế
• Đặt tools.web.search.openaiCodex.enabled: false để từ chối sử dụng tìm kiếm được Codex lưu trữ; các nhà cung cấp được quản lý khác vẫn khả dụng
• Việc hạn chế bề mặt công cụ gốc của Codex cũng duy trì web_search được quản lý ở trạng thái khả dụng
• Khi đặt allowedDomains, cơ chế dự phòng được quản lý tự động sẽ đóng khi lỗi nếu tìm kiếm được lưu trữ không khả dụng, để không thể bỏ qua danh sách cho phép gốc
• Các lượt chạy chỉ dùng LLM và đã tắt công cụ sẽ tắt cả tìm kiếm gốc lẫn tìm kiếm được quản lý
• tools.web.search.enabled: false tắt cả tìm kiếm được quản lý lẫn tìm kiếm gốc

Các thay đổi lâu dài đối với chính sách tìm kiếm Codex hiệu lực sẽ khởi động một luồng liên kết mới để luồng app-server đã tải không thể tiếp tục giữ quyền truy cập tìm kiếm được lưu trữ đã lỗi thời. Các giới hạn tạm thời theo từng lượt sử dụng một luồng bị hạn chế tạm thời và bảo toàn liên kết hiện có để tiếp tục lại sau này.

Lưu lượng OpenAI ChatGPT Responses trực tiếp cũng có thể sử dụng công cụ web_search được OpenAI lưu trữ. Đường dẫn riêng biệt đó vẫn yêu cầu chủ động bật thông qua tools.web.search.openaiCodex.enabled: true và chỉ áp dụng cho các mô hình openai/* đủ điều kiện sử dụng api: "openai-chatgpt-responses".

{  tools: {    web: {      search: {        enabled: true,        // Tùy chọn: cũng sử dụng Codex Hosted Search từ các mô hình cha không phải Codex.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

Đối với các runtime và nhà cung cấp không hỗ trợ tìm kiếm Codex gốc, Codex có thể sử dụng cơ chế dự phòng web_search được quản lý thông qua không gian tên công cụ động của OpenClaw. Hãy sử dụng một nhà cung cấp được quản lý rõ ràng khi bạn cần các biện pháp kiểm soát mạng riêng cho từng nhà cung cấp của OpenClaw thay vì tìm kiếm do Codex lưu trữ.

Việc chọn provider: "codex" sẽ bật Plugin codex đi kèm và sử dụng cùng các giới hạn tools.web.search.openaiCodex được trình bày ở trên. Trước tiên, hãy xác thực app-server Codex bằng openclaw models auth login --provider openai. Tác nhân cha có thể sử dụng bất kỳ mô hình hoặc runtime nào; chỉ worker tìm kiếm có giới hạn chạy qua Codex.

An toàn mạng

Các lệnh gọi nhà cung cấp web_search HTTP được quản lý sử dụng đường dẫn tìm nạp có bảo vệ của OpenClaw, với phạm vi giới hạn ở tên máy chủ riêng của nhà cung cấp hiện tại. Chỉ đối với tên máy chủ đó, OpenClaw cho phép các phản hồi DNS IP giả của Surge, Clash và sing-box trong 198.18.0.0/15 và fc00::/7. Các đích riêng tư, loopback, link-local và siêu dữ liệu khác vẫn bị chặn. Codex Hosted Search là ngoại lệ: worker có giới hạn của nó ủy quyền quyền truy cập mạng cho công cụ web_search được lưu trữ của app-server Codex.

Quyền cho phép tự động này không áp dụng cho các URL web_fetch tùy ý. Đối 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 đó.

Cấu hình

{  tools: {    web: {      search: {        enabled: true, // mặc định: true        provider: "brave", // hoặc bỏ qua để tự động phát hiện        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

Cấu hình riêng cho từng 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 các phương án dự phòng có mức ưu tiên thấp hơn sau cấu hình tìm kiếm web chuyên biệt và GEMINI_API_KEY của nó. Xem các trang về nhà cung cấp để biết ví dụ. Grok cũng có thể tái sử dụng hồ sơ xác thực OAuth xAI từ openclaw models auth login --provider xai --method oauth; cấu hình khóa API vẫn là phương án dự phòng.

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. Lỗi đánh máy như "brvae" khiến quá trình xác thực cấu hình thất bại thay vì âm thầm chuyển sang tự động phát hiện. Nếu một nhà cung cấp đã cấu hình chỉ còn bằng chứng Plugin lỗi thời, chẳng hạn như khối plugins.entries.<plugin> còn sót lại sau khi gỡ cài đặt Plugin bên thứ ba, OpenClaw vẫn duy trì khả năng khởi động ổn định và báo cáo cảnh báo để bạn có thể cài đặt lại Plugin hoặc chạy openclaw doctor --fix nhằm dọn dẹp cấu hình lỗi thời.

Việc chọn nhà cung cấp dự phòng 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 tìm nạp web sẵn sàng đầu tiên từ thông tin xác thực đã cấu hình
• web_fetch không chạy trong sandbox có thể sử dụng các nhà cung cấp Plugin đã cài đặt khai báo contracts.webFetchProviders; các lượt tìm nạp trong sandbox cho phép nhà cung cấp đi kèm và các bản cài đặt Plugin chính thức đã xác minh, nhưng loại trừ Plugin bên ngoài của bên thứ ba
• Plugin Firecrawl chính thức là thành phần đóng góp webFetchProviders đi kèm duy nhất hiện nay, đượ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ể yêu cầu:

• khu vực 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ó sử dụng cùng hồ sơ xác thực xAI như trò chuyện hoặc thông tin xác thực XAI_API_KEY / tìm kiếm web của Plugin được Grok web search sử dụng. Cấu hình tools.web.x_search.* cũ đượ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 cung cấp quy trình thiết lập x_search tùy chọn với cùng thông tin xác thực ngay sau khi hoàn tất thiết lập Grok. Đây là một bước tiếp theo riêng biệt trong đường dẫn Grok, không phải lựa chọn nhà cung cấp tìm kiếm web cấp cao nhất riêng biệt. Nếu bạn chọn một nhà cung cấp khác, OpenClaw sẽ không hiển thị lời nhắc x_search.

Lưu trữ 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 trên X (trước đây là Twitter) bằng xAI và trả về các câu trả lời do AI tổng hợp kèm trích dẫn. Công cụ này chấp nhận truy vấn bằng ngôn ngữ tự nhiên và các bộ lọc có cấu trúc tùy chọn. OpenClaw tạo công cụ x_search tích hợp sẵn của xAI theo từng yêu cầu thay vì đăng ký công cụ đó vĩnh viễn, vì vậy công cụ chỉ hoạt động trong lượt thực sự gọi đến nó.

Cấu hình x_search

Khi bỏ qua enabled, x_search chỉ được cung cấp khi nhà cung cấp của mô hình đang hoạt động là xai và thông tin xác thực xAI được phân giải. Đối với mô hình đang hoạt động có nhà cung cấp không phải xAI đã biết, đặt plugins.entries.xai.config.xSearch.enabled thành true để chọn sử dụng xuyên nhà cung cấp. Nếu nhà cung cấp của mô hình đang hoạt động bị thiếu hoặc chưa được phân giải, công cụ vẫn bị ẩn. Đặt enabled thành false để vô hiệu hóa công cụ cho mọi nhà cung cấp. Luôn yêu cầu thông tin xác thực xAI.

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // bắt buộc đối với nhà cung cấp mô hình không phải xAI đã biết            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // tùy chọn, ghi đè webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // tùy chọn nếu đã đặt hồ sơ xác thực xAI hoặc XAI_API_KEY            baseUrl: "https://api.x.ai/v1", // URL cơ sở Responses dùng chung của xAI, tùy chọn          },        },      },    },  },}

x_search gửi yêu cầu POST đến <baseUrl>/responses khi plugins.entries.xai.config.xSearch.baseUrl được đặt. Nếu trường đó bị bỏ qua, công cụ sẽ dự phòng về plugins.entries.xai.config.webSearch.baseUrl, sau đó là điểm cuối xAI công khai (https://api.x.ai/v1).

Tham số x_search

allowed_x_handles và excluded_x_handles loại trừ lẫn nhau.

Ví dụ x_search

await x_search({  query: "công thức nấu bữa tối",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Số liệu trên từng bài đăng: sử dụng URL trạng thái hoặc ID trạng thái chính xác khi có thểawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

Ví dụ

// Tìm kiếm cơ bảnawait web_search({ query: "SDK plugin OpenClaw" }); // Tìm kiếm dành riêng cho tiếng Đứcawait web_search({ query: "xem TV trực tuyến", country: "DE", language: "de" }); // Kết quả gần đây (tuần qua)await web_search({ query: "các tiến bộ về AI", freshness: "week" }); // Phạm vi ngàyawait web_search({  query: "nghiên cứu khí hậu",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Lọc miền (chỉ Perplexity)await web_search({  query: "đánh giá sản phẩm",  domain_filter: ["-reddit.com", "-pinterest.com"],});

Hồ sơ công cụ

Nếu sử 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"],    // hoặc: allow: ["group:web"]  (bao gồm web_search, x_search và web_fetch)  },}

Liên quan

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