OpenClaw 接入 Google/Brave/Perplexity/Grok/Kimi 搜索引擎完整教程

难度: 中级 | 时长: 15 分钟 | 收获: 掌握 OpenClaw 5 大搜索 provider 配置方法

目标读者

• 已安装 OpenClaw 并想启用搜索功能的开发者
• 对 AI Agent 工具配置感兴趣的 1-5 年经验工程师
• 想让 OpenClaw 具备实时网络搜索能力的朋友

核心依赖

• Node.js 18+
• OpenClaw (最新版本)
• 至少一个搜索 provider 的 API Key

项目结构

openclaw/
├── config.yaml              # 主配置文件
├── .env                     # 环境变量（可选）
└── src/
    └── agents/tools/
        └── web-search.ts    # 搜索实现

1. 为什么需要配置搜索 provider

OpenClaw 的核心能力之一是让 AI Agent 能够实时联网搜索。当你的 agent 需要查资料、了解最新信息或者验证事实时，搜索工具就是它的"眼睛"。

OpenClaw 支持 5 大搜索 provider，你可以根据需求选择：

2. 配置方式一：环境变量

最简单的方式是通过环境变量配置。OpenClaw 启动时会自动读取环境变量并启用对应的搜索 provider。

2.1 各 provider 对应环境变量

# Perplexity
export PERPLEXITY_API_KEY="pplx-xxxxxxxxxxxx"

# Brave Search
export BRAVE_API_KEY="BSAxxxxxxxxxxxx"

# Gemini (Google)
export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxx"

# Grok (xAI)
export XAI_API_KEY="xai-xxxxxxxxxxxx"

# Kimi (Moonshot) - 两种都支持
export KIMI_API_KEY="sk-xxxxxxxxxxxx"
# 或者
export MOONSHOT_API_KEY="sk-xxxxxxxxxxxx"

2.2 完整示例

创建一个 .env 文件：

# OpenClaw 配置
OPENCLAW_SECRET_INPUT_MODE=ref

# 搜索 provider (选择其一)
PERPLEXITY_API_KEY=pplx_xxxxxxxxxxxxxxxx

# 其他可选配置
LOG_LEVEL=info

然后启动 OpenClaw：

openclaw start

3. 配置方式二：config.yaml

对于更精细的控制，可以直接在 config.yaml 中配置。

3.1 基础配置结构

tools:
  web:
    search:
      enabled: true
      provider: perplexity  # 选择 provider
      maxResults: 5         # 返回结果数量 1-10
      timeoutSeconds: 30    # 请求超时
      cacheTtlMinutes: 15   # 缓存时间

3.2 各 provider 独立配置

tools:
  web:
    search:
      enabled: true
      provider: perplexity
      maxResults: 5

      # Perplexity 配置
      perplexity:
        apiKey: pplx_xxxxxxxxxxxx

      # Brave 配置 (provider 为 brave 时使用)
      apiKey: BSAxxxxxxxxxxxx

      # Grok 配置 (provider 为 grok 时使用)
      grok:
        apiKey: xai-xxxxxxxxxxxx
        model: grok-4-1-fast
        inlineCitations: false

      # Gemini 配置 (provider 为 gemini 时使用)
      gemini:
        apiKey: AIzaSyxxxxxxxxxxxx
        model: gemini-2.5-flash

      # Kimi 配置 (provider 为 kimi 时使用)
      kimi:
        apiKey: sk-xxxxxxxxxxxx
        baseUrl: https://api.moonshot.ai/v1
        model: moonshot-v1-128k

4. 实战配置示例

接下来我们用两种方式配置最流行的 Perplexity。

4.1 Perplexity：精准过滤搜索

步骤 1: 获取 API Key

访问 Perplexity API Settings 注册账号并生成 API Key。Perplexity API 需要单独的 API 账单，和个人订阅账户分开管理。

步骤 2: 设置环境变量

# Linux/macOS
export PERPLEXITY_API_KEY="pplx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Windows (PowerShell)
$env:PERPLEXITY_API_KEY="pplx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

步骤 3: 启动 OpenClaw

openclaw start

OpenClaw 会自动检测到 PERPLEXITY_API_KEY 并启用 Perplexity 搜索。

模型选择说明：

Perplexity 有两个主力模型：

• sonar — 轻量快速，127K 上下文，适合高频简单查询（$1/M tokens）
• sonar-pro — 高推理能力，200K 上下文，适合复杂研究任务（$6/M tokens）

进阶过滤配置（config.yaml）：

tools:
  web:
    search:
      enabled: true
      provider: perplexity
      maxResults: 5
      perplexity:
        apiKey:
          source: env
          provider: default
          id: PERPLEXITY_API_KEY
        # 搜索时间范围过滤：hour / day / week / month
        searchRecencyFilter: week
        # 仅搜索特定域名（如限制到权威来源）
        searchDomainFilter:
          - "github.com"
          - "stackoverflow.com"

速率限制：默认 50 请求/分钟，底层采用 leaky bucket 算法，支持短时突发。若遇到 429 错误，建议实现指数退避重试。

4.2 Brave Search：隐私优先的区域搜索

步骤 1: 注册 Brave Search API

访问 Brave Search API Dashboard，每月提供约 1000 次免费查询（$5 免费额度），超出后 $5/1000 次。

export BRAVE_API_KEY="BSAxxxxxxxxxxxxxxxx"

步骤 2: 配置 provider 为 brave

tools:
  web:
    search:
      provider: brave
      apiKey:
        source: env
        provider: default
        id: BRAVE_API_KEY
      brave:
        # 指定国家/地区（ISO 3166-1 alpha-2 格式，如 US / GB / DE / JP / CN）
        country: US
        searchLang: en
        # 时间新鲜度：pd(天) / pw(周) / pm(月) / py(年)
        freshness: pw

Brave Goggles（自定义排名）：Brave 独有的 Goggles 功能可自定义搜索结果排名，支持优先展示技术文档站点、屏蔽低质内容农场等，适合垂直场景搜索。

成本控制建议：在 Brave Dashboard 中设置用量上限，避免意外超出预算。建议结合缓存（cacheTtlMinutes: 60）降低调用频次。

4.3 Gemini：Google AI 搜索 Grounding

步骤 1: 获取 Gemini API Key

访问 Google AI Studio 创建 API Key，免费额度相对充足。

export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxx"

步骤 2: 配置

tools:
  web:
    search:
      provider: gemini
      gemini:
        apiKey:
          source: env
          provider: default
          id: GEMINI_API_KEY
        model: gemini-2.5-flash

工作原理：Gemini 通过 Google Search Grounding 自动判断是否需要联网，当需要时会自动执行搜索并在响应中附带 groundingMetadata（含搜索来源和引用）。不是每次请求都一定触发搜索。

计费方式：按 prompt 次数计费（非每次搜索），Gemini 2.5 及以下版本如此。每日上限 100 万次查询。

4.4 Grok：网络 + X 平台双搜索

Grok 的独特优势是可以同时搜索网络和 X（Twitter）平台内容，适合追踪实时社交媒体动态。

export XAI_API_KEY="xai-xxxxxxxxxxxx"

tools:
  web:
    search:
      provider: grok
      grok:
        apiKey:
          source: env
          provider: default
          id: XAI_API_KEY
        # 推荐模型：专为 agentic 搜索优化
        model: grok-4-1-fast
        # 启用内联引用，响应中包含 [[1]](url) 格式标注
        inlineCitations: true

双搜索组合：Grok 支持同时启用 web_search（通用网络）和 x_search（X 平台），可锁定特定账号或日期范围：

grok:
  tools:
    - type: web_search
      # 搜索时解析图片内容
      enableImageUnderstanding: true
    - type: x_search
      # 只看 2025 年以后的 X 内容
      fromDate: "2025-01-01"
      # 只追踪特定账号动态
      allowedXHandles:
        - "elonmusk"
        - "xai"

计费提醒：web_search 和 x_search 各 $10/1000 次工具调用，token 费用另计。高频使用时注意监控用量。

4.5 Kimi：超长上下文 + 极低成本

Kimi 是 Moonshot AI 推出的大模型，API 定价极具竞争力（$0.60/$2.50 per M tokens），且内置自动上下文缓存（节省 75% 输入费用），适合需要大量搜索结果摘要或长文档处理的场景。

export KIMI_API_KEY="sk-xxxxxxxxxxxx"
# 或者
export MOONSHOT_API_KEY="sk-xxxxxxxxxxxx"

tools:
  web:
    search:
      provider: kimi
      kimi:
        apiKey:
          source: env
          provider: default
          id: KIMI_API_KEY
        # 默认使用国际节点；中国大陆可切换至 api.moonshot.cn
        baseUrl: https://api.moonshot.ai/v1
        # 推荐用最新 K2 系列，支持原生 $web_search 工具
        model: kimi-k2.5
        # Instant 模式（非思考模式），适合快速搜索
        temperature: 0.6

Endpoint 选择：

• 全球节点（推荐）：https://api.moonshot.ai/v1
• 中国大陆节点：https://api.moonshot.cn/v1

模型版本说明：旧版 moonshot-v1-128k 系列已属 legacy，新项目建议直接用 K2 系列（kimi-k2.5、kimi-k2-turbo-preview），支持原生 $web_search 内置工具，搜索每次调用仅 $0.005。

5. 验证配置

配置完成后，测试搜索功能是否正常工作。

5.1 使用命令行测试

openclaw configure --section web

这会启动交互式配置向导，检查当前搜索配置状态。

5.2 在对话中测试

启动 OpenClaw 后，向 agent 提问：

What's the latest version of Node.js?

如果配置正确，agent 会联网搜索并返回最新信息。

5.3 查看日志

openclaw logs --tail 50

搜索相关的日志会显示请求是否成功。

6. 进阶配置

6.1 超时与缓存

tools:
  web:
    search:
      timeoutSeconds: 30    # 请求超时 30 秒
      cacheTtlMinutes: 15  # 缓存结果 15 分钟

6.2 结果数量控制

tools:
  web:
    search:
      maxResults: 10  # 最多返回 10 条结果

6.3 禁用搜索

如果暂时不需要搜索功能：

tools:
  web:
    search:
      enabled: false

7. 常见问题排查

Q1: 搜索返回 "No API key configured"

原因: 没有配置 API Key 或环境变量未正确设置。

解决:

# 确认环境变量已设置
echo $PERPLEXITY_API_KEY

# 如果为空，重新设置
export PERPLEXITY_API_KEY="your-key-here"

Q2: 请求超时

原因: 网络问题或 provider 服务繁忙。

解决: 增加超时配置：

tools:
  web:
    search:
      timeoutSeconds: 60

Q3: 搜索结果不理想

原因: 不同 provider 返回结果风格不同。

解决: 尝试切换 provider，或调整 maxResults 获取更多结果。

Q4: 缓存相关问题

原因: 旧缓存导致结果不更新。

解决: 设置 cacheTtlMinutes: 0 禁用缓存，或等待缓存过期。

Q5: 不知道选哪个 provider

推荐选择:

• Perplexity - 综合体验最好，支持结构化搜索；sonar 模型轻量快速，sonar-pro 适合深度研究
• Gemini - 免费额度多，Google 生态，按 prompt 次数计费更可预期
• Brave - 注重隐私，每月 ~1000 次免费；Goggles 自定义排名是独特优势
• Grok - 需要实时 X 平台内容时的唯一选择，网络+社交双搜索
• Kimi - 定价最低，256K 超长上下文，自动缓存大幅节省成本

Q6: API Key 安全性

建议:

• 永远使用环境变量或 secretInputMode: ref
• 不要把 API Key 明文写在 config.yaml
• 定期轮换 API Key（建议每 3-6 个月）
• 在各 provider Dashboard 设置用量上限，防止意外超支

Q7: Grok 搜索报错 "search_parameters is not a valid field"

原因: 使用了已废弃的旧版 Live Search API。

解决: xAI 旧版 search_parameters 于 2025 年 12 月底废弃，需升级到新的 Agent Tools API（web_search / x_search）。确保 OpenClaw 已更新到最新版本。

Q8: Gemini 有时不触发搜索

原因: Gemini 会自主判断是否需要联网，不是每次都触发 Google Search Grounding。

解决: 这是正常行为。如果需要强制联网，可以在提问中明确加上"请搜索最新信息"等指令。响应中有 groundingMetadata 字段说明确实触发了搜索。

8. 进阶方向

• 多 provider 故障切换: 主 provider 不可用时自动切换备用 provider，提升可用性
• Perplexity 域名白名单: 用 searchDomainFilter 限定权威域名，提升专业查询准确率
• Brave Goggles 自定义: 针对技术文档、学术论文等垂直场景定制搜索排名规则
• Grok 双搜索组合: 结合 web_search + x_search 实现网络与实时社交内容融合
• Kimi 长上下文搜索: 利用 256K 上下文将大量搜索结果一次性喂给模型分析
• Firecrawl 集成: 配合网页抓取实现深度研究，适合需要阅读完整网页内容的场景
• 搜索结果缓存优化: 针对高频查询设置合理缓存 TTL，大幅降低 API 费用

---

延伸阅读:

• OpenClaw 官方文档 - Web Tools
• Perplexity API 文档
• Brave Search API 文档
• Gemini Grounding with Google Search
• xAI Grok Live Search 文档
• Moonshot AI 开放平台