Ayuriel/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs update web search config guidance

Browse Source
This commit is contained in:
Tak Hoffman 2026-03-17 23:59:17 -05:00
parent 67ce726bba
commit 0354d49a82
No known key found for this signature in database
20 changed files with 325 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/brave-search.md
View File

@ -20,11 +20,21 @@ OpenClaw supports Brave Search API as a `web_search` provider.
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
provider: "brave",
apiKey: "BRAVE_API_KEY_HERE",
maxResults: 5,
timeoutSeconds: 30,
},
@ -33,6 +43,9 @@ OpenClaw supports Brave Search API as a `web_search` provider.
}
```
Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`.
Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path.
## Tool parameters
| Parameter | Description |

2
docs/cli/config.md
View File

@ -21,7 +21,7 @@ openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config unset tools.web.search.apiKey
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

2
docs/gateway/configuration.md
View File

@ -46,7 +46,7 @@ See the [full reference](/gateway/configuration-reference) for every available f
```bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```
</Tab>
<Tab title="Control UI">

15
docs/help/faq.md
View File

@ -1505,12 +1505,22 @@ Environment alternatives:
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "brave",
apiKey: "BRAVE_API_KEY_HERE",
maxResults: 5,
},
fetch: {
@ -1521,6 +1531,9 @@ Environment alternatives:
}
```
Provider-specific web-search config now lives under `plugins.entries.<plugin>.config.webSearch.*`.
Legacy `tools.web.search.*` provider paths still load temporarily for compatibility, but they should not be used for new configs.
Notes:
- If you use allowlists, add `web_search`/`web_fetch` or `group:web`.

2
docs/ja-JP/start/wizard.md
View File

@ -67,7 +67,7 @@ openclaw agents add <name>
</Note>
<Tip>
推奨：エージェントが `web_search` を使用できるように、Brave Search APIキーを設定してください（`web_fetch` はキーなしで動作します）。最も簡単な方法：`openclaw configure --section web` を実行すると `tools.web.search.apiKey` が保存されます。ドキュメント：[Webツール](/tools/web)。
推奨：エージェントが `web_search` を使用できるように、Brave Search APIキーを設定してください（`web_fetch` はキーなしで動作します）。最も簡単な方法：`openclaw configure --section web` を実行すると `plugins.entries.brave.config.webSearch.apiKey` に保存されます。旧 `tools.web.search.apiKey` パスは互換用に引き続き読み込まれますが、新しい設定では使用しないでください。ドキュメント：[Webツール](/tools/web)。
</Tip>
## 関連ドキュメント

46
docs/perplexity.md
View File

@ -12,7 +12,7 @@ OpenClaw supports Perplexity Search API as a `web_search` provider.
It returns structured results with `title`, `url`, and `snippet` fields.
For compatibility, OpenClaw also supports legacy Perplexity Sonar/OpenRouter setups.
If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `tools.web.search.perplexity.apiKey`, or set `tools.web.search.perplexity.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`, or set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
## Getting a Perplexity API key
@ -22,12 +22,12 @@ If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `tools.web.search.perplex
## OpenRouter compatibility
If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `tools.web.search.perplexity.apiKey`.
If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`.
Optional legacy controls:
Optional compatibility controls:
- `tools.web.search.perplexity.baseUrl`
- `tools.web.search.perplexity.model`
- `plugins.entries.perplexity.config.webSearch.baseUrl`
- `plugins.entries.perplexity.config.webSearch.model`
## Config examples
@ -35,13 +35,21 @@ Optional legacy controls:
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "pplx-...",
},
},
},
},
},
tools: {
web: {
search: {
provider: "perplexity",
perplexity: {
apiKey: "pplx-...",
},
},
},
},
@ -52,15 +60,23 @@ Optional legacy controls:
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "<openrouter-api-key>",
baseUrl: "https://openrouter.ai/api/v1",
model: "perplexity/sonar-pro",
},
},
},
},
},
tools: {
web: {
search: {
provider: "perplexity",
perplexity: {
apiKey: "<openrouter-api-key>",
baseUrl: "https://openrouter.ai/api/v1",
model: "perplexity/sonar-pro",
},
},
},
},
@ -70,7 +86,7 @@ Optional legacy controls:
## Where to set the key
**Via config:** run `openclaw configure --section web`. It stores the key in
`~/.openclaw/openclaw.json` under `tools.web.search.perplexity.apiKey`.
`~/.openclaw/openclaw.json` under `plugins.entries.perplexity.config.webSearch.apiKey`.
That field also accepts SecretRef objects.
**Via environment:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
@ -151,7 +167,7 @@ await web_search({
## Notes
- Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
- OpenRouter or explicit `baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
- OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
See [Web tools](/tools/web) for the full web_search configuration.

12
docs/reference/api-usage-costs.md
View File

@ -79,11 +79,13 @@ See [Memory](/concepts/memory).
`web_search` uses API keys and may incur usage charges depending on your provider:
- **Brave Search API**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
- **Gemini (Google Search)**: `GEMINI_API_KEY` or `tools.web.search.gemini.apiKey`
- **Grok (xAI)**: `XAI_API_KEY` or `tools.web.search.grok.apiKey`
- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `tools.web.search.kimi.apiKey`
- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey`
- **Brave Search API**: `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
- **Gemini (Google Search)**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
- **Grok (xAI)**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
Legacy `tools.web.search.*` provider paths still load through the temporary compatibility shim, but they are no longer the recommended config surface.
**Brave Search free credit:** Each Brave plan includes \$5/month in renewing
free credit. The Search plan costs \$5 per 1,000 requests, so the credit covers

12
docs/reference/secretref-credential-surface.md
View File

@ -32,11 +32,12 @@ Scope intent:
- `messages.tts.elevenlabs.apiKey`
- `messages.tts.openai.apiKey`
- `tools.web.fetch.firecrawl.apiKey`
- `tools.web.search.apiKey`
- `tools.web.search.gemini.apiKey`
- `tools.web.search.grok.apiKey`
- `tools.web.search.kimi.apiKey`
- `tools.web.search.perplexity.apiKey`
- `plugins.entries.brave.config.webSearch.apiKey`
- `plugins.entries.google.config.webSearch.apiKey`
- `plugins.entries.xai.config.webSearch.apiKey`
- `plugins.entries.moonshot.config.webSearch.apiKey`
- `plugins.entries.perplexity.config.webSearch.apiKey`
- `plugins.entries.firecrawl.config.webSearch.apiKey`
- `gateway.auth.password`
- `gateway.auth.token`
- `gateway.remote.token`
@ -108,6 +109,7 @@ Notes:
- In explicit provider mode (`tools.web.search.provider` set), only the selected provider key is active.
- In auto mode (`tools.web.search.provider` unset), only the first provider key that resolves by precedence is active.
- In auto mode, non-selected provider refs are treated as inactive until selected.
- Legacy `tools.web.search.*` provider paths still resolve during the compatibility window, but the canonical SecretRef surface is `plugins.entries.<plugin>.config.webSearch.*`.
## Unsupported credentials

27
docs/reference/secretref-user-supplied-credentials-matrix.json
View File

@ -476,37 +476,44 @@
"optIn": true
},
{
"id": "tools.web.search.apiKey",
"id": "plugins.entries.brave.config.webSearch.apiKey",
"configFile": "openclaw.json",
"path": "tools.web.search.apiKey",
"path": "plugins.entries.brave.config.webSearch.apiKey",
"secretShape": "secret_input",
"optIn": true
},
{
"id": "tools.web.search.gemini.apiKey",
"id": "plugins.entries.google.config.webSearch.apiKey",
"configFile": "openclaw.json",
"path": "tools.web.search.gemini.apiKey",
"path": "plugins.entries.google.config.webSearch.apiKey",
"secretShape": "secret_input",
"optIn": true
},
{
"id": "tools.web.search.grok.apiKey",
"id": "plugins.entries.xai.config.webSearch.apiKey",
"configFile": "openclaw.json",
"path": "tools.web.search.grok.apiKey",
"path": "plugins.entries.xai.config.webSearch.apiKey",
"secretShape": "secret_input",
"optIn": true
},
{
"id": "tools.web.search.kimi.apiKey",
"id": "plugins.entries.moonshot.config.webSearch.apiKey",
"configFile": "openclaw.json",
"path": "tools.web.search.kimi.apiKey",
"path": "plugins.entries.moonshot.config.webSearch.apiKey",
"secretShape": "secret_input",
"optIn": true
},
{
"id": "tools.web.search.perplexity.apiKey",
"id": "plugins.entries.perplexity.config.webSearch.apiKey",
"configFile": "openclaw.json",
"path": "tools.web.search.perplexity.apiKey",
"path": "plugins.entries.perplexity.config.webSearch.apiKey",
"secretShape": "secret_input",
"optIn": true
},
{
"id": "plugins.entries.firecrawl.config.webSearch.apiKey",
"configFile": "openclaw.json",
"path": "plugins.entries.firecrawl.config.webSearch.apiKey",
"secretShape": "secret_input",
"optIn": true
}

22
docs/tools/firecrawl.md
View File

@ -28,20 +28,22 @@ which helps with JS-heavy sites or pages that block plain HTTP fetches.
```json5
{
plugins: {
entries: {
firecrawl: {
enabled: true,
},
},
},
tools: {
web: {
search: {
provider: "firecrawl",
firecrawl: {
apiKey: "FIRECRAWL_API_KEY_HERE",
baseUrl: "https://api.firecrawl.dev",
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webSearch: {
apiKey: "FIRECRAWL_API_KEY_HERE",
baseUrl: "https://api.firecrawl.dev",
},
},
},
},

140
docs/tools/web.md
View File

@ -43,12 +43,12 @@ See [Brave Search setup](/brave-search) and [Perplexity Search setup](/perplexit
The table above is alphabetical. If no `provider` is explicitly set, runtime auto-detection checks providers in this order:
1. **Brave** — `BRAVE_API_KEY` env var or `tools.web.search.apiKey` config
2. **Gemini** — `GEMINI_API_KEY` env var or `tools.web.search.gemini.apiKey` config
3. **Grok** — `XAI_API_KEY` env var or `tools.web.search.grok.apiKey` config
4. **Kimi** — `KIMI_API_KEY` / `MOONSHOT_API_KEY` env var or `tools.web.search.kimi.apiKey` config
5. **Perplexity** — `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey` config
6. **Firecrawl** — `FIRECRAWL_API_KEY` env var or `tools.web.search.firecrawl.apiKey` config
1. **Brave** — `BRAVE_API_KEY` env var or `plugins.entries.brave.config.webSearch.apiKey`
2. **Gemini** — `GEMINI_API_KEY` env var or `plugins.entries.google.config.webSearch.apiKey`
3. **Grok** — `XAI_API_KEY` env var or `plugins.entries.xai.config.webSearch.apiKey`
4. **Kimi** — `KIMI_API_KEY` / `MOONSHOT_API_KEY` env var or `plugins.entries.moonshot.config.webSearch.apiKey`
5. **Perplexity** — `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
6. **Firecrawl** — `FIRECRAWL_API_KEY` env var or `plugins.entries.firecrawl.config.webSearch.apiKey`
If no keys are found, it falls back to Brave (you'll get a missing-key error prompting you to configure one).
@ -80,7 +80,10 @@ pricing.
2. Generate an API key in the dashboard
3. Run `openclaw configure --section web` to store the key in config, or set `PERPLEXITY_API_KEY` in your environment.
For legacy Sonar/OpenRouter compatibility, set `OPENROUTER_API_KEY` instead, or configure `tools.web.search.perplexity.apiKey` with an `sk-or-...` key. Setting `tools.web.search.perplexity.baseUrl` or `model` also opts Perplexity back into the chat-completions compatibility path.
For legacy Sonar/OpenRouter compatibility, set `OPENROUTER_API_KEY` instead, or configure `plugins.entries.perplexity.config.webSearch.apiKey` with an `sk-or-...` key. Setting `plugins.entries.perplexity.config.webSearch.baseUrl` or `model` also opts Perplexity back into the chat-completions compatibility path.
Provider-specific web search config now lives under `plugins.entries.<plugin>.config.webSearch.*`.
Legacy `tools.web.search.*` provider paths still load through a compatibility shim for one release, but they should not be used in new configs.
See [Perplexity Search API Docs](https://docs.perplexity.ai/guides/search-quickstart) for more details.
@ -88,12 +91,12 @@ See [Perplexity Search API Docs](https://docs.perplexity.ai/guides/search-quicks
**Via config:** run `openclaw configure --section web`. It stores the key under the provider-specific config path:
- Brave: `tools.web.search.apiKey`
- Firecrawl: `tools.web.search.firecrawl.apiKey`
- Gemini: `tools.web.search.gemini.apiKey`
- Grok: `tools.web.search.grok.apiKey`
- Kimi: `tools.web.search.kimi.apiKey`
- Perplexity: `tools.web.search.perplexity.apiKey`
- Brave: `plugins.entries.brave.config.webSearch.apiKey`
- Firecrawl: `plugins.entries.firecrawl.config.webSearch.apiKey`
- Gemini: `plugins.entries.google.config.webSearch.apiKey`
- Grok: `plugins.entries.xai.config.webSearch.apiKey`
- Kimi: `plugins.entries.moonshot.config.webSearch.apiKey`
- Perplexity: `plugins.entries.perplexity.config.webSearch.apiKey`
All of these fields also support SecretRef objects.
@ -114,12 +117,22 @@ For a gateway install, put these in `~/.openclaw/.env` (or your service environm
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "brave",
apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
},
},
},
@ -142,9 +155,18 @@ For a gateway install, put these in `~/.openclaw/.env` (or your service environm
search: {
enabled: true,
provider: "firecrawl",
firecrawl: {
apiKey: "fc-...", // optional if FIRECRAWL_API_KEY is set
baseUrl: "https://api.firecrawl.dev",
},
},
},
plugins: {
entries: {
firecrawl: {
enabled: true,
config: {
webSearch: {
apiKey: "fc-...", // optional if FIRECRAWL_API_KEY is set
baseUrl: "https://api.firecrawl.dev",
},
},
},
},
@ -158,15 +180,23 @@ When you choose Firecrawl in onboarding or `openclaw configure --section web`, O
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
mode: "llm-context",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "brave",
apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
brave: {
mode: "llm-context",
},
},
},
},
@ -181,14 +211,22 @@ In this mode, `country` and `language` / `search_lang` still work, but `ui_lang`
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "perplexity",
perplexity: {
apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
},
},
},
},
@ -199,16 +237,24 @@ In this mode, `country` and `language` / `search_lang` still work, but `ui_lang`
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "<openrouter-api-key>", // optional if OPENROUTER_API_KEY is set
baseUrl: "https://openrouter.ai/api/v1",
model: "perplexity/sonar-pro",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "perplexity",
perplexity: {
apiKey: "<openrouter-api-key>", // optional if OPENROUTER_API_KEY is set
baseUrl: "https://openrouter.ai/api/v1",
model: "perplexity/sonar-pro",
},
},
},
},
@ -224,22 +270,30 @@ which returns AI-synthesized answers backed by live Google Search results with c
1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
2. Create an API key
3. Set `GEMINI_API_KEY` in the Gateway environment, or configure `tools.web.search.gemini.apiKey`
3. Set `GEMINI_API_KEY` in the Gateway environment, or configure `plugins.entries.google.config.webSearch.apiKey`
### Setting up Gemini search
```json5
{
plugins: {
entries: {
google: {
config: {
webSearch: {
// API key (optional if GEMINI_API_KEY is set)
apiKey: "AIza...",
// Model (defaults to "gemini-2.5-flash")
model: "gemini-2.5-flash",
},
},
},
},
},
tools: {
web: {
search: {
provider: "gemini",
gemini: {
// API key (optional if GEMINI_API_KEY is set)
apiKey: "AIza...",
// Model (defaults to "gemini-2.5-flash")
model: "gemini-2.5-flash",
},
},
},
},
@ -266,12 +320,12 @@ Search the web using your configured provider.
- `tools.web.search.enabled` must not be `false` (default: enabled)
- API key for your chosen provider:
- **Brave**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
- **Firecrawl**: `FIRECRAWL_API_KEY` or `tools.web.search.firecrawl.apiKey`
- **Gemini**: `GEMINI_API_KEY` or `tools.web.search.gemini.apiKey`
- **Grok**: `XAI_API_KEY` or `tools.web.search.grok.apiKey`
- **Kimi**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `tools.web.search.kimi.apiKey`
- **Perplexity**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey`
- **Brave**: `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
- **Firecrawl**: `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey`
- **Gemini**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
- **Grok**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
- **Kimi**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
- **Perplexity**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
- All provider key fields above support SecretRef objects.
### Config
@ -297,7 +351,7 @@ Search the web using your configured provider.
Parameters depend on the selected provider.
Perplexity's OpenRouter / Sonar compatibility path supports only `query` and `freshness`.
If you set `tools.web.search.perplexity.baseUrl` / `model`, use `OPENROUTER_API_KEY`, or configure an `sk-or-...` key, Search API-only filters return explicit errors.
If you set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, use `OPENROUTER_API_KEY`, or configure an `sk-or-...` key under `plugins.entries.perplexity.config.webSearch.apiKey`, Search API-only filters return explicit errors.
| Parameter | Description |
| --------------------- | ----------------------------------------------------- |

14
docs/zh-CN/brave-search.md
View File

@ -27,11 +27,21 @@ OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
provider: "brave",
apiKey: "BRAVE_API_KEY_HERE",
maxResults: 5,
timeoutSeconds: 30,
},
@ -40,6 +50,8 @@ OpenClaw 使用 Brave Search 作为 `web_search` 的默认提供商。
}
```
Brave 的提供商专属搜索配置现在位于 `plugins.entries.brave.config.webSearch.*`。旧的 `tools.web.search.apiKey` 仅作为兼容层暂时保留。
## 注意事项
- Data for AI 套餐与 `web_search` **不**兼容。

2
docs/zh-CN/cli/config.md
View File

@ -24,7 +24,7 @@ openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config unset tools.web.search.apiKey
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```
## 路径

2
docs/zh-CN/gateway/configuration.md
View File

@ -53,7 +53,7 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5
```bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```
</Tab>
<Tab title="Control UI">

16
docs/zh-CN/help/faq.md
View File

@ -1266,15 +1266,26 @@ Gateway 网关监视配置文件并支持热重载：
### 如何启用网络搜索（和网页抓取）
`web_fetch` 无需 API 密钥即可工作。`web_search` 需要 Brave Search API 密钥。**推荐：** 运行 `openclaw configure --section web` 将其存储在 `tools.web.search.apiKey` 中。环境变量替代方案：为 Gateway 网关进程设置 `BRAVE_API_KEY`。
`web_fetch` 无需 API 密钥即可工作。`web_search` 需要所选提供商的 API 密钥。**推荐：** 运行 `openclaw configure --section web`。新的提供商专属配置会存储在 `plugins.entries.<plugin>.config.webSearch.*` 下。环境变量替代方案：为 Gateway 网关进程设置相应的提供商环境变量。
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
apiKey: "BRAVE_API_KEY_HERE",
provider: "brave",
maxResults: 5,
},
fetch: {
@ -1290,6 +1301,7 @@ Gateway 网关监视配置文件并支持热重载：
- 如果你使用允许列表，添加 `web_search`/`web_fetch` 或 `group:web`。
- `web_fetch` 默认启用（除非明确禁用）。
- 守护进程从 `~/.openclaw/.env`（或服务环境）读取环境变量。
- 旧的 `tools.web.search.*` 提供商路径仍通过兼容层继续生效，但不应再用于新配置。
文档：[Web 工具](/tools/web)。

38
docs/zh-CN/perplexity.md
View File

@ -34,15 +34,23 @@ OpenClaw 可以使用 Perplexity Sonar 作为 `web_search` 工具。你可以通
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "pplx-...",
baseUrl: "https://api.perplexity.ai",
model: "perplexity/sonar-pro",
},
},
},
},
},
tools: {
web: {
search: {
provider: "perplexity",
perplexity: {
apiKey: "pplx-...",
baseUrl: "https://api.perplexity.ai",
model: "perplexity/sonar-pro",
},
},
},
},
@ -53,21 +61,31 @@ OpenClaw 可以使用 Perplexity Sonar 作为 `web_search` 工具。你可以通
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "pplx-...",
baseUrl: "https://api.perplexity.ai",
},
},
},
},
},
tools: {
web: {
search: {
provider: "perplexity",
perplexity: {
apiKey: "pplx-...",
baseUrl: "https://api.perplexity.ai",
},
},
},
},
}
```
如果同时设置了 `PERPLEXITY_API_KEY` 和 `OPENROUTER_API_KEY`，请设置 `tools.web.search.perplexity.baseUrl`（或 `tools.web.search.perplexity.apiKey`）以消除歧义。
如果同时设置了 `PERPLEXITY_API_KEY` 和 `OPENROUTER_API_KEY`，请设置 `plugins.entries.perplexity.config.webSearch.baseUrl`（或 `plugins.entries.perplexity.config.webSearch.apiKey`）以消除歧义。
提供商专属配置现在统一放在 `plugins.entries.<plugin>.config.webSearch.*`。旧的 `tools.web.search.*` 路径仅通过兼容层继续生效，不再推荐用于新配置。
如果未设置 base URL，OpenClaw 会根据 API 密钥来源选择默认值：

9
docs/zh-CN/reference/api-usage-costs.md
View File

@ -79,8 +79,13 @@ OpenClaw 可以从以下来源获取凭据：
`web_search` 使用 API 密钥，可能产生使用费用：
- **Brave Search API**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
- **Perplexity**（通过 OpenRouter）：`PERPLEXITY_API_KEY` 或 `OPENROUTER_API_KEY`
- **Brave Search API**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`
- **Gemini**：`GEMINI_API_KEY` 或 `plugins.entries.google.config.webSearch.apiKey`
- **Grok**：`XAI_API_KEY` 或 `plugins.entries.xai.config.webSearch.apiKey`
- **Kimi**：`KIMI_API_KEY`、`MOONSHOT_API_KEY` 或 `plugins.entries.moonshot.config.webSearch.apiKey`
- **Perplexity**：`PERPLEXITY_API_KEY`、`OPENROUTER_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey`
旧的 `tools.web.search.*` 提供商路径仍会通过兼容层加载，但不再是推荐配置方式。
**Brave 免费套餐（额度充裕）：**

82
docs/zh-CN/tools/web.md
View File

@ -18,7 +18,7 @@ x-i18n:
OpenClaw 提供两个轻量级 Web 工具：
- `web_search` — 通过 Brave Search API（默认）或 Perplexity Sonar（直连或通过 OpenRouter）搜索网络。
- `web_search` — 通过 Brave Search API、Firecrawl Search、Gemini with Google Search grounding、Grok、Kimi 或 Perplexity Search API 搜索网络。
- `web_fetch` — HTTP 获取 + 可读性提取（HTML → markdown/文本）。
这些**不是**浏览器自动化。对于 JS 密集型网站或需要登录的情况，请使用[浏览器工具](/tools/browser)。
@ -26,18 +26,21 @@ OpenClaw 提供两个轻量级 Web 工具：
## 工作原理
- `web_search` 调用你配置的提供商并返回结果。
- **Brave**（默认）：返回结构化结果（标题、URL、摘要）。
- **Perplexity**：返回带有实时网络搜索引用的 AI 综合答案。
- 结果按查询缓存 15 分钟（可配置）。
- `web_fetch` 执行普通 HTTP GET 并提取可读内容（HTML → markdown/文本）。它**不**执行 JavaScript。
- `web_fetch` 默认启用（除非显式禁用）。
- 启用捆绑的 Firecrawl 插件后，还会提供 `firecrawl_search` 和 `firecrawl_scrape`。
## 选择搜索提供商
| 提供商 | 优点 | 缺点 | API 密钥 |
| ----------------- | ------------------------ | ---------------------------------- | -------------------------------------------- |
| **Brave**（默认） | 快速、结构化结果、免费层 | 传统搜索结果 | `BRAVE_API_KEY` |
| **Perplexity** | AI 综合答案、引用、实时 | 需要 Perplexity 或 OpenRouter 访问 | `OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY` |
| 提供商 | 结果形式 | 说明 | API 密钥 |
| --------------------- | ------------------ | ----------------------------------------------- | ------------------------------------------- |
| **Brave Search API** | 结构化结果 + 摘要 | 支持 Brave `llm-context` 模式 | `BRAVE_API_KEY` |
| **Firecrawl Search** | 结构化结果 + 摘要 | Firecrawl 专用搜索控制请使用 `firecrawl_search` | `FIRECRAWL_API_KEY` |
| **Gemini** | AI 综合答案 + 引用 | 使用 Google Search grounding | `GEMINI_API_KEY` |
| **Grok** | AI 综合答案 + 引用 | 使用 xAI 实时网络搜索 | `XAI_API_KEY` |
| **Kimi** | AI 综合答案 + 引用 | 使用 Moonshot web search | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| **Perplexity Search** | 结构化结果 + 摘要 | 兼容 OpenRouter Sonar 路径 | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
参见 [Brave Search 设置](/brave-search) 和 [Perplexity Sonar](/perplexity) 了解提供商特定详情。
@ -48,26 +51,34 @@ OpenClaw 提供两个轻量级 Web 工具：
tools: {
web: {
search: {
provider: "brave", // 或 "perplexity"
provider: "brave", // 或 "firecrawl" | "gemini" | "grok" | "kimi" | "perplexity"
},
},
},
}
```
示例：切换到 Perplexity Sonar（直连 API）：
示例：切换到 Perplexity Search / Sonar 兼容路径：
```json5
{
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
apiKey: "pplx-...",
baseUrl: "https://api.perplexity.ai",
model: "perplexity/sonar-pro",
},
},
},
},
},
tools: {
web: {
search: {
provider: "perplexity",
perplexity: {
apiKey: "pplx-...",
baseUrl: "https://api.perplexity.ai",
model: "perplexity/sonar-pro",
},
},
},
},
@ -84,7 +95,7 @@ Brave 提供免费层和付费计划；查看 Brave API 门户了解当前限制
### 在哪里设置密钥（推荐）
**推荐：** 运行 `openclaw configure --section web`。它将密钥存储在 `~/.openclaw/openclaw.json` 的 `tools.web.search.apiKey` 下。
**推荐：** 运行 `openclaw configure --section web`。它会把密钥存储到 `~/.openclaw/openclaw.json` 的 `plugins.entries.brave.config.webSearch.apiKey`。
**环境变量替代方案：** 在 Gateway 网关进程环境中设置 `BRAVE_API_KEY`。对于 Gateway 网关安装，将其放在 `~/.openclaw/.env`（或你的服务环境）中。参见[环境变量](/help/faq#how-does-openclaw-load-environment-variables)。
@ -107,13 +118,21 @@ Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用
search: {
enabled: true,
provider: "perplexity",
perplexity: {
// API 密钥（如果设置了 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 则可选）
apiKey: "sk-or-v1-...",
// 基础 URL（如果省略则根据密钥感知默认值）
baseUrl: "https://openrouter.ai/api/v1",
// 模型（默认为 perplexity/sonar-pro）
model: "perplexity/sonar-pro",
},
},
},
plugins: {
entries: {
perplexity: {
config: {
webSearch: {
// API 密钥（如果设置了 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 则可选）
apiKey: "sk-or-v1-...",
// 基础 URL（如果省略则根据密钥感知默认值）
baseUrl: "https://openrouter.ai/api/v1",
// 模型（默认为 perplexity/sonar-pro）
model: "perplexity/sonar-pro",
},
},
},
},
@ -145,18 +164,28 @@ Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用
- `tools.web.search.enabled` 不能为 `false`（默认：启用）
- 所选提供商的 API 密钥：
- **Brave**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
- **Perplexity**：`OPENROUTER_API_KEY`、`PERPLEXITY_API_KEY` 或 `tools.web.search.perplexity.apiKey`
- **Brave**：`BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`
- **Perplexity**：`OPENROUTER_API_KEY`、`PERPLEXITY_API_KEY` 或 `plugins.entries.perplexity.config.webSearch.apiKey`
### 配置
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
apiKey: "BRAVE_API_KEY_HERE", // 如果设置了 BRAVE_API_KEY 则可选
maxResults: 5,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
@ -166,6 +195,9 @@ Perplexity Sonar 模型具有内置的网络搜索功能，并返回带有引用
}
```
提供商专属的 web_search 配置现在统一放在 `plugins.entries.<plugin>.config.webSearch.*`。
旧的 `tools.web.search.*` 提供商路径仅作为兼容层暂时保留，不应再用于新配置。
### 工具参数
- `query`（必需）

2
extensions/firecrawl/src/firecrawl-client.ts
View File

@ -234,7 +234,7 @@ export async function runFirecrawlSearch(
const apiKey = resolveFirecrawlApiKey(params.cfg);
if (!apiKey) {
throw new Error(
"web_search (firecrawl) needs a Firecrawl API key. Set FIRECRAWL_API_KEY in the Gateway environment, or configure tools.web.search.firecrawl.apiKey.",
"web_search (firecrawl) needs a Firecrawl API key. Set FIRECRAWL_API_KEY in the Gateway environment, or configure plugins.entries.firecrawl.config.webSearch.apiKey.",
);
}
const count =

2
extensions/xai/web-search.ts
View File

@ -238,7 +238,7 @@ export function createXaiWebSearchProvider() {
return {
error: "missing_xai_api_key",
message:
"web_search (grok) needs an xAI API key. Set XAI_API_KEY in the Gateway environment, or configure tools.web.search.grok.apiKey.",
"web_search (grok) needs an xAI API key. Set XAI_API_KEY in the Gateway environment, or configure plugins.entries.xai.config.webSearch.apiKey.",
docs: "https://docs.openclaw.ai/tools/web",
};
}