Vincent — 面向智能体的 Brave 搜索服务

使用本技能，可通过 Brave Search 执行网页与新闻搜索。所有请求均通过 Vincent 后端代理：该后端负责与 Brave Search API 的身份认证、强制执行速率限制、追踪每次调用成本，并自动从您的信用余额中扣减费用。

无需管理 API 密钥。 智能体通过一个作用域限定为 DATA_SOURCES 密钥的 Vincent API 密钥完成身份认证。上游 Brave Search API 的凭据由 Vincent 服务端统一管理——智能体既不会接触也不会管理任何 Brave API 密钥。

所有命令均依赖 @vincentai/cli 包。API 密钥由 CLI 自动存储与解析——您无需处理原始密钥或文件路径。

安全模型

本技能专为按次计费、具备人工监督能力的自主智能体运行场景而设计。

无需配置环境变量。 本技能采用“以智能体为中心”的接入流程：智能体在运行时调用 Vincent API 创建一个 DATA_SOURCES 密钥，API 将返回一个作用域受限的 API 密钥；CLI 在创建过程中自动保存该密钥。密钥持久化路径（${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials/datasources/ 或 ./datasources/）已在本技能的元数据中声明。

智能体所使用的 API 密钥并非 Brave Search API 密钥。 它是面向 Vincent 代理服务的、作用域受限的 Bearer Token。Vincent 服务器代表智能体与 Brave Search 进行身份认证。智能体无法绕过代理直接访问上游 API，也无法规避代理层实施的信用额度与速率限制管控。

模型调用功能默认启用。 本技能的核心目标是赋予 AI 智能体自主进行网络搜索的能力。智能体应能独立发起网页与新闻搜索。人类用户通过 https://heyvincent.ai 管理信用余额与支付方式，从而控制整体支出。

所有 API 请求均仅通过 HTTPS/TLS 协议发送至 heyvincent.ai。 Vincent 服务器再代为调用 Brave Search API。智能体不与 Brave 服务直接通信。

密钥生命周期说明：

• 创建：智能体执行 secret create 命令并指定 --type DATA_SOURCES —— CLI 自动保存 API 密钥，并返回 keyId 与 claimUrl。
• 认领：人工操作员使用 claim URL 在 https://heyvincent.ai 上完成所有权认领、充值及支付方式管理。
• 信用额度：每次 API 调用产生小额费用（详见下方定价说明）。用户需通过前端界面充值；当信用余额耗尽且未绑定支付方式时，后续调用将被拒绝。
• 撤销：密钥所有者可随时通过 Vincent 前端撤销该智能体的 API 密钥。

定价

信用额度按次自动扣除。响应中包含 _vincent.creditRemainingUsd 字段，供智能体实时追踪剩余余额。

快速开始

1. 检查是否存在已有密钥

在新建密钥前，请先确认是否已存在有效密钥：

npx @vincentai/cli@latest secret list --type DATA_SOURCES

若返回密钥，则将其 id 作为后续所有命令的 --key-id 参数值；若无返回结果，则需新建密钥。

2. 创建数据源密钥（DATA SOURCES Secret）

npx @vincentai/cli@latest secret create --type DATA_SOURCES --memo "My agent data sources"

命令返回 keyId（供后续所有命令使用）和 claimUrl（需提供给终端用户）。

创建完成后，请向用户说明：

“这是您的数据源认领链接：。请通过该链接前往 https://heyvincent.ai 认领所有权，并为 Brave Search 及其他数据源充值。”

重要提示： 密钥必须完成认领，并已充值（或已绑定支付方式），API 调用方可成功。

3. 网页搜索

npx @vincentai/cli@latest brave web --key-id  --q "latest AI news" --count 10

参数说明：

• --q（必填）：搜索关键词（长度 1–400 字符）
• --count（可选）：返回结果数量，取值范围 1–20（默认值：10）
• --offset（可选）：分页偏移量，取值范围 0–9
• --freshness（可选）：时间筛选条件 — pd（过去 24 小时）、pw（过去一周）、pm（过去一月）、py（过去一年）
• --country（可选）：地区代码（两位字母），用于返回本地化结果（例如：us、gb、de）

返回结果包含标题、URL、摘要及元数据信息。

4. 新闻搜索

npx @vincentai/cli@latest brave news --key-id  --q bitcoin --count 10

参数说明：

• --q（必填）：搜索关键词（长度 1–400 字符）
• --count（可选）：返回结果数量，取值范围 1–20（默认值：10）
• --freshness（可选）：时间筛选条件 — pd（过去 24 小时）、pw（过去一周）、pm（过去一月）、py（过去一年）

返回结果包含标题、URL、摘要、发布日期及信源信息。

响应元数据

每次成功响应均包含一个 _vincent 对象，结构如下：

{
  "_vincent": {
    "costUsd": 0.005,
    "creditRemainingUsd": 4.99
  }
}

请使用 creditRemainingUsd 字段，在信用余额不足时及时向用户发出提醒。

输出格式

网页搜索结果示例：

{
  "web": {
    "results": [
      {
        "title": "Article Title",
        "url": "https://example.com/article",
        "description": "A brief description of the article content."
      }
    ]
  },
  "_vincent": {
    "costUsd": 0.005,
    "creditRemainingUsd": 4.99
  }
}

新闻搜索结果结构相同，但每条结果额外包含 age 和 source 字段。

错误处理

速率限制

• 每个 API 密钥每分钟最多 60 次请求（涵盖所有数据源端点，包括 Twitter 与 Brave Search）
• 若触发限流，将收到 429 响应。请等待后重试。

重新绑定（恢复 API 访问）

若智能体丢失其 API 密钥，密钥所有者可在前端生成一个重新绑定令牌（re-link token），智能体随后可用该令牌换取新的 API 密钥。

npx @vincentai/cli@latest secret relink --token 

CLI 将使用该令牌换取新 API 密钥，自动保存，并返回新的 keyId。重新绑定令牌为一次性使用，10 分钟后自动过期。

充值信用额度

当信用余额不足时，您可通过 Base 链上的 USDC，基于 x402 支付协议自主完成充值——全程无需人工介入。

支持的充值档位： $1、$5、$10、$25、$50、$100

查询余额

npx @vincentai/cli@latest credits balance --key-id 

通过 x402（Base 链 USDC）充值

npx @vincentai/cli@latest credits add --key-id  --amount 10

工作流程：

1. CLI 向 x402 信用充值端点发送 POST 请求
2. 服务端返回 HTTP 402 状态码，并附带一个动态生成的 Base 链 USDC 充值地址
3. CLI 使用智能体钱包对该笔支付进行签名
4. CLI 携带支付凭证再次发起请求
5. 服务端验证付款后，将对应信用额度计入您的账户

前提条件：

• 支持 x402 协议的钱包，且钱包内持有 Base 链（链 ID：8453）USDC
• 有效的 Vincent DATA_SOURCES API 密钥

通过信用卡充值（人工操作）

npx @vincentai/cli@latest credits checkout --key-id 

返回 Stripe Checkout 页面 URL。请将该链接提供给用户，以便其使用信用卡完成支付。

MCP 工具

自动补货模式（Auto-Replenish Pattern）

对于长期运行的智能体，建议在执行高成本操作前检查余额，并在余额较低时自动充值：

BALANCE=$(npx @vincentai/cli@latest credits balance --key-id  --json | jq -r '.balance')
if (( $(echo "$BALANCE < 2.00" | bc -l) )); then
  npx @vincentai/cli@latest credits add --key-id  --amount 10
fi

重要说明

• 单个 DATA_SOURCES API 密钥适用于全部数据源（如 Twitter、Brave Search 等），无需为不同数据源单独申请密钥。
• 创建密钥后，请务必向用户共享 claim URL。
• 若某次调用因信用额度问题被拒绝，请提示用户前往 https://heyvincent.ai 充值。