​

Công cụ web

• web_search — Tìm kiếm trên web bằng Brave Search API, Firecrawl Search, Gemini với Google Search grounding, Grok, Kimi, Perplexity Search API, hoặc Tavily Search API.
• web_fetch — Thực hiện HTTP fetch và trích xuất nội dung dễ đọc (HTML → markdown/text).

​

Cách hoạt động

• web_search gọi nhà cung cấp đã cấu hình và trả về kết quả.
• Kết quả được lưu trong bộ nhớ cache theo truy vấn trong 15 phút (có thể cấu hình).
• web_fetch thực hiện một HTTP GET đơn giản và trích xuất nội dung dễ đọc (HTML → markdown/text). Nó không thực thi JavaScript.
• web_fetch được bật mặc định (trừ khi bị tắt rõ ràng).
• Plugin Firecrawl đi kèm cũng thêm firecrawl_search và firecrawl_scrape khi được bật.
• Plugin Tavily đi kèm cũng thêm tavily_search và tavily_extract khi được bật.

​

Chọn nhà cung cấp tìm kiếm

​

Tự động phát hiện

1. Brave — biến môi trường BRAVE_API_KEY hoặc plugins.entries.brave.config.webSearch.apiKey
2. Gemini — biến môi trường GEMINI_API_KEY hoặc plugins.entries.google.config.webSearch.apiKey
3. Grok — biến môi trường XAI_API_KEY hoặc plugins.entries.xai.config.webSearch.apiKey
4. Kimi — biến môi trường KIMI_API_KEY / MOONSHOT_API_KEY hoặc plugins.entries.moonshot.config.webSearch.apiKey
5. Perplexity — biến môi trường PERPLEXITY_API_KEY, OPENROUTER_API_KEY, hoặc plugins.entries.perplexity.config.webSearch.apiKey
6. Firecrawl — biến môi trường FIRECRAWL_API_KEY hoặc plugins.entries.firecrawl.config.webSearch.apiKey
7. Tavily — biến môi trường TAVILY_API_KEY hoặc plugins.entries.tavily.config.webSearch.apiKey

• SecretRefs của công cụ web được giải quyết đồng thời khi khởi động/tải lại gateway.
• Trong chế độ tự động phát hiện, OpenClaw chỉ giải quyết khóa của nhà cung cấp đã chọn. SecretRefs của nhà cung cấp không được chọn vẫn không hoạt động cho đến khi được chọn.
• Nếu SecretRef của nhà cung cấp đã chọn không được giải quyết và không có fallback env của nhà cung cấp, khởi động/tải lại sẽ thất bại nhanh chóng.

​

Cài đặt tìm kiếm web

​

Brave Search

1. Tạo tài khoản Brave Search API tại brave.com/search/api
2. Trong dashboard, chọn gói Search và tạo một API key.
3. Chạy openclaw configure --section web để lưu khóa vào cấu hình, hoặc đặt BRAVE_API_KEY trong môi trường của bạn.

​

Perplexity Search

1. Tạo tài khoản Perplexity tại perplexity.ai/settings/api
2. Tạo một API key trong dashboard
3. Chạy openclaw configure --section web để lưu khóa vào cấu hình, hoặc đặt PERPLEXITY_API_KEY trong môi trường của bạn.

​

Nơi lưu trữ khóa

• Brave: plugins.entries.brave.config.webSearch.apiKey
• Firecrawl: plugins.entries.firecrawl.config.webSearch.apiKey
• Gemini: plugins.entries.google.config.webSearch.apiKey
• Grok: plugins.entries.xai.config.webSearch.apiKey
• Kimi: plugins.entries.moonshot.config.webSearch.apiKey
• Perplexity: plugins.entries.perplexity.config.webSearch.apiKey
• Tavily: plugins.entries.tavily.config.webSearch.apiKey

• Brave: BRAVE_API_KEY
• Firecrawl: FIRECRAWL_API_KEY
• Gemini: GEMINI_API_KEY
• Grok: XAI_API_KEY
• Kimi: KIMI_API_KEY hoặc MOONSHOT_API_KEY
• Perplexity: PERPLEXITY_API_KEY hoặc OPENROUTER_API_KEY
• Tavily: TAVILY_API_KEY

​

Ví dụ cấu hình

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_BRAVE_API_KEY", // tùy chọn nếu BRAVE_API_KEY đã được đặt // pragma: allowlist secret
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
      },
    },
  },
}

{
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "firecrawl",
      },
    },
  },
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "fc-...", // tùy chọn nếu FIRECRAWL_API_KEY đã được đặt
            baseUrl: "https://api.firecrawl.dev",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      tavily: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "tvly-...", // tùy chọn nếu TAVILY_API_KEY đã được đặt
            baseUrl: "https://api.tavily.com",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "tavily",
      },
    },
  },
}

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_BRAVE_API_KEY", // tùy chọn nếu BRAVE_API_KEY đã được đặt // pragma: allowlist secret
            mode: "llm-context",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
      },
    },
  },
}

{
  plugins: {
    entries: {
      perplexity: {
        config: {
          webSearch: {
            apiKey: "pplx-...", // tùy chọn nếu PERPLEXITY_API_KEY đã được đặt
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
      },
    },
  },
}

{
  plugins: {
    entries: {
      perplexity: {
        config: {
          webSearch: {
            apiKey: "<openrouter-api-key>", // tùy chọn nếu OPENROUTER_API_KEY đã được đặt
            baseUrl: "https://openrouter.ai/api/v1",
            model: "perplexity/sonar-pro",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
      },
    },
  },
}

​

Sử dụng Gemini (Google Search grounding)

​

Lấy API key Gemini

1. Truy cập Google AI Studio
2. Tạo một API key
3. Đặt GEMINI_API_KEY trong môi trường Gateway, hoặc cấu hình plugins.entries.google.config.webSearch.apiKey

​

Cài đặt tìm kiếm Gemini

{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            // API key (tùy chọn nếu GEMINI_API_KEY đã được đặt)
            apiKey: "AIza...",
            // Model (mặc định là "gemini-2.5-flash")
            model: "gemini-2.5-flash",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "gemini",
      },
    },
  },
}

​

Ghi chú

• URL trích dẫn từ Gemini grounding được tự động giải quyết từ URL chuyển hướng của Google sang URL trực tiếp.
• Giải quyết chuyển hướng sử dụng đường dẫn bảo vệ SSRF (HEAD + kiểm tra chuyển hướng + xác thực http/https) trước khi trả về URL trích dẫn cuối cùng.
• Giải quyết chuyển hướng sử dụng các mặc định SSRF nghiêm ngặt, vì vậy các chuyển hướng đến các mục tiêu riêng tư/nội bộ bị chặn.
• Mô hình mặc định (gemini-2.5-flash) nhanh và tiết kiệm chi phí. Bất kỳ mô hình Gemini nào hỗ trợ grounding đều có thể được sử dụng.

​

web_search

​

Yêu cầu

• tools.web.search.enabled không được là false (mặc định: bật)
• API key cho nhà cung cấp đã chọn:
  • Brave: BRAVE_API_KEY hoặc plugins.entries.brave.config.webSearch.apiKey
  • Firecrawl: FIRECRAWL_API_KEY hoặc plugins.entries.firecrawl.config.webSearch.apiKey
  • Gemini: GEMINI_API_KEY hoặc plugins.entries.google.config.webSearch.apiKey
  • Grok: XAI_API_KEY hoặc plugins.entries.xai.config.webSearch.apiKey
  • Kimi: KIMI_API_KEY, MOONSHOT_API_KEY, hoặc plugins.entries.moonshot.config.webSearch.apiKey
  • Perplexity: PERPLEXITY_API_KEY, OPENROUTER_API_KEY, hoặc plugins.entries.perplexity.config.webSearch.apiKey
  • Tavily: TAVILY_API_KEY hoặc plugins.entries.tavily.config.webSearch.apiKey
• Tất cả các trường khóa nhà cung cấp trên đều hỗ trợ đối tượng SecretRef.

​

Cấu hình

{
  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ông cụ

// Tìm kiếm cụ thể cho Đức
await web_search({
  query: "TV online schauen",
  country: "DE",
  language: "de",
});

// Kết quả gần đây (trong tuần qua)
await web_search({
  query: "TMBG interview",
  freshness: "week",
});

// Tìm kiếm theo khoảng thời gian
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Lọc tên miền (chỉ Perplexity)
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// Loại trừ tên miền (chỉ Perplexity)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// Trích xuất nội dung nhiều hơn (chỉ Perplexity)
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

​

web_fetch

​

Yêu cầu web_fetch

• tools.web.fetch.enabled không được là false (mặc định: bật)
• Tùy chọn Firecrawl fallback: đặt tools.web.fetch.firecrawl.apiKey hoặc FIRECRAWL_API_KEY.
• tools.web.fetch.firecrawl.apiKey hỗ trợ đối tượng SecretRef.

​

Cấu hình web_fetch

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, như 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ông cụ web_fetch

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

• web_fetch sử dụng Readability (trích xuất nội dung chính) trước, sau đó là Firecrawl (nếu được cấu hình). Nếu cả hai đều thất bại, công cụ sẽ trả về lỗi.
• Yêu cầu Firecrawl sử dụng chế độ tránh bot và lưu trữ kết quả trong bộ nhớ cache theo mặc định.
• SecretRefs của Firecrawl chỉ được giải quyết khi Firecrawl hoạt động (tools.web.fetch.enabled !== false và tools.web.fetch.firecrawl.enabled !== false).
• Nếu Firecrawl hoạt động và SecretRef của nó không được giải quyết với không có fallback FIRECRAWL_API_KEY, khởi động/tải lại sẽ thất bại nhanh chóng.
• web_fetch gửi một User-Agent giống Chrome và Accept-Language theo mặc định; ghi đè userAgent nếu cần.
• web_fetch chặn các tên miền riêng tư/nội bộ và kiểm tra lại các chuyển hướng (giới hạn với maxRedirects).
• maxChars bị giới hạn bởi tools.web.fetch.maxCharsCap.
• web_fetch giới hạn kích thước thân phản hồi tải xuống đến tools.web.fetch.maxResponseBytes trước khi phân tích; các phản hồi quá lớn bị cắt ngắn và bao gồm một cảnh báo.
• web_fetch là trích xuất nỗ lực tốt nhất; một số trang web sẽ cần công cụ trình duyệt.
• Xem Firecrawl để biết cài đặt khóa và chi tiết dịch vụ.
• Các phản hồi được lưu trữ trong bộ nhớ cache (mặc định 15 phút) để giảm các lần fetch lặp lại.
• Nếu bạn sử dụng hồ sơ công cụ/danh sách cho phép, thêm web_search/web_fetch hoặc group:web.
• Nếu thiếu API key, web_search trả về một gợi ý thiết lập ngắn với liên kết tài liệu.