Web tools

OpenClaw đi kèm hai công cụ web nhẹ:

web_search — Tìm kiếm web qua Brave Search API (mặc định) hoặc Perplexity Sonar (trực tiếp hoặc qua OpenRouter).
web_fetch — HTTP fetch + trích xuất nội dung dễ đọc (HTML → markdown/text).

Đây không phải là công cụ tự động hóa trình duyệt. Với các trang web nặng JavaScript hoặc cần đăng nhập, các bạn dùng Browser tool nhé.

Cách hoạt động

web_search gọi provider mà các bạn đã cấu hình và trả về kết quả.
- Brave (mặc định): trả về kết quả có cấu trúc (tiêu đề, URL, đoạn trích).
- Perplexity: trả về câu trả lời được AI tổng hợp kèm trích dẫn từ tìm kiếm web thời gian thực.
Kết quả được cache theo query trong 15 phút (có thể cấu hình).
web_fetch thực hiện HTTP GET đơn giản và trích xuất nội dung dễ đọc (HTML → markdown/text). Nó không chạy JavaScript.
web_fetch được bật mặc định (trừ khi tắt rõ ràng).

Chọn search provider

Provider	Ưu điểm	Nhược điểm	API Key
Brave (mặc định)	Nhanh, kết quả có cấu trúc, có gói miễn phí	Kết quả tìm kiếm truyền thống	`BRAVE_API_KEY`
Perplexity	Câu trả lời AI tổng hợp, trích dẫn, real-time	Cần tài khoản Perplexity hoặc OpenRouter	`OPENROUTER_API_KEY` hoặc `PERPLEXITY_API_KEY`

Xem Brave Search setup và Perplexity Sonar để biết chi tiết từng provider.

Đặt provider trong config:

{
  tools: {
    web: {
      search: {
        provider: "brave", // hoặc "perplexity"
      },
    },
  },
}

Ví dụ: chuyển sang Perplexity Sonar (API trực tiếp):

{
  tools: {
    web: {
      search: {
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...",
          baseUrl: "https://api.perplexity.ai",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

Lấy Brave API key

Tạo tài khoản Brave Search API tại https://brave.com/search/api/
Trong dashboard, chọn gói Data for Search (không phải “Data for AI”) và tạo API key.
Chạy openclaw configure --section web để lưu key vào config (khuyên dùng), hoặc đặt BRAVE_API_KEY trong môi trường của các bạn.

Brave cung cấp gói miễn phí cộng các gói trả phí; kiểm tra portal API của Brave để biết giới hạn và giá hiện tại.

Nơi đặt key (khuyên dùng)

Khuyên dùng: chạy openclaw configure --section web. Lệnh này lưu key vào ~/.openclaw/openclaw.json dưới tools.web.search.apiKey.

Cách thay thế qua môi trường: đặt BRAVE_API_KEY trong môi trường process Gateway. Với cài đặt gateway, đặt nó trong ~/.openclaw/.env (hoặc môi trường service của các bạn). Xem Env vars.

Dùng Perplexity (trực tiếp hoặc qua OpenRouter)

Các model Perplexity Sonar có khả năng tìm kiếm web tích hợp sẵn và trả về câu trả lời được AI tổng hợp kèm trích dẫn. Các bạn có thể dùng chúng qua OpenRouter (không cần thẻ tín dụng - hỗ trợ crypto/prepaid).

Lấy OpenRouter API key

Tạo tài khoản tại https://openrouter.ai/
Nạp credits (hỗ trợ crypto, prepaid, hoặc thẻ tín dụng)
Tạo API key trong cài đặt tài khoản

Thiết lập Perplexity search

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          // API key (tùy chọn nếu OPENROUTER_API_KEY hoặc PERPLEXITY_API_KEY đã được đặt)
          apiKey: "sk-or-v1-...",
          // Base URL (mặc định tự động theo key nếu bỏ qua)
          baseUrl: "https://openrouter.ai/api/v1",
          // Model (mặc định là perplexity/sonar-pro)
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

Cách thay thế qua môi trường: đặt OPENROUTER_API_KEY hoặc PERPLEXITY_API_KEY trong môi trường Gateway. Với cài đặt gateway, đặt nó trong ~/.openclaw/.env.

Nếu không đặt base URL, OpenClaw sẽ chọn mặc định dựa trên nguồn API key:

PERPLEXITY_API_KEY hoặc pplx-... → https://api.perplexity.ai
OPENROUTER_API_KEY hoặc sk-or-... → https://openrouter.ai/api/v1
Định dạng key không xác định → OpenRouter (fallback an toàn)

Các model Perplexity có sẵn

Model	Mô tả	Phù hợp cho
`perplexity/sonar`	Hỏi đáp nhanh với tìm kiếm web	Tra cứu nhanh
`perplexity/sonar-pro` (mặc định)	Suy luận nhiều bước với tìm kiếm web	Câu hỏi phức tạp
`perplexity/sonar-reasoning-pro`	Phân tích theo chuỗi suy nghĩ	Nghiên cứu sâu

web_search

Tìm kiếm web bằng provider đã cấu hình.

Yêu cầu

tools.web.search.enabled không được là false (mặc định: enabled)
API key cho provider đã chọn:
- Brave: BRAVE_API_KEY hoặc tools.web.search.apiKey
- Perplexity: OPENROUTER_API_KEY, PERPLEXITY_API_KEY, hoặc tools.web.search.perplexity.apiKey

Config

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // tùy chọn nếu BRAVE_API_KEY đã được đặt
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

Tham số của tool

query (bắt buộc)
count (1–10; mặc định từ config)
country (tùy chọn): mã quốc gia 2 chữ cái cho kết quả theo khu vực (ví dụ: “DE”, “US”, “ALL”). Nếu bỏ qua, Brave chọn khu vực mặc định.
search_lang (tùy chọn): mã ngôn ngữ ISO cho kết quả tìm kiếm (ví dụ: “de”, “en”, “fr”)
ui_lang (tùy chọn): mã ngôn ngữ ISO cho các phần tử UI
freshness (tùy chọn, chỉ Brave): lọc theo thời gian phát hiện (pd, pw, pm, py, hoặc YYYY-MM-DDtoYYYY-MM-DD)

Ví dụ:

// Tìm kiếm theo khu vực Đức
await web_search({
  query: "TV online schauen",
  count: 10,
  country: "DE",
  search_lang: "de",
});

// Tìm kiếm tiếng Pháp với UI tiếng Pháp
await web_search({
  query: "actualités",
  country: "FR",
  search_lang: "fr",
  ui_lang: "fr",
});

// Kết quả gần đây (tuần trước)
await web_search({
  query: "TMBG interview",
  freshness: "pw",
});

web_fetch

Fetch một URL và trích xuất nội dung dễ đọc.

Yêu cầu

tools.web.fetch.enabled không được là false (mặc định: enabled)
Firecrawl fallback tùy chọn: đặt tools.web.fetch.firecrawl.apiKey hoặc FIRECRAWL_API_KEY.

Config

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "FIRECRAWL_API_KEY_HERE", // tùy chọn nếu FIRECRAWL_API_KEY đã được đặt
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1 ngày)
          timeoutSeconds: 60,
        },
      },
    },
  },
}

Tham số của tool

url (bắt buộc, chỉ http/https)
extractMode (markdown | text)
maxChars (cắt ngắn các trang dài)

Lưu ý:

web_fetch dùng Readability (trích xuất nội dung chính) trước, sau đó Firecrawl (nếu được cấu hình). Nếu cả hai đều thất bại, tool trả về lỗi.
Các request Firecrawl dùng chế độ vượt bot và cache kết quả mặc định.
web_fetch gửi User-Agent giống Chrome và Accept-Language mặc định; ghi đè userAgent nếu cần.
web_fetch chặn hostname private/internal và kiểm tra lại redirect (giới hạn bằng maxRedirects).
web_fetch là trích xuất best-effort; một số trang web sẽ cần browser tool.
Xem Firecrawl để biết cách thiết lập key và chi tiết dịch vụ.
Response được cache (mặc định 15 phút) để giảm fetch lặp lại.
Nếu các bạn dùng tool profiles/allowlists, thêm web_search/web_fetch hoặc group:web.
Nếu thiếu Brave key, web_search trả về gợi ý thiết lập ngắn kèm link tài liệu.