OpenClaw DuckDuckGo 搜索集成指南免 API Key 的 web_search 实验性提供方【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawDuckDuckGo 是 OpenClaw 中唯一一个完全免 API Key、免账号的web_search提供方本文档带你完成从插件安装、配置选择到工具调用的完整接入并深入源码讲解其 HTML 抓取原理、参数校验、结果解析与缓存机制。读完本文你将掌握如何为 OpenClaw 配置一个零成本、开箱即用的网页搜索回退方案以及它在生产环境中需要注意的边界与风险。一、定位与适用场景OpenClaw 将网页搜索能力抽象为web_search工具并支持多种提供方providers。DuckDuckGo 提供方在 ddg-search-provider.shared.ts 中以如下元数据注册idduckduckgolabelDuckDuckGo Search (experimental)requiresCredentialfalse无需任何凭据envVars[]不需要配置环境变量credentialPath无凭据路径autoDetectOrder100onboardingScopes[text-inference]这意味着它是 OpenClaw 生态里少见的零密钥搜索引擎特别适合以下场景需要快速给 Agent 补一个网页搜索能力但暂时不想申请任何 API Key作为多提供方配置中的免费兜底fallback选项本地开发、Demo、测试环境中降低搜索成本。但请注意它不是官方 API。插件通过抓取 DuckDuckGo 的非 JavaScript HTML 搜索页https://html.duckduckgo.com/html来获取结果属于实验性、非官方集成。页面结构一旦变化或遇到机器人挑战bot-challenge页面结果就可能异常因此官方将其明确标记为 experimental。二、安装与启用DuckDuckGo 永远不会被自动选中——OpenClaw 的自动检测auto-detection只考虑带有可用凭据的提供方而免密钥提供方没有任何凭据可供检测。因此必须显式安装并指定openclaw plugins install openclaw/duckduckgo-plugin openclaw gateway restart插件包信息见 extensions/duckduckgo/package.json包名为openclaw/duckduckgo-pluginminHostVersion为2026.7.2同时发布到 npm 与 ClawHubclawhub:openclaw/duckduckgo-plugin默认安装渠道为 npm。安装后通过交互式配置选择提供方openclaw configure --section web # 在提示中选择 duckduckgo 作为 provider插件入口 index.ts 只做一件事调用api.registerWebSearchProvider(createDuckDuckGoWebSearchProvider())把提供方注册进 OpenClaw 的 web 搜索体系之后便可通过web_search工具调用。三、配置文件详解3.1 选择提供方在 OpenClaw 配置中直接设置provider{ tools: { web: { search: { provider: duckduckgo, }, }, }, }这一步是必须的。从源码结构看由于requiresCredential: false且autoDetectOrder: 100自动检测逻辑会将其排除在有可用凭据的候选之外只有显式配置才会启用它。3.2 插件级默认参数可以在插件条目下配置 region 与 SafeSearch 的默认值{ plugins: { entries: { duckduckgo: { config: { webSearch: { region: us-en, // DuckDuckGo region code safeSearch: moderate, // strict, moderate, or off }, }, }, }, }, }这些配置的解析逻辑位于 config.tsresolveDdgRegion(config)读取plugins.entries.duckduckgo.config.webSearch.region并经过normalizeOptionalString处理——测试用例证实空白字符串会被归一化为undefined参见 ddg-search-provider.test.tsresolveDdgSafeSearch(config)读取safeSearch并小写归一化仅接受strict或off其余任何值包括未配置一律回退到默认值moderate源码常量DEFAULT_DDG_SAFE_SEARCH moderate。也就是说SafeSearch 的默认档位是moderate且解析过程对非法值做了严格的白名单兜底。四、工具参数web_search工具DuckDuckGo 提供方的完整参数定义在 ddg-search-provider.ts 的DuckDuckGoSearchSchema中参数类型必填默认值说明querystring是—搜索查询词countnumber否5返回结果数量范围 1–10regionstring否插件配置值DuckDuckGo 区域代码如us-en、uk-en、de-desafeSearchstrict \| moderate \| off否moderate安全搜索级别region与safeSearch属于**逐查询覆盖per-query override**参数调用时传入即覆盖插件级默认配置不传则回退到插件配置再回退到内置默认。值得注意的参数校验细节源码 测试双重印证count通过readPositiveIntegerParam(args, count, { max: 10, message: count must be an integer from 1 to 10. })校验小数如 4.5和越界值如 11会在发起任何网络请求之前直接抛出异常测试用例rejects fractional and out-of-range counts before searching对此有专门覆盖Schema 设置了additionalProperties: false未知字段会被拒绝执行入口首先调用context?.signal?.throwIfAborted()支持调用方取消cancellation——已取消的请求不会启动进行中的请求会中止且不缓存结果测试用例aborts an in-flight DuckDuckGo request without caching its result验证了这一点。五、底层实现原理从请求到结果DuckDuckGo 提供方的核心实现在 ddg-client.ts理解它有助于预判各种异常行为。5.1 请求构造请求端点固定为https://html.duckduckgo.com/htmlHTML 版搜索页查询词写入q参数region映射为kl参数DuckDuckGo 的区域键safeSearch映射为kp参数映射关系为strict → 1、moderate → -1、off → -2请求携带浏览器风格的User-AgentChrome 122 / Linux以减少被拦截概率默认超时DEFAULT_TIMEOUT_SECONDS 20秒可通过timeoutSeconds调整请求经withTrustedWebSearchEndpoint包装发出响应体有大小上限测试证实超过 16,777,216 字节会被拒绝且不会调用response.text()造成无界读取。5.2 结果解析解析器通过正则匹配 HTML 中的result__a结果链接与result__snippet摘要class提取每条结果的title、url、snippet并做三层处理HTML 实体解码针对lt;、amp;、#128512;等实体做单次解码测试特意验证了不会双重解码如amp;lt;应还原为lt;而不是以及非法数字实体保持原文标签剥离移除b高亮标签时不添加空白避免把Cafbé/b拆成Caf é保证单词完整性测试用例keeps inline result markup from splitting returned wordsURL 解码DuckDuckGo 返回的跳转链接通过uddg参数携带真实地址decodeDuckDuckGoUrl会提取该参数还原直链无uddg时保留原始 URL。5.3 机器人挑战检测isBotChallenge函数会先检查页面是否包含result__aclass说明是正常结果页否则再匹配g-recaptcha、are you a human、idchallenge-form、namechallenge等特征命中即抛出DuckDuckGo returned a bot-detection challenge.。测试用例同时验证了包含 Challenge 字样的普通结果不会被误判。5.4 结果包装与缓存返回载荷包含query、provider: duckduckgo、count、tookMs耗时、results数组以及externalContent: { untrusted: true, source: web_search, wrapped: true }标记——从源码结构看这是 OpenClaw 对第三方网页内容的不可信内容标记提示上层按非可信来源处理每条结果的title与snippet都会经过wrapWebContent包装siteName由 URL 解析得出结果写入内存缓存DDG_SEARCH_CACHE缓存键由provider query count region safeSearch归一化生成TTL 默认DEFAULT_CACHE_TTL_MINUTES可通过tools.web.search.cacheTtlMinutes覆盖命中缓存时返回cached: true标记避免重复抓取。六、注意事项与风险边界使用 DuckDuckGo 提供方前请务必了解以下约束文档与源码一致确认无需 API Key只要把provider设为duckduckgo即可使用实验性集成抓取的是非 JavaScript HTML 页面不是官方 API/SDK结果依赖页面结构页面随时可能变更机器人挑战风险高频或自动化使用可能触发 CAPTCHA 或被封禁实现中会以明确错误信息暴露这一情况仅显式选择自动检测不会选中它必须显式配置provider: duckduckgoSafeSearch 默认moderate未配置时生效超时与响应上限默认 20 秒超时、16 MB 响应上限超大页面会被截断拒绝缓存特性结果缓存在进程内相同查询组合短时间内重复调用直接命中缓存不产生新请求。对于生产环境建议评估 API 背书、返回结构化数据的提供方例如 Brave Search提供免费额度或 Exa Search神经搜索 内容提取。七、相关资源Web Search 总览 —— 全部提供方与自动检测机制Brave Search —— 结构化结果含免费额度Exa Search —— 神经搜索支持内容提取插件源码入口、提供方注册、配置解析、抓取客户端、测试套件【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考