OpenClaw 配置 Tavily 搜索踩坑指南

背景

最近想给 OpenClaw 配置网络搜索功能，选择 Tavily 作为搜索后端——它专为 AI 应用优化，每月有免费额度。本以为几行配置就能搞定，结果踩了一堆坑。

这篇文章记录了完整的排查过程，希望能帮到遇到类似问题的朋友。

💡 核心教训

Gateway 是独立服务进程，不会继承 shell 环境变量！

这是所有问题的根本原因，也是最容易忽略的点。

踩坑过程

第一次尝试：随意猜测配置路径

凭记忆在配置文件中添加了：

"tools": {
  "web": {
    "search": {
      "tavily": {
        "apiKey": "tvly-xxx"
      }
    }
  }
}

结果：

Error: Config validation failed: tools.web.search.tavily
Unknown config keys

失败配置路径根本不存在。

第二次尝试：插件配置路径

查阅文档后发现应该通过插件配置，于是改成：

"plugins": {
  "entries": {
    "openclaw-tavily": {
      "enabled": true,
      "config": {
        "apiKey": "tvly-xxx"
      }
    }
  }
}

重启 Gateway 后检查日志：

[plugins] tavily: no API key found

失败插件加载了，但 API key 仍然没生效。

第三次尝试：清理重复配置

发现配置文件有重复条目，清理后重启。结果：

[plugins] tavily: idle (no API key)

仍失败问题不在重复配置。

根本原因

仔细分析日志和文档后，发现了关键点：

⚠️ 问题定位

Gateway 是通过 macOS LaunchAgent 服务启动的，运行在独立环境中，不会加载 .zshrc 等 shell 环境变量。

这意味着：

在终端 export TAVILY_API_KEY=xxx 无效
在 .zshrc 中配置环境变量无效
必须在 OpenClaw 配置中显式声明

正确方案

在配置文件顶层添加 env 块：

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  },
  "plugins": {
    "allow": ["openclaw-tavily"],
    "entries": {
      "openclaw-tavily": {
        "enabled": true
      }
    }
  }
}

同时确保插件已安装：

openclaw plugins install openclaw-tavily

重启 Gateway 后验证：

[plugins] tavily: initialized (depth=advanced, maxResults=5, answer=true, rawContent=false, timeout=30s, cacheTtl=15min)
[plugins] tavily: service started

✅ 配置成功！

Tavily 搜索服务已正常启动。

问题总结

问题	原因	解决方案
配置路径无效	`tools.web.search.tavily` 不是有效路径	使用正确的插件配置方式
API Key 不生效	Gateway 作为服务进程运行，不继承 shell 环境变量	在配置文件顶层添加 `env` 块
配置重复	多次编辑导致 JSON 有重复键	清理配置文件，确保无重复

配置对比

❌ 错误配置

// 方式1：错误路径
"tools": {
  "web": {
    "search": {
      "tavily": { "apiKey": "..." }
    }
  }
}

// 方式2：插件配置但缺少环境变量
"plugins": {
  "entries": {
    "openclaw-tavily": {
      "enabled": true,
      "config": { "apiKey": "..." }
    }
  }
}

// 方式3：shell 环境变量
export TAVILY_API_KEY="..."
// ❌ Gateway 服务进程不继承

✅ 正确配置

{
  // 顶层 env 块
  "env": {
    "TAVILY_API_KEY": "tvly-xxx"
  },
  "plugins": {
    // 白名单
    "allow": ["openclaw-tavily"],
    "entries": {
      "openclaw-tavily": {
        "enabled": true
      }
    },
    "installs": {
      "openclaw-tavily": {
        "source": "npm",
        "spec": "openclaw-tavily"
      }
    }
  }
}

验证步骤

1. 验证配置文件

openclaw config validate
# 输出：Config valid: ~/.openclaw/openclaw.json

2. 重启 Gateway

openclaw gateway restart

3. 检查日志

tail -f ~/.openclaw/logs/gateway.log | grep -i tavily
# 期望输出：
# [plugins] tavily: initialized (depth=advanced...)
# [plugins] tavily: service started

4. 检查状态

openclaw status --deep | grep -i tavily
# 期望输出：
# Enabled extension plugins: ... openclaw-tavily ...

5. 测试搜索

在 AI 助手中发起搜索请求，验证返回结果正常。

经验总结

1. 配置前先查文档

不要凭记忆配置！OpenClaw 的配置结构可能会变化，每次配置前先查阅官方文档：

官方文档：https://docs.openclaw.ai
插件配置：https://docs.openclaw.ai/plugins

2. 理解服务进程特性

Gateway 作为系统服务运行，与终端 shell 环境完全隔离：

不继承 shell 环境变量
不加载 .zshrc / .bashrc
需要显式配置 env 块

3. 配置验证流程

修改配置 → openclaw config validate → 重启 Gateway → 检查日志 → 测试功能

每一步都不能省略，尤其是日志检查。

4. 环境变量 vs 插件配置

类型	适用场景	配置位置
`env` 环境变量	API Key、密钥等敏感信息	配置文件顶层 `env` 块
`config` 插件配置	插件行为参数、非敏感配置	`plugins.entries.插件名.config`

写在最后

这次踩坑让我深刻理解了 OpenClaw 的服务架构。配置任何东西前，先查官方文档，不可凭记忆想当然。

希望这篇文章能帮到遇到类似问题的朋友。如果有其他问题，欢迎讨论交流。

背景