"web_search 工具详解"

龙虾学堂2026年5月7日

"深入理解 OpenClaw 的 web_search 工具，掌握搜索参数、结果过滤和实战技巧。"

web_search 工具详解

本文聚焦：搜索参数配置 + 结果过滤与处理

相关阅读：web_fetch 工具详解

知识点 1：搜索参数配置

是什么

web_search 是 OpenClaw 内置的网页搜索工具，基于 Brave Search API。它让 Agent 能够主动搜索互联网获取最新信息，是扩展知识边界的核心工具。

为什么需要

LLM 的知识有截止日期，而世界在不断变化。通过 web_search，Agent 可以：

获取最新技术动态和版本信息
查询实时数据（天气、股价、新闻）
验证事实、补充背景知识
发现相关资源和文档

基本用法

// 最简单的搜索
const result = await web_search({
  query: "OpenClaw 最新版本"
});

核心参数详解

参数	类型	说明	示例
`query`	string	必填，搜索关键词	`"OpenClaw 安装教程"`
`count`	number	返回结果数量 (1-10)	`5`
`country`	string	区域代码 (2字母)	`"US"`, `"CN"`
`language`	string	语言代码 (ISO 639-1)	`"en"`, `"zh"`
`freshness`	string	时间过滤	`"day"`, `"week"`, `"month"`, `"year"`
`date_after`	string	起始日期 (YYYY-MM-DD)	`"2025-01-01"`
`date_before`	string	结束日期 (YYYY-MM-DD)	`"2025-12-31"`

代码示例

// 搜索最近一周的中文技术文章
const techNews = await web_search({
  query: "OpenClaw AI Agent 教程",
  count: 5,
  country: "CN",
  language: "zh",
  freshness: "week"
});

// 搜索结果结构
{
  "results": [
    {
      "title": "文章标题",
      "url": "https://example.com/article",
      "snippet": "文章摘要...",
      "published": "2025-03-10"
    }
  ]
}

常见陷阱

陷阱 1：关键词过于宽泛

// ❌ 不好的查询
{ query: "AI" }

// ✅ 好的查询
{ query: "OpenClaw AI Agent 多智能体配置教程" }

陷阱 2：忽略语言/区域设置

// ❌ 可能返回英文结果
{ query: "天气预报" }

// ✅ 明确指定中文和中国区域
{ query: "北京天气预报", language: "zh", country: "CN" }

陷阱 3：时间过滤使用不当

// ❌ freshness 和 date 参数混用可能导致意外结果
{ query: "新闻", freshness: "day", date_after: "2025-01-01" }

// ✅ 根据需求选择一种方式
// 相对时间：最近24小时
{ query: "新闻", freshness: "day" }
// 绝对时间：特定日期范围
{ query: "新闻", date_after: "2025-03-01", date_before: "2025-03-10" }

知识点 2：结果过滤与处理

搜索结果的结构

interface SearchResult {
  title: string;      // 页面标题
  url: string;        // 页面链接
  snippet: string;    // 内容摘要
  published?: string; // 发布日期（如果有）
}

结果筛选技巧

1. 按域名过滤

const results = await web_search({ query: "OpenClaw 教程", count: 10 });

// 只保留官方文档和 GitHub
const filtered = results.results.filter(r => 
  r.url.includes("github.com") || 
  r.url.includes("docs.openclaw")
);

2. 按关键词过滤标题

// 排除广告和无关结果
const relevant = results.results.filter(r => 
  r.title.toLowerCase().includes("openclaw") &&
  !r.title.toLowerCase().includes("广告")
);

3. 去重处理

// 同一网站可能有多条结果，按域名去重
const uniqueByDomain = results.results.filter((r, index, self) => 
  index === self.findIndex(t => 
    new URL(t.url).hostname === new URL(r.url).hostname
  )
);

与 web_fetch 配合使用

搜索只是第一步，获取完整内容需要 web_fetch：

// 第一步：搜索获取候选链接
const searchResults = await web_search({
  query: "OpenClaw 配置教程",
  count: 3
});

// 第二步：抓取最相关页面的完整内容
const bestMatch = searchResults.results[0];
const fullContent = await web_fetch({
  url: bestMatch.url,
  extractMode: "markdown",  // 或 "text"
  maxChars: 5000
});

// 现在可以基于完整内容进行分析

批量处理模式

// 同时搜索多个主题
const topics = ["OpenClaw 安装", "OpenClaw 配置", "OpenClaw Skills"];

const allResults = await Promise.all(
  topics.map(topic => web_search({ query: topic, count: 3 }))
);

// 合并并去重
const combined = allResults
  .flatMap(r => r.results)
  .filter((r, i, self) => 
    i === self.findIndex(t => t.url === r.url)
  );

实践建议

关键词优化
- 使用 3-5 个关键词，包含核心概念
- 添加 "教程"、"文档"、"指南" 等限定词获取高质量内容
- 英文搜索通常返回更多技术资源
结果验证
- 不要完全信任搜索结果，交叉验证重要信息
- 优先选择官方文档、知名技术博客
- 检查发布日期，避免过时信息
性能考虑
- 合理设置 count，通常 3-5 条足够
- 批量搜索时使用 Promise.all 并行执行
- 对频繁查询的结果考虑本地缓存

错误处理

try {
  const results = await web_search({ query: "..." });
  if (!results.results || results.results.length === 0) {
    // 处理无结果情况
  }
} catch (error) {
  // 处理搜索失败（网络问题、API限制等）
}

与 Agent 工作流结合
- 在回答用户问题前，先搜索获取最新信息
- 使用搜索结果作为 web_fetch 的输入
- 将搜索和抓取结果存入 memory 供后续使用