OpenClaw 安装 Tavily Search 完整指南：让 AI 助手真正能”上网搜索”

适用版本：OpenClaw 2026.3.x | 系统：Windows / macOS / Linux
前置要求：已安装 OpenClaw，拥有有效的 Tavily API Key

为什么你的 AI 助手搜不到东西？

很多人在使用 OpenClaw 接入飞书或其他渠道后，发现一个让人抓狂的问题：明明已经配置了搜索工具，AI 助手还是要么说”我不知道最新信息”，要么调用 Brave 搜索失败，要么干脆什么都搜不到。

这不是 AI 的问题，也不是你网络的问题。根本原因在于：OpenClaw 的 web_search 工具默认使用 Brave 搜索，而 Tavily 是一个独立的 Skill 插件，两者的配置方式完全不同。如果只是设置了系统环境变量 TAVILY_API_KEY，飞书等渠道的 OpenClaw 进程根本读不到这个值。

本文会从头到尾把整个配置过程讲清楚，包括常见报错的处理方法。

Tavily Search 是什么？为什么选它？

Tavily 是一个专为 AI Agent 设计的搜索 API，和 Google、Bing 这类面向人类用户的搜索引擎不同，它的结果格式对大语言模型更友好——返回的是结构化的摘要内容，而不是一堆网页链接列表。

对比维度	Tavily	Brave Search API
面向对象	AI Agent / LLM	开发者 / 人类用户
结果格式	结构化摘要	原始搜索结果
免费额度	每月 1,000 次	有限免费额度
接入方式	MCP / Skill 插件	Web Search 工具
适合场景	Agent 自动搜索	手动集成搜索

简单来说，如果你希望 AI 助手在回答问题时能自动查阅网络最新内容，Tavily 是目前最顺手的选择之一。

第一步：获取 Tavily API Key

打开 https://tavily.com
注册账号（支持 Google 账号快捷登录）
进入控制台，复制 API Key，格式类似：tvly-dev-xxxxxxxxxxxxxxxx

⚠️ 注意：免费套餐每月 1,000 次请求，个人日常使用完全够用。超出后需要升级付费计划。

第二步：了解 OpenClaw 的配置结构

在开始操作前，有必要理解 OpenClaw 配置文件 openclaw.json 的结构，这样遇到报错时你才能判断问题出在哪里。

openclaw.json 默认位于：

Windows：C:\Users\你的用户名\.openclaw\openclaw.json
macOS / Linux：~/.openclaw/openclaw.json

文件里有几个关键区块：

openclaw.json
├── tools          → 工具配置（只有 profile 等基础设置，不能随意添加字段）
├── skills         → Skill 插件（tavily-search 在这里）
├── plugins        → 渠道插件（feishu、qwen-portal-auth 等）
├── channels       → 渠道连接配置（飞书 appId、appSecret 等）
└── gateway        → 本地网关配置

最容易踩的坑：很多教程会让你在 tools 下面加 web_search 或 searchBackend 字段，但 OpenClaw 的配置校验会直接报错：

Config invalid
Problem:
  - tools: Unrecognized key: "web_search"
  - web: Unrecognized key: "searchBackend"

这些字段在当前版本中根本不存在，不要加。

第三步：正确配置 Tavily Search

3.1 通过命令行安装 Skill

打开终端（PowerShell 或 Terminal），执行：

npx clawhub install tavily-search --force

这条命令会把 tavily-search Skill 安装到 OpenClaw 的 skills 目录下。

3.2 写入 openclaw.json 配置

用文本编辑器打开配置文件：

# Windows
notepad C:\Users\你的用户名\.openclaw\openclaw.json

# macOS / Linux
nano ~/.openclaw/openclaw.json

找到 "skills" 区块，修改为：

"skills": {
  "entries": {
    "tavily-search": {
      "enabled": true,
      "env": {
        "TAVILY_API_KEY": "tvly-dev-你的实际APIKey"
      }
    }
  }
}

同时，在 "plugins" 的 "entries" 里新增 openclaw-tavily（与已有的 feishu 并列）：

"plugins": {
  "entries": {
    "qwen-portal-auth": {
      "enabled": true
    },
    "feishu": {
      "enabled": true
    },
    "openclaw-tavily": {
      "enabled": true,
      "config": {
        "apiKey": "tvly-dev-你的实际APIKey"
      }
    }
  }
}

⚠️ 为什么要写两个地方？
skills.entries 里的配置是给 Skill 运行脚本用的（通过环境变量读取）；plugins.entries 里的配置是让 OpenClaw 的插件系统识别并加载这个工具，两者缺一不可。

3.3 不要用这些命令

以下命令语法错误，会直接报错，不要用：

# ❌ 错误：--key 参数不存在
openclaw configure --section web --key tavily_api_key --value "xxx"

# ❌ 错误：tools 下没有 web_search 字段
openclaw config set tools.web_search.provider "tavily"

正确的 config set 用法是：

# ✅ 正确：直接设置 skills 路径下的配置
openclaw config set skills.entries.tavily-search.enabled true

第四步：验证配置并重启

4.1 验证配置文件

openclaw config validate

如果输出没有 Problem 字样，说明配置文件格式正确。

4.2 重启网关

openclaw gateway restart

4.3 检查 Skill 是否加载

openclaw skills list

在输出列表中，应该能看到 tavily-search 且状态为 enabled。

完整的 openclaw.json 配置示例

以下是一份完整的配置文件示例，供参考。请将 你的API Key 替换为实际值，其他字段根据自己的实际配置保留：

{
  "tools": {
    "profile": "full"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "你的飞书AppID",
      "appSecret": "你的飞书AppSecret",
      "connectionMode": "websocket",
      "domain": "feishu",
      "groupPolicy": "allowlist"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "你的gateway token"
    }
  },
  "skills": {
    "entries": {
      "tavily-search": {
        "enabled": true,
        "env": {
          "TAVILY_API_KEY": "tvly-dev-你的实际APIKey"
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      },
      "feishu": {
        "enabled": true
      },
      "openclaw-tavily": {
        "enabled": true,
        "config": {
          "apiKey": "tvly-dev-你的实际APIKey"
        }
      }
    }
  }
}

常见报错与解决方法

错误一：`Unrecognized key: "web_search"`

Config invalid
Problem:
  - tools: Unrecognized key: "web_search"

原因：tools 区块下没有 web_search 字段，是无效配置。
解决：删除 tools 下所有自行添加的字段，只保留 "profile": "full"。

错误二：`Unrecognized key: "searchBackend"`

Config invalid
Problem:
  - web: Unrecognized key: "searchBackend"

原因：之前某次配置尝试写入了不存在的 web.searchBackend 字段。
解决：找到并删除整个 "web": { ... } 段落，或仅删除 searchBackend 那一行。

错误三：`duplicate plugin id detected`

plugins.entries.feishu: plugin feishu: duplicate plugin id detected;
later plugin may be overridden

原因：飞书插件被加载了两次，通常是 extensions 目录下有多个飞书文件夹。
解决：

# 查看 extensions 目录
ls C:\Users\你的用户名\.openclaw\extensions\

# 重装飞书插件
openclaw plugin uninstall feishu
openclaw plugin install @openclaw/feishu

错误四：`Start-Process: 系统找不到指定的文件`

Start-Process : 由于出现以下错误，无法运行此命令: 系统找不到指定的文件。

原因：setup-env.ps1 脚本中的 Edge 浏览器路径写错了用户名，或者你的 Edge 安装路径与脚本预设不同。
解决：这个错误不影响 API Key 的实际配置。脚本输出了 ✅ 说明 Key 已写入，这个报错仅仅是”自动打开浏览器”这一步失败了，可以直接忽略。

如需彻底修复，让 API Key 永久生效：

[System.Environment]::SetEnvironmentVariable("TAVILY_API_KEY", "你的API Key", "User")

错误五：飞书中搜索功能仍然失败

如果 OpenClaw 本地已经能用 Tavily 搜索，但飞书里不行，通常有两个原因：

Key 只在系统环境变量里，没有写入 openclaw.json
→ 按本文第三步，把 Key 写入 skills.entries 和 plugins.entries 两个地方
飞书插件有重复冲突
→ 按”错误三”的方法重装飞书插件

安装后如何使用

配置成功后，你的 AI 助手拥有的是一个叫 tavily_search 的工具（注意：不是原来的 web_search，两者并存）。

在飞书或其他渠道里，你可以这样触发搜索：

“帮我搜索今天的 AI 行业新闻”
“查一下最新的 iPhone 价格”
“用 Tavily 搜索 OpenClaw 最新版本”

如果 AI 没有自动选择 Tavily，明确说”用 Tavily 搜索”即可。

Tavily 还支持以下搜索模式：

参数	说明
默认搜索	返回 5 条摘要结果，速度快
深度搜索（`--deep`）	返回更全面的结果，速度稍慢
新闻搜索（`--topic news`）	专注于新闻内容
指定结果数（`-n 10`）	返回更多条目

常见问题（FAQ）

Q：Tavily 免费版够用吗？
A：每月 1,000 次请求，对个人日常使用完全充裕。如果是团队共用或高频使用场景，需要升级付费计划。

Q：配置完成后需要重启电脑吗？
A：不需要。只需执行 openclaw gateway restart 重启本地网关即可。

Q：Tavily 和 Brave Search 能同时使用吗？
A：可以。OpenClaw 内置的 web_search 工具和 Tavily 的 tavily_search 工具是独立存在的，AI 助手会根据上下文自动选择，或者你可以明确指定使用哪个。

Q：为什么系统环境变量设置了 Key 但还是不生效？
A：飞书等渠道插件运行在 OpenClaw 的内部进程里，这个进程在启动时就已经建立，不会读取后来设置的系统环境变量。必须把 Key 写入 openclaw.json 的 skills.entries 才能生效。

Q：openclaw configure 和 openclaw config set 有什么区别？
A：openclaw configure 是交互式向导，会逐步引导你完成配置，适合初次设置；openclaw config set 是命令行直接写入配置项，适合自动化脚本或精确修改某个字段。

Q：配置文件改错了怎么办？
A：用本文提供的”完整配置示例”覆盖你的 openclaw.json，再按实际情况填入 appId、appSecret 等字段即可。

小结

整个配置过程的核心逻辑只有一句话：Tavily 是 Skill 插件，Key 必须写进 openclaw.json 的 skills 和 plugins 两个区块，系统环境变量对飞书渠道无效。

遇到配置报错时，优先看报错里提示的是哪个字段，然后对照本文的常见报错部分处理。绝大多数问题都是多余的字段或路径写错导致的，删掉或修正就能解决。

如果你在配置过程中遇到本文没有覆盖到的问题，可以先执行 openclaw config validate 看具体的错误字段，再有针对性地调整。

本文基于 OpenClaw 2026.3.13 版本验证，如版本更新导致配置方式变化，请以官方文档为准。

别再让AI当废物！OpenClaw安装Tavily搜索终极救赎指南