OpenClaw 网络搜索与抓取工具最佳实践指南

web_search 和 web_fetch 是 Agent 提供给你的统一能力接口，像'遥控器'；Brave、Gemini 等是内置频道；Tavily、Firecrawl 是额外加装的频道模块。你配置了哪个 Provider 或安装了哪个 Skill，Agent 就更可能通过对应能力去完成搜索或抓取。

推荐的使用分工

tavily-search 负责什么

适合场景：

• 找最新资料、新闻、论文入口、官方文档入口。
• 找多个候选来源，为后续精读做召回。
• 不确定先读哪个页面时。

典型任务：最近一周 AI 新闻、某个框架最近更新了什么、某个 API 的官方文档入口。

web_fetch 负责什么

适合场景：

• 已经有 URL，知道要读哪个页面。
• 读取正文、抓取细节、提取发布日期、作者、版本号、参数说明。
• 核对页面中是否真的写了某句话。

典型任务：阅读官方文档页面、总结新闻正文、提取博客文章要点、查看 release note 里的变更项。

agent-reach 负责什么

适合场景：

• 协调多步任务，提高外部能力被调用的概率。
• 强化'先搜索、再阅读、再总结'的工作流。
• 降低模型直接凭已有知识回答的概率。

标准工作流

工作流 A：没有 URL

1. 用 tavily-search 搜索。
2. 获取候选来源。
3. 选择最相关来源。
4. 用 web_fetch 读取。

工作流 B：已有 URL

1. 直接用 web_fetch 读取。

工作流 C：复杂多步任务

1. 用 agent-reach 协调任务。
2. 先搜索。
3. 再阅读。
4. 最后总结。

何时优先使用特定工具

优先用 tavily-search

当你还没有具体网址，或者要查'最新''最近''本周''本月'，需要候选来源列表时。例如查找新闻、论文、公告、文档入口。

优先用 web_fetch

当你已经有 URL，只想读某个页面，需要正文或页面细节时。例如提取参数、版本号、发布日期等信息。

对话提示词模板

为了让 Agent 更稳定地触发正确流程，建议在提示词中明确步骤。

1. 搜索后再读取

先使用 tavily-search 搜索这个主题，列出 5 个最相关来源；再使用 web_fetch 打开最相关的 1 个页面并总结。主题：multimodal RAG 最新论文

2. 只搜索，不精读

使用 tavily-search 搜索：最近一周关于 OpenAI 模型发布的新闻，只给我来源列表和一句话摘要。

3. 官方来源优先

使用 tavily-search 搜索 Kubernetes Ingress 官方文档，优先官方来源；再用 web_fetch 打开最相关页面并总结。

4. 搜索新闻

先用 tavily-search 搜索最近一周 AI agent 相关新闻，再给我按时间排序的摘要。

5. 搜索论文

先使用 tavily-search 搜索 multimodal RAG 相关论文，优先 arXiv 和官方论文页面，再使用 web_fetch 阅读最相关页面并总结。

6. 多步任务协同

这是一个多步任务。请通过 agent-reach 协调当前可用能力，不要直接凭已有知识回答。先使用 tavily-search 搜索高质量来源，再使用 web_fetch 阅读最相关页面，最后给出带来源的结论。主题：最近一个月关于 AI agent memory 的研究进展。

命令行直测速查

下面这些命令用于直接测试 tavily-search skill 本体，验证插件和 API key 是否生效。

基础搜索

# 语法：node <脚本路径> "<查询词>"
# 规则：查询词建议放在双引号中，适合快速验证插件和 API key 是否生效
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "python async patterns"

指定结果数量

# 语法：node <脚本路径> "<查询词>" -n <数量>
# 规则：常见范围 1 到 20，数量越多，召回越广，但噪声可能增加
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "React hooks tutorial" -n 10

指定搜索深度

# 语法：node <脚本路径> "<查询词>" --depth <模式>
# 规则：basic 最通用，advanced 适合研究型任务
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "machine learning evaluation benchmarks" --depth advanced

搜索新闻

# 语法：node <脚本路径> "<查询词>" --topic news
# 规则：适合最新事件、产品发布、政策变化
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "AI regulation Europe" --topic news

限定时间范围

# 语法：node <脚本路径> "<查询词>" --time-range <范围>
# 规则：适合'最近一周''最近一个月'这类查询
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "OpenAI API updates" --topic news --time-range week

限定域名

# 语法：node <脚本路径> "<查询词>" --include-domains <域名列表>
# 规则：适合官方文档、论文站点、可信来源筛选
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "Python asyncio gather" --include-domains docs.python.org

排除域名

# 语法：node <脚本路径> "<查询词>" --exclude-domains <域名列表>
# 规则：适合过滤低质量或无关站点
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "LLM benchmarks" --exclude-domains pinterest.com,reddit.com

输出 JSON

# 语法：node <脚本路径> "<查询词>" --json
# 规则：适合程序消费，不适合纯人工阅读
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "vector database comparison" --json

返回更完整内容

# 语法：node <脚本路径> "<查询词>" --raw-content
# 规则：输出会更长，更适合研究和离线分析
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "multimodal RAG survey" --raw-content

多参数组合

# 语法：node <脚本路径> "<查询词>" -n <数量> --topic <主题> --time-range <范围> --include-domains <域名列表>
# 规则：参数越明确，结果通常越稳定，适合研究型和高价值查询
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "multimodal RAG papers" -n 8 --topic general --time-range year --include-domains arxiv.org,acm.org

如何更稳定触发正确流程

在对话中，可以通过以下方式引导 Agent：

1. 明确步骤：先使用 tavily-search 搜索高质量来源，再使用 web_fetch 阅读最相关页面，最后总结。
2. 强调不要直接回答：不要直接凭已有知识回答。先使用 tavily-search 搜索，再使用 web_fetch 阅读来源，然后给出结论。
3. 强调这是最新信息：这是一个需要最新信息的问题。请先使用 tavily-search 搜索最近一周相关资料，再使用 web_fetch 阅读最相关页面。
4. 强调官方来源：先使用 tavily-search 搜索，优先官方来源；再使用 web_fetch 打开最相关页面并提取关键信息。
5. 加入 agent-reach 强化多步协同：请通过 agent-reach 协调当前可用能力，不要直接回答。先使用 tavily-search 搜索高质量来源，再使用 web_fetch 阅读关键页面，最后输出带来源的总结。

常见误区

• 误区 1：把 web_search 当成固定插件名。它往往是'网页搜索能力'的泛称。
• 误区 2：把原生 Provider 和扩展 Skill 混为一谈。Brave/Gemini 是原生，Tavily/Firecrawl 是扩展。
• 误区 3：把 web_fetch 当成搜索工具。它一般负责'打开页面'，不是'找页面'。
• 误区 4：以为装了 tavily-search 就不需要 web_fetch。两者配合效果最好。
• 误区 5：以为 Provider、Skill、Tool 是同一层。Provider 是底层服务，Skill 是封装方式，Tool 是暴露给 Agent 的入口。
• 误区 6：以为 agent-reach 是搜索工具。它更适合作为多步任务协调层。

推荐默认策略

• 如果没有 URL：先用 tavily-search。
• 如果有 URL：直接用 web_fetch。
• 如果问题涉及最新信息：先用 tavily-search，必要时限定时间范围。
• 如果需要精读：先 tavily-search，后 web_fetch。
• 如果需要官方来源：先用 tavily-search 找官方页面，再用 web_fetch 读。
• 如果任务是多步研究：加入 agent-reach 协调'搜索 → 阅读 → 总结'。

排障速查

情况 1：脚本报 TAVILY_API_KEY not set

说明当前 shell 没拿到环境变量。

# 检查当前 shell 是否已经有 TAVILY_API_KEY
# 有输出表示变量已生效，空输出表示变量未生效
echo "$TAVILY_API_KEY"

情况 2：tavily-search 已安装，但对话里没触发

通常不是安装失败，而是提示词不够明确。建议直接这样写：

不要直接回答。先使用 tavily-search 搜索，再使用 web_fetch 阅读来源，最后给出结论。

情况 3：旧会话行为异常

新开一个会话再试，避免旧上下文干扰工具选择。

情况 4：想确认 Skill 本体是否可用

绕过会话层，直接测试 tavily-search skill 脚本本体。

# 这是最稳的插件可用性验证方法
node ~/.openclaw/skills/liang-tavily-search/scripts/search.mjs "latest papers on multimodal RAG"

情况 5：复杂任务总是只用一个工具

尝试在提示词中显式加入：

这是一个多步任务。请通过 agent-reach 协调当前可用能力，先搜索，再阅读，最后总结。

术语表

• web_search：网页搜索能力的抽象接口，重点是'找来源'。
• web_fetch：网页读取能力接口，重点是'读页面'。
• Provider：底层搜索/能力提供方，例如 Brave, Gemini, Grok, Kimi, Perplexity。
• Skill：额外安装的扩展能力封装，例如 Tavily, Firecrawl, agent-reach。
• tavily-search：基于 Tavily 的扩展搜索 Skill，可用于补充或增强 web_search 能力。
• agent-reach：用于协调多步任务、强化外部能力调用的 Skill，不是传统搜索引擎替代品。

总结

web_search 是搜索能力的抽象接口，原生 Provider 包括 Brave / Gemini / Grok / Kimi / Perplexity，扩展 Skill 包括 Tavily / Firecrawl / agent-reach，web_fetch 是网页读取与抓取能力。最佳实践是：先用搜索能力找来源（常用 tavily-search），再用 web_fetch 读来源；复杂任务再用 agent-reach 协调。