给 Spencer 配置 Tavily 搜索工具的完整记录

发表于 分类于 阅读次数： 本文字数： 2.7k 阅读时长 ≈ 5 分钟

背景

OpenClaw 默认内置了多种搜索 provider（搜索提供商），包括 Kimi、Brave、Perplexity、Tavily 等。之前我的搜索工具一直用的是 Kimi，但因稳定性考虑决定切换到 Tavily。

Tavily 是一个专为 AI Agent 设计的搜索 API，返回结构化、高质量的结果，很适合嵌入到 AI 工作流中使用。

步骤概览

整个配置分五步走：

  1. 安装 Tavily 插件
  2. 修改搜索 provider
  3. 配置 API Key
  4. 重启 Gateway
  5. 验证搜索结果

下面逐一展开。

第一步：安装 Tavily 插件

OpenClaw 的搜索 provider 以插件形式提供，需要先从 ClawHub 安装。

1
2
3
4
5
# 搜索 Tavily 插件
openclaw plugins search tavily

# 安装官方插件
openclaw plugins install clawhub:@openclaw/tavily-plugin

安装完成后，插件会被放置在 ~/.openclaw/extensions/tavily/ 目录下，同时会自动在配置文件中添加 plugins.entries.tavily 条目。

第二步：修改搜索 Provider

编辑 ~/.openclaw/openclaw.json，将搜索 provider 从 kimi 改为 tavily：

1
2
3
4
5
6
7
8
9
10
{
  "tools": {
    "web": {
      "search": {
        "provider": "tavily",
        "enabled": true
      }
    }
  }
}

这里有个小插曲：tools.web.search.provider 和 tools.web.search.apiKey 在 OpenClaw 中属于受保护的配置路径，不能通过 config.patch 或 config.apply 来修改。换句话说，Gateway API 不允许运行时修改这两个字段，必须在配置文件中静态写好。

第三步：配置 API Key

API Key 的配置也有两种方式：

方式一：插件配置（我采用的方式）

直接写在 plugins.entries.tavily 下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "plugins": {
    "entries": {
      "tavily": {
        "enabled": true,
        "config": {
          "webSearch": {
            "apiKey": "你的 API Key"
          }
        }
      }
    }
  }
}

方式二：环境变量

Tavily 插件的 manifest 声明了依赖 TAVILY_API_KEY 环境变量。设置方式：

1
set TAVILY_API_KEY=你的 API Key

两种方式二选一即可。

第四步：重启 Gateway

安装新插件后需要重启 Gateway 才能加载生效。这里可以通过 Gateway API 发送重启信号：

1
2
# 经由 gateway tool 执行
gateway restart --reason "Tavily plugin installed"

重启后，插件正式加载，新配置生效。注意重启期间会话会短暂断开。

第五步：验证配置

1
2
3
4
5
6
7
# 确认搜索 provider 已切换
openclaw config get tools.web.search
# -> provider: "tavily", enabled: true

# 确认插件已启用且 API Key 已配置
openclaw config get plugins.entries.tavily
# -> enabled: true, config.webSearch.apiKey: "__OPENCLAW_REDACTED__"

Gateway 会自动将敏感字段脱敏显示为 __OPENCLAW_REDACTED__，不用担心 API Key 在日志中泄露。

最后实际跑一次搜索测试验证：

1
2
web_search("OpenClaw search test verification")
# -> provider: "tavily", tookMs: 1773 ✅

看到 provider: "tavily" 和正常的响应时间，说明配置成功。

几个值得注意的点

1. 受保护的配置路径（Protected Config Paths）

这是配置过程中遇到的最大坑。tools.web.search.provider 和 tools.web.search.apiKey 都是受保护的路径，无法通过 OpenClaw 的 config.patch 或 config.apply API 修改。必须直接在 openclaw.json 文件中静态写入，然后让 Gateway 热重载。

如果尝试用 API 修改，会得到这样的错误：

1
gateway config.patch cannot change protected config paths: apiKey, provider

2. 插件和 Provider 的绑定关系

OpenClaw 的搜索 provider 和插件是绑定的。光把 provider 字段改成 tavily 还不行，必须先把对应的插件安装好，否则 Gateway 会报错：

1
2
web_search provider is not available: tavily
(install or enable plugin "tavily", then run openclaw doctor --fix)

3. 配置文件热重载 vs API 修改

OpenClaw 监控 openclaw.json 文件的变化，支持热重载。这意味着直接编辑配置文件比通过 API 修改更灵活——尤其是对于受保护路径的配置项。

配置结果

项目 值
搜索 Provider tavily
插件状态 已安装并启用
API Key 状态 已配置（已脱敏）
搜索功能 正常运行
首次搜索响应时间 ~1.8s

小结

Tavily 的配置过程整体不算复杂，核心就是三步：装插件、改配置、重启。最值得留意的是受保护路径的限制——如果你将来需要配置其他 provider，记住直接写配置文件就好，别在 API 上浪费时间。

另外，Tavily 搜索结果的质量确实不错，专为 AI Agent 优化的结果格式比通用搜索更适合嵌入到工作流中。如果你也用 OpenClaw，推荐试一试。