Brave Search API 适合需要实时网络搜索的 OpenClaw 用户，通过 Search 套餐每月可免费查询 1000 次。关键操作为：在 Brave 控制台申请 API Key，在 plugins.entries.brave.config.webSearch 中配置 key 和 mode；支持 web（默认，返回摘要）和 llm-context（返回结构化文本块）两种模式；可通过 baseUrl 指定代理地址；默认缓存 15 分钟，使用 brave.http 诊断标志可排查请求问题。

OpenClaw Brave Search 搜索配置与 API Key #

申请 API Key #

1. 访问 https://brave.com/search/api/ 注册 Brave Search API 账号。
2. 在控制台选择 Search 套餐，生成 API Key。
3. 将 Key 写入 OpenClaw 配置文件，或设置环境变量 BRAVE_API_KEY。

配置示例 #

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
            mode: "web", // 可选 "llm-context"
            baseUrl: "https://api.search.brave.com", // 代理或自定义基础 URL
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "brave",
        maxResults: 5,
        timeoutSeconds: 30,
      },
    },
  },
}

Brave 搜索的专属配置现在位于 plugins.entries.brave.config.webSearch.*。旧版 tools.web.search.apiKey 仍可通过兼容层读取，但已不再是推荐路径。

webSearch.mode 说明 #

• web（默认）：普通 Brave 网页搜索，返回标题、URL 和摘要。
• llm-context：使用 Brave LLM Context API，返回预先提取的文本块和来源，适合用于智能体 Grounding。

webSearch.baseUrl 说明 #

• 用于将 Brave 请求指向受信任的 Brave 兼容代理或网关。
• OpenClaw 会在配置的 baseUrl 后附加 /res/v1/web/search（web 模式）或 /res/v1/llm/context（llm-context 模式），并将 baseUrl 纳入缓存键。
• 公网端点必须使用 https://；只有信任的回环地址或私有网络代理主机才允许 http://。

工具参数 #

使用示例：

// 指定国家和语言搜索
await web_search({
  query: "renewable energy",
  country: "DE",
  language: "de",
});

// 近期结果（过去一周）
await web_search({
  query: "AI news",
  freshness: "week",
});

// 日期范围搜索
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

注意事项 #

• OpenClaw 使用的是 Brave Search 套餐。若你持有旧版订阅（如每月 2000 次查询的免费旧套餐），仍可使用，但不包含 LLM Context 等新特性或更高频率限制。
• 每个 Brave 套餐包含 每月 $5 免费额度（自动续期）。Search 套餐每 1000 次请求收费 $5，因此免费额度覆盖约 1000 次查询/月。建议在 Brave 控制台设置用量上限，避免意外扣费。详见 Brave API 门户。
• Search 套餐包含 LLM Context 端点和 AI 推理权限。如需存储结果用于训练或微调模型，需选择具有显式存储权限的套餐。详见 Brave 服务条款。
• llm-context 模式返回基于来源的条目，而非普通搜索摘要结构。
• llm-context 模式支持 freshness 和有边界范围的 date_after+date_before。不支持 ui_lang；单独使用 date_before 而无 date_after 会被拒绝，因为 Brave 要求自定义时间范围必须同时提供起止日期。
• ui_lang 必须包含地区子标签，如 en-US。
• 结果默认缓存 15 分钟，可通过 cacheTtlMinutes 调整。
• 自定义 webSearch.baseUrl 会纳入 Brave 缓存标识，因此不同代理的响应不会冲突。
• 调试时启用 brave.http 诊断标志，可记录 Brave 请求 URL/参数、响应状态/耗时以及缓存命中/未命中/写入事件。该标志不会记录 API Key 或响应内容，但搜索查询内容可能为敏感数据。

相关文档 #

• Web Search 概述 — 所有提供商及自动检测
• Perplexity Search — 结构化结果含域名过滤
• Exa Search — 神经搜索含内容提取

常见问题 #

Brave Search 每月免费额度是多少？ #

免费额度为每月 $5，自动续期。Search 套餐 $5/1000 次请求，所以每月可免费使用 1000 次查询。超出后需在 Brave 控制台设置上限防止意外扣费。

llm-context 模式为什么不能单独用 date_before？ #

Brave LLM Context API 要求自定义时间范围必须同时提供 date_after 和 date_before，否则拒绝请求。仅需时间范围时请使用 freshness 参数。

brave.http 诊断标志会泄露 API Key 吗？ #

不会。该标志仅记录请求 URL、参数、响应状态和缓存事件，不会记录 API Key 或响应正文。但搜索查询内容可能被日志记录，若涉及敏感信息需注意。