Byted Web Search Plugin

基于火山引擎联网搜索的 OpenClaw 插件。

它在 OpenClaw 中注册两个能力：

• byted-web-search Web Search Provider
• byted_search_pricing 额度与定价查询工具

入口实现见 index.ts。

功能特性

• 支持将火山联网搜索作为 OpenClaw 的默认搜索引擎
• 支持 timeRange、authLevel、queryRewrite
• 支持通过 WEB_SEARCH_API_KEY 或插件配置注入密钥
• 内置免费额度追踪与用量提醒
• 提供 byted_search_pricing 工具，便于查询当前用量和升级入口

版本要求

建议配合支持自定义 Web Search Provider 的 OpenClaw 版本使用。

如果你的 OpenClaw 版本过旧，可能会遇到以下问题：

• tools.web.search.provider: Invalid input (allowed: "brave", "perplexity", "grok", "gemini", "kimi")
• Cannot find module 'openclaw/plugin-sdk/core'
• Cannot find module 'openclaw/plugin-sdk/provider-web-search'

出现这类问题时，优先升级 OpenClaw，再加载本插件。

安装方式

方式一：通过本地路径加载

在 ~/.openclaw/openclaw.json 中增加：

{
  plugins: {
    load: {
      paths: [
        "/Users/bytedance/demo/ask-echo-search/byted-web-search-extension",
      ],
    },
  },
}

方式二：通过 CLI 安装本地目录

openclaw plugins install /Users/bytedance/demo/ask-echo-search/byted-web-search-extension

安装后重启 Gateway。

快速开始

1. 在火山引擎联网搜索控制台创建 API Key
2. 启用插件并配置 Key
3. 把 tools.web.search.provider 设为 "byted-web-search"

最小可用配置：

{
  plugins: {
    load: {
      paths: [
        "/Users/bytedance/demo/ask-echo-search/byted-web-search-extension",
      ],
    },
    entries: {
      "byted-web-search": {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "YOUR_VOLC_WEB_SEARCH_API_KEY",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "byted-web-search",
        maxResults: 5,
        timeoutSeconds: 30,
      },
    },
  },
}

这会让 byted-web-search 成为 OpenClaw 默认搜索引擎。

通过环境变量配置

也可以不把密钥写入配置文件，直接使用环境变量：

export WEB_SEARCH_API_KEY="your-api-key"

然后保留插件启用和 provider 选择配置即可。

密钥优先级：

plugins.entries.byted-web-search.config.webSearch.apiKey > WEB_SEARCH_API_KEY

配置项

插件配置路径：

plugins.entries.byted-web-search.config.webSearch

支持字段如下：

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | apiKey | string | - | 火山联网搜索 API Key | | count | number | 5 | 默认结果数，范围 1-10 | | timeRange | string | - | OneDay、OneWeek、OneMonth、OneYear，或 YYYY-MM-DD..YYYY-MM-DD | | authLevel | number | 0 | 0 表示全部来源，1 表示仅权威来源 | | queryRewrite | boolean | false | 是否启用 Query 改写 |

示例：

{
  plugins: {
    entries: {
      "byted-web-search": {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "YOUR_KEY",
            count: 10,
            timeRange: "OneWeek",
            authLevel: 1,
            queryRewrite: true,
          },
        },
      },
    },
  },
}

插件配置 schema 定义见 openclaw.plugin.json。

使用方式

配置完成后，OpenClaw 在需要联网搜索时会使用这个 provider。你也可以直接让模型发起搜索，例如：

帮我搜索一下 2026 年 AI Agent 框架对比

搜索工具支持以下参数：

{
  "query": "AI Agent 框架对比",
  "count": 10,
  "timeRange": "OneMonth",
  "authLevel": 1,
  "queryRewrite": true
}

byted_search_pricing 工具

插件还注册了 byted_search_pricing 工具，用来查询：

• 当前月份已使用次数
• 剩余额度
• 免费套餐与付费套餐信息
• 控制台和文档入口

典型提问：

我的搜索额度还剩多少？

这个工具的注册逻辑见 index.ts。

免费额度与升级

• 免费额度：500 次/月
• 付费参考：约 0.03 元/次
• 本地额度文件：

~/.openclaw/byted-web-search/quota.json

升级入口：

• 联网搜索控制台
• API Key 管理
• 套餐与定价

常见问题

1. provider 不生效

优先检查：

• 插件是否已加载
• plugins.entries.byted-web-search.enabled 是否为 true
• tools.web.search.provider 是否为 "byted-web-search"
• OpenClaw 是否已经重启

2. 提示缺少 API Key

检查以下任一配置是否生效：

• plugins.entries.byted-web-search.config.webSearch.apiKey
• WEB_SEARCH_API_KEY

3. 返回 10403 或 HTTP 401

通常说明 Key 无效，或者用了火山方舟的 Key。请使用联网搜索控制台创建的 Key。

4. 返回 10406 或 10407

说明免费额度已耗尽，需要等待下月重置或开通付费。

5. 启动时报 Cannot find module 'openclaw/plugin-sdk/*'

说明运行插件的 OpenClaw 宿主版本与插件源码不匹配。请升级 OpenClaw，或确保安装版暴露了对应的 plugin-sdk 子路径。

相关文件

• index.ts
• openclaw.plugin.json

参考链接

• 火山联网搜索 API 文档
• 火山联网搜索控制台
• OpenClaw Plugins 文档