> 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).

# 网页搜索

代理可以自行搜索实时网页。默认情况下，这会运行在 **OpenHuman 托管版** search：查询会通过 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` ，使用你的密钥。                                                                                            |
| **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`；将通过环境变量提供的密钥视为敏感机密。

## 自托管 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，但不能 *发现* 一个。网页搜索是发现层：它为代理挑选合适的 URL，然后代理将它们交给 [网页抓取器](/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 客户端。
* [网页抓取器](/openhuman/zh/gong-neng/native-tools/web-scraper.md) - 获取并清理一个特定的 URL。
* [智能 Token 压缩](/openhuman/zh/gong-neng/token-compression.md) - 搜索摘要在送入模型之前会被压缩。