browser-search 快速入门

browser-search 快速入门

一句话卖点: 搜索+浏览+反爬三合一，Agent 终于能自由访问 Web 了

这是什么?适合谁?

browser-search 是 AI Agent 的 Web 搜索 Skill 三件套。将搜索引擎（SearXNG）、浏览器（Camofox）、反爬保护（CloakBrowser）三个环节打包为一个即装即用的 Agent Skill。自托管、免费、无限使用。

核心理念：Agent 搜索 Web 时面临三大痛点——搜索引擎 API 收费贵、网站反爬拦截、浏览内容被屏蔽。browser-search 用 SearXNG（开源元搜索引擎）替代 Google/Bing API，用 Camofox（反检测浏览器）绕过 Cloudflare，用 CloakBrowser 处理验证码和访问限制。

适合需要 Agent 进行 Web 搜索和浏览的开发者。不适合已有 SearXNG 部署经验的用户（可以直接用 SearXNG 原生 API）。

准备工作

1. 准备一台可以运行 Docker 的服务器（用于部署 SearXNG）
2. 安装 Node.js（用于 Camofox 和 CloakBrowser）
3. 确保 AI Agent（如 Claude Code）已安装
4. 了解基本的 Docker 操作

3步快速上手

第1步: 部署 SearXNG

使用 Docker 部署 SearXNG 元搜索引擎。browser-search 提供了 docker/setup.md 部署指南，按步骤启动。SearXNG 聚合多个搜索引擎的结果，无需任何 API key。

第2步: 配置 Camofox 和 CloakBrowser

Camofox 是一个反检测浏览器实例，模拟真实用户行为绕过 Cloudflare 等防护，通过 REST API 在 localhost:9377 提供服务。CloakBrowser 处理验证码和访问限制，通过 npm 安装并按需启动。两者通过本地代理与 SearXNG 协同工作。

第3步: 在 Agent 中加载 Skill

将 browser-search Skill 加载到 Claude Code、OpenCode、Cursor 等兼容 Agent 中。Agent 可以通过自然语言发起 Web 搜索，browser-search 自动处理搜索→浏览→反爬全流程。

常见踩坑

1. SearXNG 实例需要公网可访问——如果 Agent 运行在本地，SearXNG 也需要本地部署
2. 搜索引擎限流——SearXNG 聚合多个搜索引擎，某些引擎可能对频繁请求限流
3. Camofox 资源消耗——反检测浏览器模拟完整浏览器环境，内存占用较高
4. 验证码并非 100% 可绕过——复杂验证码（如 reCAPTCHA v3）仍可能失败
5. 网站 ToS 合规——自动浏览某些网站可能违反其服务条款
6. 搜索结果质量——SearXNG 的聚合结果可能不如 Google 原生搜索精准

初级用法

1. Agent 搜索最新技术文档：Agent 自动搜索 → 浏览结果页面 → 提取关键信息
2. 竞品调研：Agent 搜索竞品信息 → 浏览官网 → 汇总对比
3. 新闻监控：Agent 定时搜索特定关键词 → 浏览新闻页面 → 摘要汇报
4. 文档查证：Agent 搜索技术问题 → 浏览多个来源 → 交叉验证

高级玩法

1. 自定义搜索引擎组合：配置 SearXNG 使用特定的搜索引擎组合，优化特定领域的搜索质量
2. 深度研究模式：Agent 搜索 → 浏览 → 发现新关键词 → 递归搜索 → 综合报告
3. 多 Agent 并行搜索：多个 Agent 同时搜索不同关键词，汇总结果
4. 搜索缓存：配置 SearXNG 缓存策略，减少重复搜索的延迟

小技巧

1. 为不同场景配置不同的 SearXNG 实例（如技术搜索用 Google+GitHub，新闻搜索用 Bing+News）
2. 设置搜索频率限制，避免被目标网站封 IP
3. 定期更新 Camofox 的浏览器指纹，保持反检测效果
4. 将搜索结果缓存到本地，减少重复请求
5. 配置 Agent 的搜索预算（每日最大搜索次数），控制资源消耗

常见问题 FAQ

Q1: browser-search 是免费的吗？ 是的，MIT 开源协议，完全免费。但需要自备服务器部署 SearXNG。 来源: https://github.com/Johell1NS/browser-search LICENSE

Q2: 和 Google Search API 有什么区别？ Google Search API 按次收费且有配额限制，browser-search 使用 SearXNG 聚合多个免费搜索引擎，无使用次数限制。但搜索结果质量可能不如 Google 原生 API。 来源: https://github.com/Johell1NS/browser-search README

Q3: 需要 API key 吗？ 不需要。SearXNG 聚合公开搜索引擎，无需任何 API key。 来源: https://github.com/Johell1NS/browser-search

Q4: 能绕过所有网站的反爬吗？ 不能。Camofox 和 CloakBrowser 能处理大多数 Cloudflare 防护和简单验证码，但 reCAPTCHA v3 等高级防护仍可能失败。 来源: https://github.com/Johell1NS/browser-search

Q5: 支持哪些 AI Agent？ 任何支持加载外部 Skill 的 Agent（Claude Code、Cursor、Codex 等）。 来源: https://github.com/Johell1NS/browser-search

参考链接

• 官方仓库: https://github.com/Johell1NS/browser-search
• SearXNG 文档: https://docs.searxng.org
• Camofox: https://github.com/Johell1NS/browser-search/tree/master/docker (browser-search 仓库内)
• MCP 协议: https://modelcontextprotocol.io

⚙️ 架构详解：三级升级链

browser-search 的核心设计是一个自动升级链（escalation chain），Agent 按优先级依次尝试三种工具：

SearXNG (搜索) → Camofox (浏览) → CloakBrowser (反爬)
    ↓ 找到信息              ↓ 页面可访问              ↓ Camofox 被拦截
    ↓ 直接使用结果           ↓ 提取内容                ↓ 最后一层绕过
    ↓ 返回给Agent           ↓ 返回给Agent             ↓ 返回给Agent

第一级 — SearXNG（元搜索引擎）：部署在 localhost:8080 的 Docker 容器。通过 REST API 发起搜索请求，聚合 Google、Bing、DuckDuckGo、Wikipedia 等数十个搜索引擎的结果。无需任何 API Key——这是 browser-search 完全免费的关键。支持按语言、时间范围、分类、引擎过滤搜索，支持图片搜索和分页。

第二级 — Camofox（反检测浏览器）：部署在 localhost:9377 的 Docker 容器，基于 Camoufox（Firefox 的 MIT 许可分支）。提供完整的 REST API（13+ 端点），Agent 通过 curl 命令创建标签页、截取快照、执行 JavaScript、点击、滚动、输入等操作。集成 Mozilla Readability.js 用于文章内容提取，相比原始快照可节省约 70% token 消耗。约 90% 的网站可通过 Camofox 正常访问。

第三级 — CloakBrowser（隐身 Chromium）：通过 npm 按需安装和启动的 Chromium 浏览器实例。当 Camofox 被 Cloudflare、Akamai、DataDome 等高级反爬系统拦截时，Agent 自动升级到 CloakBrowser。设计为 fire-and-forget 模式（启动→导航→关闭），避免常驻容器占用资源。约 10% 的场景会触发此升级。

🛡️ 安全与风险

browser-search 在 SKILL.md 中明确定义了安全边界：

已实施的安全措施：

• SSRF/DNS 验证：阻止对私有 IP、云元数据端点、DNS 重绑定的请求
• Playwright 沙箱：仅开放白名单 API 方法，禁止任意脚本执行
• 频率限制：默认 30 req/min，防止对目标站点造成负担
• 路径遍历保护：验证脚本路径不越权访问文件系统
• 依赖锁定：package.json + package-lock.json 固定版本
• 审计脚本：scripts/audit.sh 检查完整性和已知漏洞
• CloakBrowser Chromium 二进制 SHA-256 校验

已知风险（README 中明确记录）：

• Camofox 的 REST API 默认无身份验证（大部分端点），同一主机上的任何进程均可调用
• CloakBrowser 的 Chromium 二进制为专有软件（非开源），虽可免费使用但不可审计
• SearXNG 聚合的搜索引擎可能对频繁请求限流，影响搜索可用性
• 自动浏览某些网站可能违反其服务条款，用户需自行承担合规责任

📊 与其他方案对比

browser-search 的独特价值在于同时覆盖搜索、浏览、反爬三个环节，且完全免费自托管。适合对隐私敏感、需要无限使用、愿意自己运维服务器的开发者和团队。

🚀 部署实战与性能参考

硬件需求

browser-search 在设计上考虑了资源受限环境，官方已在 Raspberry Pi 上完成测试验证：

快速部署步骤

# 1. 安装 SearXNG
mkdir searxng && cd searxng
# 参见 docker/setup.md 完成 SearXNG 配置
docker compose up -d

# 2. 安装 Camofox（从 browser-search 仓库）
cd browser-search
# 配置 CAMOFOX_API_KEY 环境变量
docker compose -f docker/camofox.yml up -d

# 3. 安装 CloakBrowser
npm install
# CloakBrowser 会在首次使用时自动下载 Chromium 二进制

# 4. 验证
curl http://localhost:8080/search?format=json&q=test  # SearXNG
curl http://localhost:9377/health                       # Camofox

常用 Agent 集成示例

将 SKILL.md 内容加载到 Agent 后，Agent 可自动执行以下典型流程：

场景：搜索最新技术文档

Agent: "搜索 React 19 的新特性"
→ SearXNG 搜索 "React 19 new features"
→ 获取搜索结果列表（含 URL、标题、摘要）
→ Camofox 打开排名靠前的页面
→ 使用 Readability.js 提取文章正文
→ 汇总多来源信息返回给用户

场景：竞品价格调研

Agent: "对比 OpenAI、Anthropic、Google 最新模型定价"
→ SearXNG 分别搜索各厂商 pricing page
→ Camofox 依次打开定价页面
→ evaluate 提取价格表格数据
→ 生成对比表格返回给用户

注意事项

• SearXNG 首次启动后需通过 Web UI 设置默认搜索引擎偏好
• Camofox 的 CAMOFOX_API_KEY 建议使用 openssl rand -hex 32 生成强随机密钥
• CloakBrowser 首次下载 Chromium 二进制约需 300MB 流量，建议在网络良好的环境执行
• 生产环境建议使用反向代理（nginx/Caddy）为 SearXNG 和 Camofox 添加 HTTPS
• 定期执行 scripts/audit.sh 检查依赖安全漏洞