brave-search

用途

Brave Search 技能提供对 Brave Search 的访问，这是一个注重隐私的网页搜索 API，允许在不追踪用户的情况下查询网络，同时支持过滤条件和摘要提取，面向 AI 驱动的应用。

何时使用

当你需要在 AI 工作流中进行快速、私密的网页搜索时使用，例如为响应获取实时数据、避免在用户查询中收集数据，或将搜索集成到需要过滤结果（如面向家庭内容的安全搜索）的工具中。

主要能力

使用查询字符串、结果数量（例如最多 50 条）以及安全搜索、语言（如 "en-US"）和国家（如 "US"）等过滤条件执行搜索。
提取摘要：API 返回 JSON，每个结果包含标题、URL 和描述字段。
隐私特性：不追踪用户；结果基于 Brave 的索引。
速率限制：每个 API 密钥每天最多 1000 次请求，具体取决于套餐。

使用方式

始终使用 $BRAVE_API_KEY 环境变量对请求进行认证。向端点发起 HTTP GET 请求并携带必需参数。将查询构造为 URL 编码字符串。对于 AI 代理，可通过 Python 或 curl 等语言的 HTTP 客户端集成。通过递增 'offset' 参数（例如从 0 开始，然后 10）在循环中测试分页。

常用命令/API

端点：https://api.search.brave.com/res/v1/web/search
认证：包含请求头 'X-Subscription-Token: $BRAVE_API_KEY'（在环境中通过 export BRAVE_API_KEY=your_key 设置）。
关键参数：q（查询字符串）、count（结果数量，例如 10）、offset（用于分页，例如 0）、search_lang（例如 "en"）、country（例如 "US"）、safe（例如 "active" 表示安全搜索）。

示例 curl 命令：

curl -H "X-Subscription-Token: $BRAVE_API_KEY" "https://api.search.brave.com/res/v1/web/search?q=AI+assistants&count=5&search_lang=en"

使用 requests 的 Python 片段：

import requests; import os;
response = requests.get('https://api.search.brave.com/res/v1/web/search', headers={'X-Subscription-Token': os.environ['BRAVE_API_KEY']], params={'q': 'open source AI', 'count': 3})

配置格式：将 API 密钥存储在 .env 文件中，格式为 BRAVE_API_KEY=your_key，并使用 python-dotenv 等库加载。

集成说明

通过将 API 调用包装在 AI 代理的代码中进行集成；使用异步请求实现非阻塞操作。例如，在 OpenClaw 中，在生成需要外部数据的响应之前调用此技能。通过导出 $BRAVE_API_KEY 或从安全保管库读取来处理配置。如果与其他 AI API 结合使用，请将此技能链接在语言模型等工具之后以丰富输出（例如先搜索上下文，再总结）。由于网页内容易变，避免缓存结果超过 1 小时。

错误处理

检查 HTTP 状态码：200 表示成功，401 表示 API 密钥无效（验证 $BRAVE_API_KEY 后重试），429 表示速率限制（等待并使用指数退避重试，例如 5-10 秒）。解析 JSON 响应中的错误，如 "error": "Bad request"，并记录详细信息。在代码中使用 try-except 块：

try: response = requests.get(...)
except requests.exceptions.RequestException as e: print(f"Error: {e}"); exit(1)

对于 CLI，将输出通过管道传递给 grep 以查找错误模式，并通过以非零代码退出来处理失败。

具体使用示例

搜索最新 AI 新闻：用于获取 AI 主题的头条新闻。命令：curl -H "X-Subscription-Token: $BRAVE_API_KEY" "https://api.search.brave.com/res/v1/web/search?q=latest+AI+advancements&count=3&search_lang=en"。在你的代理中，提取第一个结果的摘要并附加到响应中。

为查询分析提取摘要：对于像 "best open source tools" 这样的用户查询，运行：curl -H "X-Subscription-Token: $BRAVE_API_KEY" "https://api.search.brave.com/res/v1/web/search?q=best+open+source+tools&safe=active&country=US"。处理 JSON 以提取描述，然后在 AI 推理中使用，根据提取的数据推荐工具。

图谱关系

相关：ai-apis（集群），因为它为其他 AI 工具提供搜索能力。