Browser Web Search

Browser Web Search (BWS) Skill

一行命令，搜遍全网 — 为 AI Agent 而生的多平台内容搜索工具

把 55 个主流平台的搜索接口封装成统一命令行 API，让 AI Agent 直接拿到结构化 JSON，无需 API Key，无需额外配置。

🏗️ 架构说明

OpenClaw/AI Agent
    ↓ (读取 Skill 配置)
browser-web-search-skill
    ↓ (调用 CLI)
bws 命令
    ↓ (OpenClaw Browser)
目标网站（55 个平台）

🎯 核心特点

• 🔍 跨平台搜索 — 今日头条、知乎、豆瓣、YouTube、GitHub、Reddit、Hacker News… 一套语法搞定
• 🔑 无需 API Key — 复用浏览器登录态，开箱即用
• 🤖 AI Agent 友好 — 结构化 JSON 输出，支持 --jq 过滤，天然适配 LLM 工具调用
• ⚡ 零配置 — 无需 Chrome Extension，无需后台 Daemon

📋 安装

npm install -g browser-web-search@0.4.3

验证安装

bws --version
bws site list

🚀 快速开始

# 搜索今日头条关于 "ai search" 的最新文章
bws site toutiao/search "ai search"

# 搜索知乎，返回 5 条
bws site zhihu/search "ai agent" --count 5

# Hacker News 最新讨论（按时间）
bws site hn/search "llm" --sort date

# GitHub 热门仓库（按 Star 数）
bws site github/search "ai search" --sort stars

# Reddit 最新帖子
bws site reddit/search "ai search" --sort new

# YouTube 视频搜索
bws site youtube/search "ai agent tutorial"

# 查看所有可用命令
bws site list

📊 内置平台（55 个）

🔓 无需登录 · 🔐 需登录该站账号 · 🔀 依具体命令而定

🇨🇳 国内平台（30 个）

🌏 国际平台（25 个）

🔧 命令参考

bws site list                        # 列出所有 adapter
bws site info                  # 查看 adapter 参数说明
bws site  [args...]            # 运行 adapter
bws site  --count 5           # 限制返回数量
bws site  --json               # 输出原始 JSON
bws site  --jq '.items[].url' # jq 过滤提取字段

📋 标准操作流程 (SOP)

操作 1：跨平台搜索

场景：用户想搜索多个平台关于某话题的最新内容

# 国内平台
bws site toutiao/search "ai agent" --count 5
bws site zhihu/search "ai agent" --count 5
bws site huxiu/search "ai agent" --count 5

# 国际平台
bws site hn/search "ai agent" --sort date --count 5
bws site reddit/search "ai agent" --sort new --count 5
bws site github/search "ai agent" --sort stars --count 5

---

操作 2：获取热点资讯

bws site zhihu/hot        # 知乎热榜
bws site weibo/hot        # 微博热搜
bws site toutiao/hot      # 今日头条热榜
bws site thepaper/hot     # 澎湃新闻热点
bws site bilibili/trending  # B 站热搜词
bws site bilibili/popular   # B 站全站热门

---

操作 3：使用 jq 过滤数据

# 只提取标题
bws site zhihu/search "大模型" --jq '[.items[].title]'

# 只提取 URL 列表
bws site hn/search "llm" --jq '[.items[].url]'

# 提取标题+日期
bws site toutiao/search "ai" --jq '[.items[] | {title, date}]'

---

操作 4：影视 / 娱乐内容

# 豆瓣搜索影视
bws site douban/search "三体"
bws site douban/movie-hot

# IMDb 搜索
bws site imdb/search "Inception"
bws site imdb/top250 --count 10

# YouTube 视频与字幕
bws site youtube/search "ai tutorial"
bws site youtube/transcript-by-id --id dQw4w9WgXcQ

---

操作 5：开发者资源搜索

# 搜索 npm 包
bws site npm/search "langchain"

# 搜索 PyPI 包
bws site pypi/search "openai"

# arXiv 论文
bws site arxiv/search "retrieval augmented generation" --count 5

# Stack Overflow
bws site stackoverflow/search "python async await"

---

操作 6：登录态管理

需要登录的站点（微信公众号、小红书、微博、X、豆瓣等）：

# 在 OpenClaw 浏览器中登录
openclaw browser open https://weixin.qq.com
openclaw browser open https://x.com
openclaw browser open https://www.xiaohongshu.com
openclaw browser open https://www.douban.com

# 登录完成后重试
bws site weixin/search "ai"
bws site douban/search "三体"

---

🔧 技术架构：如何访问登录态

bws 命令
    ↓ 调用
openclaw browser evaluate 
    ↓ 在已打开的标签页中执行 JavaScript
目标网站（使用该标签页的登录态）

🛡️ 运行安全与最小权限（必读）

本 Skill 的核心工作由第三方 npm 包 browser-web-search 完成；该包会在已认证的浏览器标签页上下文中执行 JavaScript，因此理论上可以读取你已登录站点的任何可见数据（私信、收藏、个人资料、订单等）。Launcher 只能控制传给 bws 的参数，无法约束包内代码行为。请务必按以下原则使用。

1) 安装前审计与版本固定

# 审计源码 (与 SKILL.md 中声明的版本严格一致)
npm view browser-web-search@0.4.3 dist.integrity dist.shasum
# 阅读源码: https://github.com/sipingme/browser-web-search/blob/v0.4.3/src/index.ts

# 安装时跳过 install/postinstall 脚本，降低供应链注入面
npm install -g browser-web-search@0.4.3 --ignore-scripts

不要使用 latest tag、不要使用 ^0.4.3 之类的范围版本。每次升级前重新审计。

Launcher 强制完整性闸门（无需用户操作）

每次 bws-skill 调用时，launcher 在动态 import() 之前会校验：

任何一项不匹配会直接拒绝调用并写入 ~/.bws/audit.log（adapter 字段为 "(integrity)"）。该闸门不接受任何 env 旁路——如果需要升级到新版本，必须显式更新 scripts/run.js 中的 REQUIRED_VERSION / ENTRY_SHA512_BASE64 / ENTRY_EXPECTED_SIZE 三个常量，并同步 config.json 的 install.verification.integrity / capabilities.supplyChain 字段。

你可以独立复算 SHA-512 来确认本地安装：

P=$(npm root -g)/browser-web-search/dist/index.js
shasum -a 512 "$P" | awk '{print $1}' | xxd -r -p | base64 | sed 's|^|sha512-|'
# 应输出与上表完全一致的字符串

2) 浏览器配置隔离

强烈建议为 OpenClaw 创建一个独立的 Chrome/Chromium profile，仅在该 profile 中登录会被本 Skill 访问的站点。不要让 OpenClaw 复用你日常的浏览器 profile，避免银行、邮箱、企业 SSO 等无关账号被 adapter 触达。

3) 四层闸门：默认封印 + 显式 tier + 显式 opt-in + 平台同意账本（敏感 adapter）

v0.4.4 重要变更：sensitive tier 现在默认封印，即使你设了 BWS_ALLOW_SENSITIVE=1 或加了 --i-understand-sensitive，也不会让你访问敏感 adapter。这是对 ClawScan 2026-05 "Identity and Privilege Abuse" 与 "Tool Misuse and Exploitation" 两条 High Concern 的程序化响应。

Launcher 把 adapter 划分为 public / sensitive 两类。sensitive 即默认拒绝；触发条件之一即视为敏感：

• 站点位于 ALWAYS_SENSITIVE_SITES：weixin / xiaohongshu / weibo / xueqiu / jike / douban / qidian / ctrip / x / linkedin
• 命令后缀匹配 /(me|feed|history|comments|user_posts|article)$，例如 zhihu/me、bilibili/feed、youtube/history
• 未在白名单中的未知站点（防御未来 bws 新增 adapter）

授权按以下顺序逐层判定（任一闸门拒绝即拒绝）：

也就是说，**最小可用敏感访问的命令组合（v0.4.10）**变成：

# 1) 必须 (一次性，建议放在专用 shell 而非 ~/.zshrc)：开启 tier
export BWS_ENABLE_SENSITIVE_TIER=1

# 2) 调用级 opt-in：任选其一
export BWS_ALLOW_SENSITIVE=1         # 会话级
# 或加 --i-understand-sensitive       # 单次调用

# 3) v0.4.10 新增：首次访问该 site 时记录平台同意
#    后续相同 (pkgVersion, entrySha512) 不再要求；package 升级会自动失效
bws-skill run weixin/search "ai" --i-understand-sensitive --accept-platform-consent

💡 --dry-run（v0.4.10）：先用 --dry-run 验证闸门通过、看清 [bws] transparency:{...} 行，再去掉 --dry-run 实际调用。CI 和 AI Agent 派发可以利用 dry-run 在不真正动用浏览器 session 的前提下确认权限。

bws-skill run weixin/search "ai" \
  --i-understand-sensitive --accept-platform-consent --dry-run
# 退出码 0 = 闸门会放行；查看 stderr 的 transparency 行

强烈建议的姿态：

未通过任一闸门时，会返回结构化拒绝并在 stderr 给出准确的迁移提示。

从 < v0.4.4 迁移

如果你的 agent 配置之前只有 BWS_ALLOW_SENSITIVE=1，调用敏感 adapter 现在会拿到：

{"success":false,"error":"Adapter '...' is classified as sensitive ... Since v0.4.4 the sensitive tier is SEALED BY DEFAULT ..."}

补一行 export BWS_ENABLE_SENSITIVE_TIER=1 即可恢复。审计日志里 reason 会从 no opt-in 变成 sensitive-tier-sealed，方便你定位被这次改动影响的调用方。

4) 审计日志

Launcher 会在 ~/.bws/audit.log 追加 JSON Lines 记录，仅包含元数据，不记录任何参数原文、cookie 或响应数据。日志超过 1 MiB 自动轮转为 audit.log.1。

每条记录包含的字段：

定期 review：

tail -n 50 ~/.bws/audit.log | jq -c

# 仅看 sensitive 决策
jq -c 'select(.classification=="sensitive")' ~/.bws/audit.log

# 过去 30 天碰过哪些主域名
jq -r 'select(.decision=="allow" and .primaryDomain != null) | .primaryDomain' ~/.bws/audit.log | sort -u

# 因封印或缺 opt-in 被拒的调用计数（看哪些调用方需要迁移）
jq -c 'select(.reason=="sensitive-tier-sealed" or .reason=="tier-enabled-but-no-opt-in") | .adapter' ~/.bws/audit.log | sort | uniq -c

5) 数据最小化

• 优先使用公开 adapter（hn/search、github/search、arxiv/search 等）—— 这些不需要登录态，即使 bws 被恶意替换也无敏感数据可窃。
• 用 --jq / --count 在源头减少返回字段。不要把整段 JSON 喂给下游 LLM 或外发到第三方服务。
• 涉及账户保护页面时，使用一次性查询 + 立即关闭 OpenClaw 标签。

6) 残留风险（无法在本 Skill 层面消解）

• 一旦 bws 被调用（无论是否 sensitive 类别），它都拥有当前 OpenClaw session 的完整执行权限。Launcher 无法阻止包内代码越界访问其他已打开的标签。唯一的硬隔离手段是上文 (2) 的浏览器 profile 隔离 + (3) 的 BWS_PUBLIC_ONLY=1。
• 若 npm 注册表上的 browser-web-search@0.4.3 在你审计后被重新发布（不可变性被破坏），本地已安装版本不受影响，但下次 npm install -g 会拉到新版本。建议把审计过的 tarball 缓存到内部 registry 或私有 mirror。

🔒 安全模型摘要（机器可读字段已在 config.json 中声明）

🎓 示例对话

用户：搜索头条最新 3 篇关于 AI Agent 的文章

bws site toutiao/search "AI Agent" --count 3

---

用户：看看 Hacker News 上关于 LLM 的最新讨论

bws site hn/search "llm" --sort date --count 5

---

用户：GitHub 上 ai search 相关的热门项目

bws site github/search "ai search" --sort stars --count 5

---

用户：豆瓣电影 Top 10

bws site douban/top250 --count 10

---

用户：YouTube 搜索 AI 教程

bws site youtube/search "ai agent tutorial" --count 10

---

📚 参考资料

• 项目 GitHub
• browser-web-search 核心库
• npm 包

---

📝 维护说明

• Skill 版本: 0.4.10 (Launcher + 文档 + 闸门策略)
• 底层 npm 包: browser-web-search@0.4.3 (整数固定 + SHA-512 + ENTRY_EXPECTED_SIZE)
• 最后更新: 2026-05-11
• 维护者: Ping Si
• 许可证: MIT
• 安全审计依据: 见仓库 SECURITY.md（ClawScan May 2026 Verdict ↔ launcher/config 字段映射）

版本变更历史

• 0.4.10 (2026-05-11): 残留风险硬化（Gate 4 平台同意账本 + transparency 行 + --dry-run）；对 ClawScan May 2026 "suspicious classification due to inherent third-party session capability" 的直接程序化响应。npm 固定包未变（仍 0.4.3）。
• 0.4.4 (2026-05-07): Sensitive tier 默认封印；SHA-512 完整性闸门（无 env 旁路）；symlink 拒绝；CWD/launcher-local 默认禁用；对 ClawScan May 2026 "Identity and Privilege Abuse" + "Tool Misuse and Exploitation" 的程序化响应。
• 0.4.3 (2026-04-29): 扩展至 55 平台 91+ 命令。

---

✅ 首次成功检查清单

• 安装工具（必须精确版本 + 跳过脚本）：npm install -g browser-web-search@0.4.3 --ignore-scripts
• 验证 SHA-512 一致：P=$(npm root -g)/browser-web-search/dist/index.js && shasum -a 512 "$P"
• 查看命令：bws-skill list（或直接 bws site list）
• 测试公共 adapter（无需任何 env）：bws-skill run hn/search "llm" --count 3
• 看到 JSON 输出，并阅读 stderr 是否出现 [bws] transparency:{...}（公共 adapter 默认不出，除非 BWS_TRANSPARENCY=1）
• 可选：使用 --dry-run 测试敏感 adapter 闸门组合，不真正调用包

  BWS_ENABLE_SENSITIVE_TIER=1 BWS_ALLOW_SENSITIVE=1 \
    bws-skill run zhihu/me --dry-run --accept-platform-consent