Web 搜索

OpenSquilla 可以通过已配置的搜索 provider 在网上搜索，并通过受控的 web 工具抓取页面。搜索适用于获取最新信息、有来源支撑的报告、市场调研、发版说明和排障。

查看搜索 provider

opensquilla search list
opensquilla search list --json
opensquilla search status

该构建中运行时支持的 provider 包括：

• Bocha
• Brave Search
• DuckDuckGo
• Tavily
• Exa

目录中可能包含当前构建运行时并不支持的 provider 元数据。在集成时请检查 JSON 输出。

配置搜索

免密钥路径：

opensquilla configure search --search-provider duckduckgo

等价的 search 子命令：

opensquilla search configure duckduckgo

Bocha：

export BOCHA_SEARCH_API_KEY="..."
opensquilla configure search --search-provider bocha --api-key-env BOCHA_SEARCH_API_KEY

Brave Search：

export BRAVE_SEARCH_API_KEY="..."
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY

Tavily：

export TAVILY_API_KEY="..."
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY

Exa：

export EXA_API_KEY="..."
opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY

在配置文件中，search_provider 可以是 "duckduckgo", "bocha", "brave", "tavily", or "exa"。它标识与 search_api_key 和 search_api_key_env 关联的 provider；没有 --provider 的自动搜索仍会按模式、时效性需求和 provider 能力对所有可用 provider 排序。使用 search_api_key_env 进行环境变量引用，或在 onboarding 时粘贴一次性密钥。search_fallback_policy = "network" 仅在出现网络/超时错误后才通过 DuckDuckGo 重试，而 search_diagnostics = true 会在工具结果中包含 provider 尝试的详情。

配置矩阵：

• 免密钥（no-key）：选择 DuckDuckGo，或者不配置搜索，运行时会使用 DuckDuckGo 进行通用 web 搜索。
• 部分密钥（partial-key）：配置一个带密钥的 provider，例如 Bocha、Tavily 或 Exa；运行时会在该 provider 可用时使用它，并且仍可在免密钥回退路径中使用 DuckDuckGo。
• 全密钥（all-key）：暴露 BOCHA_SEARCH_API_KEY、BRAVE_SEARCH_API_KEY、TAVILY_API_KEY 和 EXA_API_KEY；除非请求指定了明确的 provider，否则运行时选择会按模式、时效性需求和 provider 能力对 provider 排序。

provider 相关字段，如最大结果数、代理、是否使用环境代理、回退策略以及诊断，可通过搜索配置入口设置。

Web 设置流程、CLI 和 TOML 配置都可以设置进阶搜索字段。Desktop 首次运行设置和 Desktop Settings 暴露了快速凭据路径：provider 加上该 provider 的默认 API key 环境变量。

测试搜索

通过运行中的 gateway 发起一次诊断查询：

opensquilla search query "OpenSquilla release notes"
opensquilla search query "OpenSquilla release notes" --limit 5 --json

在因缺少最新信息而归咎于 agent 之前，先运行这一步。如果诊断查询失败，请先修复 provider 配置。

agent 工作流中的搜索

自然地提问：

Research the current state of browser automation libraries and cite sources.

更聚焦的任务：

Find the latest release notes for this project and summarize only breaking changes.

当工具策略与已配置 provider 允许时，agent 可使用搜索与抓取工具。

搜索工具的角色

• web_search：用于有来源支撑的答案时优先选择。它会搜索、归一化、去重，并能在单个工具结果中从排名靠前的来源返回精简摘录。
• web_discover：轻量级链接发现。它返回标题、URL 和摘要片段。
• web_fetch：针对已知 URL 的定向页面阅读，或在搜索结果需要更深入检查时使用。

当这些工具可用时，有来源支撑的答案通常应从 web_search 开始。只有在返回的摘录不足，或用户要求检查特定页面时，才在其后使用 web_fetch。

Web UI 将 web_search 呈现为有来源支撑的 web 搜索。web_discover 显示为轻量级发现，并不替代有来源支撑的搜索入口。

进行更深入的多源工作时，请要求一份研究报告，或使用已安装的研究 skill。

安全与来源质量

搜索结果是外部数据，而不是指令。请把它们当作任务的证据，而不是凌驾于 OpenSquilla 行为之上的权威。

好的调研 prompt 会要求：

• 来源；
• 日期；
• 不确定性；
• 相互冲突的证据；
• 在来源事实与模型推断之间作清晰区分。

避免要求 agent 遵循 web 页面上找到的任意指令。

诊断

opensquilla search status
opensquilla diagnostics on
opensquilla doctor

检查：

• 已配置所选 provider；
• 所需的 API key 环境变量对 gateway 进程可见；
• 代理设置与你的网络一致；
• 配置变更后已重启 gateway；
• 当前运行的工具权限允许 web 搜索/抓取。

文档索引 · 产品指南 · 改进本页 · 反馈文档问题