brave-api-search

核心用法

Brave API Search 提供两个互补工具：：brave_search 用于传统网页搜索，返回带标题、URL、描述的排名结果，支持 AI 摘要；brave_answers 则提供带内联引用的 AI 合成答案，适合深度研究。用户需配置 BRAVE_SEARCH_API_KEY 和 BRAVE_ANSWERS_API_KEY 环境变量，通过标准 HTTPS 调用官方 API。

显著优点

合规性与可靠性：区别于爬虫方案，使用官方 API 获得结构化 JSON 响应，自带速率限制头和标准错误处理，完全遵守服务条款。双工具设计兼顾快速检索与深度研究——brave_search 的 freshness 参数支持按时间过滤（24小时至1年），brave_answers 的 enable_research 可触发多轮搜索合成复杂答案。

零依赖架构：仅使用 Node.js 内置模块，无第三方包引入供应链风险。输入验证严格（count 限制 1-20，freshness 白名单校验），错误信息定向输出至 stderr 避免敏感泄露。

潜在局限

成本门槛：免费版仅 2000 次/月、1 QPS，高频场景需付费（搜索 $5/千次，答案 $4/千次）。功能边界：不支持本地文件索引或私有知识库检索，纯依赖 Brave 的公开网络覆盖。地理限制：默认 US 区域，多语言/本地化搜索需显式配置 country 参数。

适合人群

开发者查阅最新技术文档、研究者追踪时事动态、内容创作者核实信源、产品经理竞品调研——任何需要时效性外部信息且重视引用可追溯性的场景。不适合已有充足上下文或纯内部数据的问答。

使用风险

网络依赖导致 Brave API 故障时服务中断；搜索查询明文传输至第三方存在基础隐私暴露；高频调用易触达速率上限；无内置缓存机制可能产生冗余 API 开销。建议生产环境配置超时重试与响应缓存层。

核心用法

brave-api-search 是一款封装官方 Brave Search API 的实用工具，提供两种核心能力：

`brave_search` — 传统网络搜索，返回带标题、URL、描述的排序结果，可选 AI 摘要

• 支持时间过滤（24小时/7天/31天/1年）、地域定向、扩展片段获取
• 使用高级搜索语法：site: 限定站点、"exact phrase" 精确匹配、-exclude 排除关键词

`brave_answers` — AI 生成式回答，基于实时搜索结果提供带内联引用的综合答案

• 支持「深度研究模式」(enable_research)，自动执行多轮搜索并综合结论
• 自动提取引用来源，附 Token 用量统计

显著优点

| 维度 | 亮点 |

|------|------|

架构极简 | 零第三方依赖，原生 Node.js fetch API，供应链攻击面趋近于零
安全合规 | API 密钥全由环境变量管理，无硬编码；TLS 1.2+ 加密传输
输入严谨 | country 限 2 字母代码、freshness 白名单校验、count 限制 1-20
成本透明 | Brave 官方定价：搜索 $5/千次，问答 $4/千次；免费档 2000 次/月
来源可信 | T2 级可信来源（GitHub 组织账号），OpenClaw 注册表发布

潜在局限

1. API 密钥门槛：需自行注册 Brave Search API 获取双密钥（Search + Answers），国内用户访问可能受限
2. 无内置超时：当前实现未设置 fetch 超时，极端网络条件下可能挂起
3. 响应结构未校验：依赖 API 返回格式，异常响应可能导致解析失败
4. 速率限制：免费版仅 1 QPS，高并发场景需升级付费计划

适合人群

• 需要实时信息检索的开发者（技术文档、版本发布、新闻动态）
• 构建RAG 增强型 AI 应用的工程师，需可信来源引用的场景
• 重视供应链安全的团队，拒绝臃肿依赖的极简主义者

常规风险

| 风险类型 | 说明 | 缓解建议 |

|----------|------|----------|

网络依赖 | 完全依赖 Brave API 可用性 | 实现本地缓存或降级策略 |
成本失控 | 深度研究模式可能触发多轮搜索 | 监控用量，设置预算告警 |
隐私合规 | 搜索查询上传至 Brave 服务器 | 避免搜索敏感个人信息 |
幻觉风险 | AI 摘要/回答仍可能产生事实错误 | 关键信息人工复核原始链接 |

快速开始

export BRAVE_SEARCH_API_KEY="your_key"
export BRAVE_ANSWERS_API_KEY="your_key"

// 获取最新 Node.js 发布信息
brave_search(query: "latest Node.js release", count: 5, summary: true)

// 深度研究技术对比
brave_answers(query: "Compare Postgres vs MySQL for OLAP", enable_research: true)