目录

1. 引言

2. web_search 介绍

2.1 什么是 web_search

2.2 申请 Brave Search API Key

第一步：注册 Brave Search API 账号

第二步：选择套餐并生成 API Key

2.3 将 API Key 配置到 OpenClaw

方式一：通过配置文件（推荐）

方式二：通过环境变量

2.4 如何使用 web_search

3. 问题描述

3.1 症状表现

3.2 根因分析

3.3 快速验证是否为此问题

4. 解决方案

方案：升级 Node.js 使内置 undici 与 OpenClaw 依赖匹配（推荐）

步骤 1：确认 OpenClaw 依赖的 undici 版本

步骤 2：确认所需 Node.js 版本

步骤 3：使用 nvm 升级 Node.js

步骤 4：重新安装 OpenClaw 依赖

步骤 5：重启 OpenClaw Gateway

步骤 6：验证

补充：WSL2 网络问题排查

5. 结语

1. 引言

OpenClaw 是一款功能强大的 AI 助手框架，内置了丰富的工具链，其中 web_search 是最常用的核心工具之一——它允许 AI 助手实时搜索互联网，获取最新信息。然而，在某些环境下，web_search 会抛出类似以下错误而无法正常工作，经过排查，这类问题的根源通常指向 undici 库的版本不适配。undici 是 Node.js 生态中广泛使用的 HTTP/1.1 客户端库，Node.js 内置的 fetch API 底层正是基于 undici 实现的。当 OpenClaw 依赖的 undici 版本与当前 Node.js 运行时内置版本存在冲突时，就会导致网络请求异常。本文将系统性地介绍如何配置 Brave Search API、分析问题根因，并提供详细的逐步解决方案。

适用环境： WSL2 / Linux，OpenClaw (openclaw-cn) + Node.js v20+或：

---

2. web_search 介绍

2.1 什么是 web_search

web_search 是 OpenClaw 提供的内置工具之一，允许 AI 助手通过搜索引擎查询互联网上的实时信息。当前默认使用 Brave Search API 作为搜索后端。

典型使用场景：

• 查询实时新闻、天气、股价等动态信息

• 搜索技术文档、API 参考

• 验证事实、查找最新数据

2.2 申请 Brave Search API Key

第一步：注册 Brave Search API 账号

1. 访问 Brave Search API 官网

2. 点击 Get Started for Free 注册账号

3. 完成邮箱验证并登录

第二步：选择套餐并生成 API Key

1. 在 Dashboard 中，选择 Data for Search 套餐（⚠️ 注意： Data for AI 套餐不兼容 web_search），这里订阅需要信用卡，没有的可以私信我，我给你发教程

2. 免费套餐通常包含每月 2000 次查询，足够日常使用

3. 点击 Create API Key，复制生成的密钥

2.3 将 API Key 配置到 OpenClaw

有两种方式配置：

方式一：通过配置文件（推荐）

编辑 OpenClaw 配置文件（通常位于 ~/.openclaw/config.json 或通过 openclaw config 命令找到）：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "BRAVE_API_KEY_HERE",    // 替换为你的实际 API Key
        maxResults: 5,                    // 每次搜索返回的最大结果数
        timeoutSeconds: 30,               // 超时时间
        cacheTtlMinutes: 15               // 缓存有效期（分钟）
      }
    }
  }
}

方式二：通过环境变量

在启动 OpenClaw Gateway 之前设置环境变量：

export BRAVE_API_KEY="your_api_key_here"

或将其写入 ~/.bashrc / ~/.zshrc 中持久化。

2.4 如何使用 web_search

配置完成后，AI 助手即可自动使用 web_search 工具。用户只需向助手提出需要搜索的问题即可：

用户：今天上海的天气怎么样？
助手：（自动调用 web_search 搜索 "上海天气" 并返回结果）

用户：帮我查一下 React 19 有什么新特性
助手：（自动调用 web_search 搜索并整理结果）

你也可以在 OpenClaw 会话中通过 /status 命令确认 web_search 工具是否已正确加载。

---

3. 问题描述

3.1 症状表现

在完成 Brave Search API 配置后，调用 web_search 时出现以下错误之一：

错误类型一：连接超时

web_search failed: TypeError: fetch failed
  [cause]: ConnectTimeoutError: Connect Timeout Error
      at Timeout.onConnectTimeout [as _onTimeout] (...)

错误类型二：请求失败（通用）

web_search failed: TypeError: fetch failed
  [cause]: Error: getaddrinfo ENOTFOUND api.search.brave.com

错误类型三：undici 抛出的异常

node:internal/deps/undici/undici:1
TypeError: fetch failed
    at Object.fetch (node:internal/deps/undici/undici:...)

3.2 根因分析

问题的核心在于 undici 版本冲突。具体机制如下：

1. Node.js 内置 undici： 从 Node.js v18 开始，fetch API 作为全局函数引入，底层依赖 Node.js 捆绑的 undici 库。不同 Node.js 版本捆绑的 undici 版本不同：

   • Node.js v20.x → undici ~5.x

   • Node.js v22.x → undici ~6.x

   • Node.js v26.x → undici ~7.x

2. OpenClaw 依赖的 undici： OpenClaw 的 node_modules 中有自己的 undici 依赖（例如 v7.25.0），通过 require('undici') 或直接使用 globalThis.fetch 调用。

3. 版本冲突场景： 当 Node.js 内置的 undici 版本与 OpenClaw node_modules 中的版本不一致时，可能出现：

   • HTTP/2 协议协商失败

   • TLS 握手行为差异

   • 连接池管理不兼容

   • 代理配置无法正确传递

   这些差异会导致对 api.search.brave.com 的 HTTPS 请求在 TLS 握手或连接建立阶段失败。

4. WSL2 特殊情况： 在 WSL2 环境下，网络层通过 Windows 主机进行 NAT 转发，DNS 解析和连接超时行为与原生 Linux 不同，进一步放大了版本冲突的影响。

3.3 快速验证是否为此问题

运行以下命令检查版本差异：

# 查看 Node.js 版本
node -v

# 查看 OpenClaw 依赖的 undici 版本
cat $(npm root -g)/openclaw-cn/node_modules/undici/package.json | grep '"version"'

# 查看 Node.js 内置 undici 版本
node -e "console.log(process.versions)"

如果两者主版本号不一致（如 Node.js 内置 6.x，OpenClaw 依赖 7.x），则大概率存在版本冲突。

---

4. 解决方案

方案：升级 Node.js 使内置 undici 与 OpenClaw 依赖匹配（推荐）

这是最干净、最根本的解决方式。

步骤 1：确认 OpenClaw 依赖的 undici 版本

cat $(npm root -g)/openclaw-cn/node_modules/undici/package.json | grep '"version"'

输出示例："version": "7.25.0"，说明 OpenClaw 需要 undici v7.x。

步骤 2：确认所需 Node.js 版本

• undici v7.x → 需要 Node.js v22+（推荐 v22 LTS 或 v26）

• undici v6.x → 需要 Node.js v20+

• 确保node里面的undici版本大于openclaw需要的版本

步骤 3：使用 nvm 升级 Node.js

# 查看当前已安装的 Node.js 版本
nvm ls

# 安装 Node.js 25（推荐）
nvm install 25

# 或安装最新的 Node.js 26
nvm install 26

# 切换到新版本
nvm use 25

# 设置为默认版本
nvm alias default 25

# 验证
node -v

步骤 4：重新安装 OpenClaw 依赖

# 重新全局安装 openclaw-cn
npm install -g openclaw-cn

# 重新安装只会更新库和依赖，不用从头配置，如果是英文版则去掉-cn

# 或者仅更新依赖
cd $(npm root -g)/openclaw-cn && npm update undici

步骤 5：重启 OpenClaw Gateway

openclaw gateway restart

步骤 6：验证

# 在 OpenClaw 会话中测试
# 对助手说：帮我搜索一下今天的科技新闻

---

补充：WSL2 网络问题排查

如果你在 WSL2 环境下，有可能是因为你的网络代理没有配置好导致无法访问到网络或者存在代理问题，首先C:\Users\<UserName>中创建一个.wslconfig文件，可以使用Powershell命令创建，然后记事本打开，在里面输入以下内容：

# Powershell创建.wslconfig
New-Item -Name .wslconfig -ItemType File

# cmd创建.wslconfig
echo. > .wslconfig

# 记事本打开.wslconfig输入以下内容：
[experimental]
networkingMode=mirrored
autoProxy=true
dnsTunneling=true
firewall=true
autoMemoryReclaim=gradual

• networkingMode=mirrored：和 Windows 共用同一 IP / 端口
• autoProxy=true：自动同步 Windows 的代理（如 Clash、VPN、系统代理）到 WSL2
• dnsTunneling=true：WSL2 的 DNS 解析走 Windows 的解析流程
• firewall=true：统一 Windows 和 WSL2 的防火墙规则，比如禁止外部访问 WSL2 的敏感端口，提升安全性
• autoMemoryReclaim=gradual：避免 WSL2 占着内存不释放，导致 Windows 卡顿

保存后重启wsl2，这样wsl就和windows共享一个代理，可以点击设置——网络和Internet——代理——手动设置代理 里面查看代理的ip地址和端口号，一般是https://127.0.0.1/7890，而wsl2也会走这个地址的代理，实现wsl2和windows网络互通，可以在wsl2中使用以下命令测试是否网络联通：

curl -I https://www.google.com

---

5. 结语

undici 版本不适配是 OpenClaw 使用 Brave Search API 时一个相对常见的问题，尤其在 WSL2 环境下更容易触发。其根本原因是 Node.js 运行时内置的 undici 版本与 OpenClaw 依赖的版本不一致，导致 HTTP 客户端行为异常。

核心解决思路： 让 Node.js 内置的 undici 版本与 OpenClaw node_modules 中的版本保持一致。

最佳实践：

1. 始终使用 Node.js LTS 版本（当前推荐 v25.x 或更高）

2. 定期运行 npm update -g openclaw-cn 保持 OpenClaw 及其依赖为最新版

3. 遇到网络工具异常时，优先检查 undici 和 Node.js 版本的兼容性

4. 在 WSL2 环境下，确保 DNS 和网络配置正确

如果按照本文方案操作后问题仍未解决，可以在评论区留言，我会逐一回复，如果是没有信用卡的用户，也可以留言，我将看情况是否出一个虚拟卡的注册教程。