` 块，
OpenClaw 会保持启动过程的韧性并报告警告，以便你重新安装
插件或运行 `openclaw doctor --fix` 清理过期配置。
`web_fetch` 回退提供商的选择是独立的：
- 通过 `tools.web.fetch.provider` 选择
- 或省略该字段，让 OpenClaw 根据已配置的凭据自动检测第一个就绪的 Web 提取
提供商
- 非沙箱隔离的 `web_fetch` 可以使用声明了
`contracts.webFetchProviders` 的已安装插件提供商；沙箱隔离的提取允许使用内置提供商和
经验证的官方插件安装，但排除第三方外部插件
- 官方 Firecrawl 插件是目前唯一内置的 `webFetchProviders`
贡献者，其配置位于
`plugins.entries.firecrawl.config.webFetch.*` 下
当你在 `openclaw onboard` 或
`openclaw configure --section web` 期间选择 **Kimi** 时，OpenClaw 还可以询问：
- Moonshot API 区域（`https://api.moonshot.ai/v1` 或 `https://api.moonshot.cn/v1`）
- 默认 Kimi Web 搜索模型（默认为 `kimi-k2.6`）
对于 `x_search`，请配置 `plugins.entries.xai.config.xSearch.*`。它使用与聊天相同的
xAI 身份验证配置文件，或 Grok Web 搜索所用的 `XAI_API_KEY` / 插件 Web 搜索
凭据。
旧版 `tools.web.x_search.*` 配置会由 `openclaw doctor --fix` 自动迁移。
当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 Grok 时，
OpenClaw 还会在 Grok 设置完成后，使用相同凭据提供可选的 `x_search` 设置。这是 Grok
路径中的一个独立后续步骤，而不是单独的顶层 Web 搜索提供商选项。如果你选择其他
提供商，OpenClaw 不会显示 `x_search` 提示。
### 存储 API 密钥
**配置文件**
运行 `openclaw configure --section web` 或直接设置密钥：
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "YOUR_KEY", // pragma: allowlist secret
},
},
},
},
},
}
```
**环境变量**
在 Gateway 网关进程环境中设置提供商环境变量：
```bash
export BRAVE_API_KEY="YOUR_KEY"
```
对于 Gateway 网关安装，请将其放入 `~/.openclaw/.env`。
请参阅[环境变量](https://funcoding.ai/agents/openclaw/help/faq/#env-vars-and-env-loading)。
## 工具参数
| 参数 | 描述 |
| --------------------- | ------------------------------------------------------------ |
| `query` | 搜索查询（必填） |
| `count` | 返回的结果数（1-10，默认值：5） |
| `country` | 2 字母 ISO 国家/地区代码（例如 "US"、"DE"） |
| `language` | ISO 639-1 语言代码（例如 "en"、"de"） |
| `search_lang` | 搜索语言代码（仅限 Brave） |
| `freshness` | 时间筛选条件：`day`、`week`、`month` 或 `year` |
| `date_after` | 此日期之后的结果（YYYY-MM-DD） |
| `date_before` | 此日期之前的结果（YYYY-MM-DD） |
| `ui_lang` | UI 语言代码（仅限 Brave） |
| `domain_filter` | 域名允许列表/拒绝列表数组（仅限 Perplexity） |
| `max_tokens` | 总内容 token 预算，仅限原生 Perplexity Search API |
| `max_tokens_per_page` | 每页提取 token 上限，仅限原生 Perplexity Search API |
并非所有参数都适用于所有提供商。Brave `llm-context` 模式
会拒绝 `ui_lang`；`date_before` 还需要 `date_after`，因为 Brave 自定义
时效范围要求同时指定开始日期和结束日期。
Gemini、Grok 和 Kimi 会返回一个带引用的综合答案。它们
接受 `count` 以实现共享工具兼容性，但该参数不会改变
基于搜索结果的答案形式。Gemini 将 `day` 时效条件视为近期程度提示；更宽泛的
时效值和明确日期会设置 Google Search 的搜索依据时间范围。
通过 Sonar/OpenRouter
兼容路径（`plugins.entries.perplexity.config.webSearch.baseUrl` /
`model` 或 `OPENROUTER_API_KEY`）使用 Perplexity 时，其行为也相同；该路径还不支持 `max_tokens` 和
`max_tokens_per_page`。
SearXNG 仅对受信任的专用网络或 local loopback 主机接受 `http://`；
公共 SearXNG 端点必须使用 `https://`。
Firecrawl 和 Tavily 仅通过 `web_search` 支持 `query` 和 `count`
——如需高级选项，请使用它们的专用工具。
## x_search
`x_search` 使用 xAI 查询 X（原 Twitter）帖子，并返回
带引用的 AI 综合答案。它接受自然语言查询和
可选的结构化筛选条件。OpenClaw 会为每个请求构造内置的 xAI `x_search`
工具，而不会将其永久注册，因此该工具仅在实际调用它的轮次中
处于活动状态。
`x_search` 在 xAI 的服务器上运行。xAI 对每 1,000 次工具调用收取 $5，此外还会收取
模型输入和输出 token 的费用。
xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户
搜索和话题串获取。对于转发数、
回复数、书签数或浏览量等单篇帖子互动统计数据，建议针对确切帖子 URL
或状态 ID 进行定向查询。宽泛的关键词搜索可能会找到正确的帖子，但返回的
单篇帖子元数据可能不够完整。推荐的做法是：先找到帖子，然后
运行第二个 `x_search` 查询，聚焦于该确切帖子。
### x_search 配置
省略 `enabled` 时，仅当活动模型的
提供商为 `xai` 且能解析到 xAI 凭据时，才会公开 `x_search`。对于使用已知
非 xAI 提供商的活动模型，将 `plugins.entries.xai.config.xSearch.enabled` 设为 `true` 可
选择启用跨提供商使用。如果活动模型提供商缺失或
无法解析，该工具将保持隐藏。将 `enabled` 设为 `false` 可对
所有提供商禁用该工具。始终需要 xAI 凭据。
```json5
{
plugins: {
entries: {
xai: {
config: {
xSearch: {
enabled: true, // 使用已知非 xAI 模型提供商时必需
model: "grok-4.3",
baseUrl: "https://api.x.ai/v1", // 可选，覆盖 webSearch.baseUrl
inlineCitations: false,
maxTurns: 2,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
},
webSearch: {
apiKey: "xai-...", // 如果已设置 xAI 身份验证配置文件或 XAI_API_KEY，则为可选
baseUrl: "https://api.x.ai/v1", // 可选的共享 xAI Responses 基础 URL
},
},
},
},
},
}
```
设置 `plugins.entries.xai.config.xSearch.baseUrl` 后，`x_search` 会向 `/responses`
发送 POST 请求。如果省略该字段，
则回退到 `plugins.entries.xai.config.webSearch.baseUrl`，然后回退到
公共 xAI 端点（`https://api.x.ai/v1`）。
### x_search 参数
| 参数 | 描述 |
| ---------------------------- | ------------------------------------------------------ |
| `query` | 搜索查询（必填） |
| `allowed_x_handles` | 将结果限制为最多 20 个 X 用户名 |
| `excluded_x_handles` | 排除最多 20 个 X 用户名 |
| `from_date` | 仅包含此日期当日或之后的帖子（YYYY-MM-DD） |
| `to_date` | 仅包含此日期当日或之前的帖子（YYYY-MM-DD） |
| `enable_image_understanding` | 允许 xAI 检查匹配帖子所附的图片 |
| `enable_video_understanding` | 允许 xAI 检查匹配帖子所附的视频 |
`allowed_x_handles` 和 `excluded_x_handles` 互斥。
### x_search 示例
```javascript
await x_search({
query: "dinner recipes",
allowed_x_handles: ["nytfood"],
from_date: "2026-03-01",
});
```
```javascript
// 单篇帖子统计数据：尽可能使用确切的状态 URL 或状态 ID
await x_search({
query: "https://x.com/huntharo/status/1905678901234567890",
});
```
## 示例
```javascript
// 基本搜索
await web_search({ query: "OpenClaw plugin SDK" });
// 针对德语的搜索
await web_search({ query: "TV online schauen", country: "DE", language: "de" });
// 近期结果（过去一周）
await web_search({ query: "AI developments", freshness: "week" });
// 日期范围
await web_search({
query: "climate research",
date_after: "2024-01-01",
date_before: "2024-06-30",
});
// 域名筛选（仅限 Perplexity）
await web_search({
query: "product reviews",
domain_filter: ["-reddit.com", "-pinterest.com"],
});
```
## 工具配置文件
如果使用工具配置文件或允许列表，请添加 `web_search`、`x_search` 或 `group:web`：
```json5
{
tools: {
allow: ["web_search", "x_search"],
// 或：allow: ["group:web"] （包括 web_search、x_search 和 web_fetch）
},
}
```
## 相关内容
- [Web Fetch](https://funcoding.ai/agents/openclaw/tools/web-fetch/) —— 获取 URL 并提取可读内容
- [Web Browser](https://funcoding.ai/agents/openclaw/tools/browser/) —— 对大量使用 JS 的网站进行完整浏览器自动化
- [Grok Search](https://funcoding.ai/agents/openclaw/tools/grok-search/) —— 使用 Grok 作为 `web_search` 提供商
- [Ollama Web 搜索](https://funcoding.ai/agents/openclaw/tools/ollama-search/) —— 通过你的 Ollama 主机进行无需密钥的 Web 搜索