web-search

name	web-search
description	Web search and anti-bot page fetching via search-stack native plugin. Use these tools instead of the built-in web_search/web_fetch when: - Built-in web_search is disabled or returns errors - A page returns empty/blocked content (Cloudflare, anti-bot) - The target site requires JavaScript rendering (SPA, dynamic content) - Fetching Chinese platforms (Xiaohongshu, Douyin, Weibo, Bilibili, Zhihu, Toutiao) - The built-in web_fetch failed or returned incomplete results (use page_fetch instead) - You need multi-engine search with full-text enrichment Triggers: "搜索", "search", "查一下", "look up", "抓取网页", "读取网页", "fetch url", "render page", "cookie", "登录".
user-invocable	true
metadata	{"openclaw":{"emoji":"🔍"}}

Web Search & Anti-Bot Fetch

内置 Brave 搜索已禁用。 所有网页搜索和抓取通过 search-stack 原生插件工具执行。工具已注册到你的工具列表中，直接调用即可。

⚠️ 重要：抓取网页用 page_fetch（不是内置的 web_fetch）。 page_fetch 支持 Cookie 注入、Chrome 渲染、登录检测。内置 web_fetch 没有这些功能。

核心原则：两步法（搜索 → 选择性抓取）

永远不要 默认使用 enrich:true。正确的工作流是：

1. 第一步：快速搜索（~1 秒完成） → 调用 web_search 工具，query = 关键词，count = 5

2. 第二步：选择性抓取（只对需要全文的结果） → 调用 page_fetch 工具，url = 感兴趣的文章 URL

为什么不用 enrich： enrich:true 会同时抓取所有结果的全文，每页耗时 3-10 秒。count:5 enrich:true 总耗时可达 20 秒+，容易超时。两步法总耗时更短（1 秒搜索 + 只抓你需要的 1-2 页），且搜索永远不会失败。

唯一例外： 如果用户明确要求"深度研究"且结果数少，可用 count:3 enrich:true（最多 3 个）。

搜索 — web_search 工具

直接调用 web_search 工具：

参数：

• query (必填) — 搜索关键词
• count (可选) — 结果数量 (1-10，默认 5)

仅在少量结果时可选的 enrich 参数：

• enrich — 同时抓取全文（仅限 count:3 以下）
• max_chars — enrich 时每页最大字符数（默认 8000）
• render — enrich 时用 Chrome 渲染

抓取网页 — page_fetch 工具（不是内置 web_fetch！）

直接调用 page_fetch 工具（支持 Cookie、Chrome 渲染、登录检测）：

参数：

• url (必填) — 要抓取的网址
• render (可选) — 用 headless Chrome 渲染（反爬虫/JS 页面）
• max_chars (可选) — 最大抓取字符数（默认 20000）
• bypass_cache (登录/Cookie 更新后必传 true) — 跳过缓存获取最新内容。不传此参数会返回旧的缓存结果（登录前的）！

典型工作流

新闻推送

1. 调用 web_search：query="日本 ニュース 今日", count=8
2. 从结果中选出最相关的 2-3 条
3. 对每条调用 page_fetch：url=选中的文章URL
4. 汇总推送

技术调研

1. 调用 web_search：query="技术关键词", count=5
2. 浏览标题和摘要，判断哪些值得深读
3. 对 1-2 篇最相关的文章用 page_fetch 抓全文

快速查询（只需要摘要）

调用 web_search：query="具体问题", count=3 直接用 snippet 回答，不需要抓取全文

中国社交平台站内搜索（小红书、抖音、微博等）

这些平台的站内内容 web_search 搜不到（site:xiaohongshu.com 无效），page_fetch 不登录会被拦截。

⚠️ 严格按以下顺序执行，不得跳步：

场景 A：用户给了具体 URL

1. 用 page_fetch 抓取该 URL
2. 如果返回 ** LOGIN REQUIRED ** → 把返回的登录链接发给用户
3. 用户登录后 → bypass_cache:true 重新抓取
4. 只有当用户明确说"不想登录"/"暂时不登录" → 才可用 tikhub_call

场景 B：用户要搜索站内内容（如"搜小红书 日本机票"）

1. 先调用 cookies_list 检查该平台是否已有 Cookie
2. 如果没有 Cookie → 调用 cookie_catcher_link 生成登录链接，告诉用户： "小红书需要登录才能搜索站内内容，请先通过以下链接登录：[链接]。登录后告诉我，我会重新搜索。如果暂时不想登录，我可以尝试用备用接口搜索。"
3. 用户登录后 → 用 page_fetch 抓取搜索页
4. 只有当用户明确回复"不想登录"/"用备用接口" → 才可用 tikhub_call
5. 如果有 Cookie 但 page_fetch 返回 LOGIN REQUIRED → Cookie 过期，引导重新登录

绝对禁止：未经登录引导就直接调用 tikhub_call 搜索站内内容。

Cookie 管理

需要登录时（自动检测）

以下任何一种情况出现时，都必须主动引导用户登录：

1. page_fetch 返回内容包含 ** LOGIN REQUIRED **
2. 页面正文内容明显不完整（只有标题/摘要，正文被截断或为空）
3. 返回了反爬提示（如"请登录"、"需要验证"、"请完成安全验证"等）
4. 返回的内容与预期严重不符（如文章页只拿到导航栏/侧边栏）

page_fetch 检测到需要登录时，返回内容已包含登录链接。直接把链接发给用户即可，不要自行修改或解释链接。

用户点击链接 → 在远程浏览器中登录 → Cookie 自动保存 → 用户告诉你登录好了 → 用 bypass_cache:true 重新抓取。

⚠️ 登录后重试必须传 bypass_cache: true！ 否则会返回缓存的旧结果（登录前的空内容）。示例：

page_fetch(url="https://xiaohongshu.com/...", bypass_cache=true)

不要：

• 不要解释文章内容来代替抓取失败的事实
• 不要跳过登录引导直接回答"抓不到"
• 不要让用户自己去搞技术细节（如 F12 → DevTools → Cookie）
• 不要传不存在的参数（如 extractMode）— 只使用 page_fetch 工具定义的参数
• 不要用内置 web_fetch — 它没有 Cookie 注入和 Chrome 渲染功能

用户主动要求添加 Cookie

调用 cookie_catcher_link 工具生成链接，把链接发给用户。

• 如果知道目标网站，传 url 参数（如 url: "https://youtube.com"）
• 如果不知道，不传 url，用户自己输入

用户直接粘贴 Cookie

当用户发送消息中包含 Cookie 信息时（如含有 cookie、Cookie:、大量 key=value; key=value 格式的文本），自动识别并处理：

场景 A：用户同时发了网址和 Cookie

示例："帮我加一下 Cookie，网址是 https://example.com，Cookie: sid=abc; token=xyz"

处理方式：

1. 从网址中提取域名（如 example.com）
2. 调用 cookies_update 工具：domain="example.com", raw="sid=abc; token=xyz"
3. 告诉用户保存成功，包含域名和 Cookie 数量

场景 B：用户只发了 Cookie，没给网址 → 询问用户这个 Cookie 对应哪个网站

场景 C：用户发了网址但没有 Cookie → 调用 cookie_catcher_link 工具生成登录链接发给用户

Cookie 识别规则

以下格式都视为 Cookie，自动提取：

• Cookie: name1=val1; name2=val2 — 带 Cookie: 前缀
• name1=val1; name2=val2; name3=val3 — 分号分隔的键值对（3 个以上）
• 多行的 name=value 格式

提取域名规则：

• 从 URL 中去掉 www. 前缀，取主域名
• https://www.xiaohongshu.com/explore → xiaohongshu.com
• https://weibo.com/xxx → weibo.com

Cookie 管理工具

• cookies_list — 查看已配置域名
• cookies_update — 保存 Cookie（domain + raw 参数）
• cookies_delete — 删除域名 Cookie
• cookie_catcher_link — 生成远程浏览器登录链接（用户点击登录后 Cookie 自动保存）

社交媒体 API — tikhub_call（最后手段）

核心原则：自有能力优先，第三方兜底

TikHub 是第三方 API，只在自有手段全部失败后才使用。不管什么需求，都必须先用自己的工具链尝试。

调用前提（必须全部满足）

只有同时满足以下两个条件，才可以调用 tikhub_call：

1. 自有手段已尝试且失败 — 已按以下链条尝试过： web_search → page_fetch（普通） → page_fetch（render:true） → 引导登录获取 Cookie → page_fetch（bypass_cache:true） 注意：不是每步都必须执行，但必须尝试到对应场景合理的深度
2. 用户同意使用第三方 — 以下任一：
   • 用户明确要求（"用 tikhub"、"用备用接口"）
   • 你已告知用户自有手段失败并提供了登录选项，用户回复"不想登录"/"暂时不登录"/"直接搜吧"

典型流程示例

"搜小红书 日本机票"：

1. web_search query="小红书 日本机票" → 可能有部分结果但不是站内笔记
2. cookies_list 检查 xiaohongshu.com → 无 Cookie
3. 发 cookie_catcher_link 登录链接给用户，并说明： "小红书需要登录才能搜索站内内容。请通过以下链接登录：[链接]。如果暂时不想登录，我可以尝试用备用接口搜索。"
4. 用户回复"不想登录" → 此时才调用 tikhub_call

"微博热搜"：

1. web_search query="微博热搜" → 可能直接搜到热搜榜单
2. 如果搜到了 → 直接用，不需要 TikHub
3. 如果没搜到有效内容 → 告诉用户"网页搜索没找到实时热搜，要不要用备用接口试试？"
4. 用户同意 → 调用 tikhub_call

"帮我看这个小红书链接 https://..."：

1. page_fetch url=链接 → LOGIN REQUIRED
2. 发登录链接给用户
3. 用户登录后 → bypass_cache:true 重试 → 成功
4. （如果用户不想登录 → 此时可用 tikhub 的 note detail API）

违规行为（绝对禁止）：

• ❌ 未尝试 web_search 就调用 tikhub_call
• ❌ 未发登录链接就调用 tikhub_call 搜索站内内容
• ❌ 内心判断"反正自有工具搜不到"而跳步

调用 tikhub_call 工具：tool_name="工具名", arguments={"参数":"值"}

常用工具速查（必须使用下表中的准确名称，不要猜测！）

平台	工具名	参数	说明
小红书	xiaohongshu_web_search_notes	keyword	搜索笔记（web 端，较稳定）
小红书	xiaohongshu_app_search_notes	keyword, page	搜索笔记（app 端，可能 500）
小红书	xiaohongshu_app_fetch_note_info	note_id	获取笔记详情
TikTok	tiktok_web_fetch_search_video	keyword, count	搜索视频
抖音	douyin_app_fetch_hot_search_list	无	抖音热搜榜
微博	weibo_web_v2_fetch_hot_search_summary	无	微博热搜榜
B站	bilibili_web_fetch_search_result	keyword, page	B站搜索
YouTube	youtube_web_fetch_search_result	keyword	搜索视频

⚠️ 工具名必须完全准确！ 例如 xiaohongshu_web_fetch_search_notes 是错误的，正确名是 xiaohongshu_web_search_notes。名称拼错会返回 500 错误。

注意： 部分端点可能返回空数据或错误（如 xiaohongshu_app_search_notes 偶尔 500），优先用 web 端接口，失败再换 app 端。

使用规则

1. 搜索一律用 web_search 工具 — 内置搜索已禁用
2. 默认不用 enrich:true — 用两步法（搜索 → 选择性 page_fetch）
3. enrich:true 仅限 count:3 以下 — 避免超时
4. 抓取网页一律用 page_fetch（不是内置 web_fetch），它支持 Cookie、Chrome 渲染、登录检测
5. 反爬虫站用 page_fetch + render:true — Browserless 无头 Chrome 始终可用，不要说"没有 Chrome"
6. tikhub_call 是最后手段：自有工具链全部失败 + 用户同意后才调用。优先级：web_search → page_fetch → Cookie 登录 → 用户同意 → TikHub
7. 结果缓存 15 分钟
8. 遇到 LOGIN REQUIRED 或正文不完整 → 直接把返回的登录链接发给用户
9. 用户发送 Cookie 文本时 → 自动识别、提取域名、保存，不要再问"要不要保存"
10. 命令超时处理：工具超时会返回错误信息（不会静默失败），最多重试 1 次
11. 任何场景都先用自有工具（web_search → page_fetch → Cookie 登录），全部失败且用户同意后才 fallback 到 TikHub

备选方式（插件不可用时）

如果原生插件工具不在工具列表中，可通过 mcporter exec 调用：

mcporter call search-stack.web_search query="关键词" count:5 --output json
mcporter call search-stack.page_fetch url="https://example.com" --output json
mcporter call search-stack.cookies_list --output json
mcporter call search-stack.cookies_update domain="example.com" raw="cookie字符串" --output json
mcporter call search-stack.cookies_delete domain="example.com" --output json
mcporter call search-stack.tikhub_call tool_name="工具名" arguments='{"参数":"值"}' --output json