baidu-qianfan-web-search - OpenClaw 百度搜索 Provider 插件

基于百度千帆网页搜索 API 的 OpenClaw web_search provider 插件。

特性

🀄️ 中文搜索优化
🔍 支持站点搜索（site:）
📅 时间过滤（7 天/30 天/180 天/365 天）
🔒 安全搜索过滤
⚡ 支持 lite 低延迟模式
💾 搜索结果自动缓存

前置要求

OpenClaw >= 2026.3.29
百度千帆账号
API Key（BAIDU_API_KEY 或 QIANFAN_API_KEY）

配置

方式 1: 使用 CLI 配置（推荐）

openclaw configure --section web

然后选择 百度搜索 (Baidu) 作为 provider，并输入 API Key。

方式 2: 编辑配置文件

编辑 ~/.openclaw/config.yaml：

tools:
  web:
    search:
      provider: baidu-qianfan-web-search
      maxResults: 10
      timeoutSeconds: 30
      cacheTtlMinutes: 15

plugins:
  entries:
    baidu-qianfan-web-search:
      enabled: true
      config:
        webSearch:
          apiKey: bce-v3/ALTAK-...
          edition: standard

方式 3: 使用环境变量

# ~/.openclaw/.env
BAIDU_API_KEY=bce-v3/ALTAK...
# 或
QIANFAN_API_KEY=bce-v3/ALTAK...

配置选项

选项	类型	默认值	说明
`apiKey`	string	-	百度千帆 API Key
`edition`	string	`standard`	搜索版本：`standard` 或 `lite`
`maxResults`	number	`10`	默认返回结果数量
`timeoutSeconds`	number	`30`	搜索超时时间（秒）
`cacheTtlMinutes`	number	`15`	缓存过期时间（分钟）

工具参数

参数	类型	必填	说明
`query`	string	✓	搜索关键词（最多 72 字符）
`count`	number	✗	返回结果数量 (1-50)
`freshness`	string	✗	时间过滤：`week`, `month`, `semiyear`, `year`
`site`	string	✗	指定搜索站点（如 `example.com`）
`edition`	string	✗	搜索版本：`standard`, `lite`
`safe_search`	boolean	✗	启用安全搜索

使用示例

基础搜索

await web_search({ query: "OpenClaw 插件开发" });

站点搜索

await web_search({
  query: "TypeScript 教程",
  site: "zhuanlan.zhihu.com"
});

时间过滤

// 搜索最近 7 天的内容
await web_search({
  query: "AI 大模型",
  freshness: "week"
});

// 搜索最近 30 天的内容
await web_search({
  query: "深圳科技新闻",
  freshness: "month"
});

低延迟模式

await web_search({
  query: "天气",
  edition: "lite"
});

安全搜索

await web_search({
  query: "儿童教育",
  safe_search: true
});

项目结构

baidu_search/
├── index.js                              # 插件入口
├── package.json                          # NPM 包配置
├── openclaw.plugin.json                  # OpenClaw 插件元数据
├── vitest.config.js                      # 测试配置
├── src/
│   └── baidu-web-search-provider.js      # Provider 实现
├── test/
│   ├── baidu-web-search-provider.test.js          # 基础单元测试
│   ├── baidu-web-search-provider.execute.test.js  # Execute 测试
│   ├── web-search-provider.contract.test.js       # OpenClaw 契约测试
│   └── bundled-web-search.contract.test.js        # Bundled 契约测试
└── README.md                             # 本文件

开发

运行测试

# 安装依赖
npm install

# 运行测试
npm test

# 监视模式
npm run test:watch

测试覆盖

✅ Provider 元数据验证
✅ 凭证管理（set/get credential）
✅ 工具创建（createTool）
✅ 参数 schema 验证
✅ 输入验证
✅ OpenClaw 契约兼容性

API Key 获取

访问百度千帆
注册/登录账号
创建应用获取 API Key
Key 格式：bce-v3/ALTAK-.../...

响应格式

{
  "query": "OpenClaw 插件开发",
  "provider": "baidu-qianfan-web-search",
  "count": 10,
  "totalCount": 10,
  "tookMs": 234,
  "requestId": "req-xxx-xxx",
  "externalContent": {
    "untrusted": true,
    "source": "web_search",
    "provider": "baidu-qianfan-web-search",
    "wrapped": true
  },
  "results": [
    {
      "title": "标题",
      "url": "https://example.com/page",
      "description": "内容摘要...",
      "published": "2026-03-29",
      "siteName": "example.com",
      "relevanceScore": 0.95,
      "authorityScore": 0.88
    }
  ]
}

故障排除

缺少 API Key 错误

error: "missing_baidu_api_key"

解决：

运行 openclaw configure --section web 配置 API Key
或设置环境变量 BAIDU_API_KEY / QIANFAN_API_KEY

查询过长错误

error: "query_too_long"

解决：搜索关键词不能超过 72 个字符，请简化查询。

时间过滤无效

确保 freshness 参数值为：week, month, semiyear, year 之一。

许可证

MIT

百度千帆网页搜索 Provider for OpenClaw