> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/native-tools/web-search.md).

# 网页搜索

代理可以直接调用的原生搜索工具——托管搜索由 Exa 提供支持，无需 API 密钥。

代理可以自行搜索实时网络。默认情况下，这一功能运行在 **OpenHuman 托管版** 搜索：查询会通过 OpenHuman 后端，当前由以下服务提供支持： [Exa](https://exa.ai)，因此你无需持有搜索 API 密钥。你也可以为 Exa、Brave 或 Querit 使用自己的密钥，或者启用由后端代理的 Parallel 引擎。如果你运行自己的 [SearXNG](https://docs.searxng.org/) 实例，你可以将 `searxng_search` 作为私有、自托管的搜索工具暴露给 RPC 和 MCP 客户端。

## 适用场景

* 研究——“X 的最新情况是什么”。
* 查找引用——“帮我找三条关于 Y 的来源”。
* 回答前进行事实核查——如果代理没有把握，它会快速搜索一下。

## 搜索引擎

在以下位置选择引擎： **连接 → 搜索**。任意时刻只有一个引擎处于活动状态，该引擎负责提供规范的 `web_search_tool` ，供代理调用。

| 引擎                     | 设置        | 你的查询会去哪里                                                                                                                      |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **OpenHuman 托管版** （默认） | 不需要       | OpenHuman 后端，当前由以下服务提供支持： [Exa](https://exa.ai).                                                                              |
| **Exa**                | 你的 API 密钥 | 直接到 `https://api.exa.ai` ，使用你的密钥。                                                                                             |
| **Tavily**             | 你的 API 密钥 | 直接到 `https://api.tavily.com` ，使用你的密钥（网页 / 新闻 / 金融搜索 + 页面提取）。                                                                  |
| **Parallel**           | 本地启用值     | Parallel 特定工具会通过 OpenHuman 后端转发给 Parallel；规范的 `web_search_tool` 继续使用后端解析出的托管提供商（当前为 Exa）。该值仅在本地选择引擎，不会发送给 Parallel 进行身份验证或计费。 |
| **Brave**              | 你的 API 密钥 | 直接使用你的密钥连接到 Brave Search API。                                                                                                 |
| **Querit**             | 你的 API 密钥 | 直接使用你的密钥连接到 Querit API。                                                                                                       |
| **已禁用**                | 不需要       | 哪里都不会去。所有面向代理的搜索工具都会被移除；但已启用的 SearXNG 端点仍可通过 RPC/MCP 使用。                                                                      |

选择“自带密钥”引擎但未保存密钥时，会回退到托管搜索。该回退需要一个经过后端身份验证的会话；本地或离线用户必须配置直接的提供商密钥。一旦搜索完成，聊天时间线会标明回答它的提供商（“使用 Exa 搜索”），因此托管路径绝不会是一个无归属的黑盒。

### OpenHuman 托管版（默认）

托管搜索是开箱即用的路径，无需任何设置：它通过你现有的订阅经由 OpenHuman 后端代理，目前其背后的提供商是 Exa。你的机器不会保存任何搜索凭据，代理只获得这一个 `web_search_tool` 槽位。

### Exa（自带密钥）

想在自己的 Exa 账户上运行搜索？从以下地址获取密钥： [exa.ai](https://exa.ai) ，然后粘贴到 **连接 → 搜索 → Exa**下。随后调用会直接从你的机器发往 `https://api.exa.ai` ，使用你的密钥，完全不会接触托管后端。启用密钥加密时，OpenHuman 会将该密钥以密文形式存储在 `config.toml`中；操作系统密钥环保护的是主加密密钥，而不是 Exa 密钥本身。

选择 Exa 会为代理注册 Exa 的神经搜索系列功能，并叠加常规的 `web_search_tool`:

* `exa_search` ——带有 URL、标题、发布日期以及可选页面文本的排名页面。支持从即时到深度推理的搜索模式、域名包含/排除过滤器、发布日期范围和结果类别。
* `exa_find_similar` ——与你已有的某个 URL 在语义上相似的页面，可用于从一个优质来源扩展到可比较的来源（竞争对手、相关论文、相似文章）。此工具使用的是 Exa 已弃用的 `/findSimilar` 端点，如果 Exa 移除它，可能会发生变化。
* `exa_get_contents` ——一个或多个 URL 的完整抓取内容，可为每个 URL 提供可选摘要或与查询相关的高亮。

你也可以在以下位置选择它： `config.toml`:

```toml
[search]
engine = "exa"

[search.exa]
api_key = "your-exa-api-key"
```

不要将此示例中的明文 API 密钥提交到仓库。直接在 `config.toml` 中输入的密钥，在 OpenHuman 下次以启用密钥加密的方式保存配置之前，都会保持为明文。

或者通过环境变量：

```bash
OPENHUMAN_SEARCH_ENGINE=exa
EXA_API_KEY=your-exa-api-key
# 也接受 OPENHUMAN_EXA_API_KEY
```

`OPENHUMAN_EXA_API_KEY` 和 `EXA_API_KEY` 都会覆盖 `search.exa.api_key`；请将环境变量提供的密钥视为敏感机密。

### Tavily（自带密钥）

想在自己的 [Tavily](https://tavily.com) 账户上运行搜索？从以下地址获取密钥： [tavily.com](https://tavily.com) ，然后粘贴到 **连接 → 搜索 → Tavily**下。随后调用会直接从你的机器发往 `https://api.tavily.com` ，使用你的密钥，完全不会接触托管后端。启用密钥加密时，OpenHuman 会将该密钥以密文形式存储在 `config.toml`；操作系统密钥环保护的是主加密密钥，而不是 Tavily 密钥本身。

选择 Tavily 会为代理注册 Tavily 的搜索 + 提取系列功能，并叠加常规的 `web_search_tool`:

* `tavily_search` ——包含标题、URL 和摘要的网页、新闻和金融结果。支持搜索深度级别（`基础`/`高级`/`快速`/`超快`）、发布/更新时间范围（ `time_range` 或显式的 `start_date`/`end_date`）、域名包含/排除过滤器、可选的 LLM 生成的 `回答`、有界的清理后页面内容和图片链接。
* `tavily_extract` ——从一个或多个 URL 中提取清理后的内容，以 Markdown 或纯文本形式呈现，用于代理找到的深度阅读来源。代理输出对每个 URL 限制为 8,000 个字符。

你也可以在以下位置选择它： `config.toml`:

```toml
[search]
engine = "tavily"

[search.tavily]
api_key = "tvly-your-tavily-api-key"
```

或者通过环境变量：

```bash
OPENHUMAN_SEARCH_ENGINE=tavily
TAVILY_API_KEY=tvly-your-tavily-api-key
# 也接受 OPENHUMAN_TAVILY_API_KEY
```

`OPENHUMAN_TAVILY_API_KEY` 和 `TAVILY_API_KEY` 都会覆盖 `search.tavily.api_key`。不要提交明文 API 密钥。

## 自托管 SearXNG

SearXNG 搜索为可选启用，并通过以下方式暴露： `openhuman.tools_searxng_search` RPC 控制器和 MCP 目录；它不会被注册为代理工具。控制器会调用你配置的 SearXNG `/search?format=json` 端点，并返回标准化的 `{ title, url, snippet, source }` 结果。

在以下位置启用它： `config.toml`:

```toml
[searxng]
enabled = true
base_url = "http://localhost:8080"
max_results = 10
default_language = "en"
timeout_seconds = 10
```

或者通过环境变量：

```bash
OPENHUMAN_SEARXNG_ENABLED=true
OPENHUMAN_SEARXNG_BASE_URL=http://localhost:8080
OPENHUMAN_SEARXNG_MAX_RESULTS=10
OPENHUMAN_SEARXNG_DEFAULT_LANGUAGE=en
OPENHUMAN_SEARXNG_TIMEOUT_SECONDS=10
```

每次调用时，该工具接受 `query`，可选的 `categories` (`web`, `news`, `images`）、可选的 `language`，以及可选的 `max_results` ，最多 50 个。空查询、不支持的类别、非 2xx 的 SearXNG 响应以及超时失败都会返回结构化工具错误，而不是静默回退到云端搜索提供商。

## 它与通用 HTTP 的区别

纯粹的 `http_request` 工具可以获取一个 URL，但不能 *查找* 它。Web Search 是发现层：它为代理挑选合适的 URL，然后将它们交给 [Web Scraper](/openhuman/zh/gong-neng/native-tools/web-scraper.md) 进行实际读取。

## 另请参阅

* [MCP 服务器](https://github.com/tinyhumansai/openhuman/tree/main/gitbooks/developing/mcp-server.md) ——如何 `searxng_search` 出现在 MCP 客户端中。
* [Web Scraper](/openhuman/zh/gong-neng/native-tools/web-scraper.md) ——获取并清理一个特定 URL。
* [智能令牌压缩](/openhuman/zh/gong-neng/token-compression.md) ——搜索摘要在进入模型之前会先被压缩。