博查搜索 Python 版 (Bocha Search Python)

概述

博查搜索 Python 版是一个增强的博查 AI 搜索 API 客户端，专为 AI Agent 和自动化工作流设计。相比现有的 JavaScript 版本，本技能提供：

• 更稳定的连接：内置重试机制和错误处理
• 灵活的输出格式：支持原始 JSON、Brave/Bing 兼容格式和 Markdown
• 多重配置来源：.env 文件、环境变量
• 完整的时间范围过滤：支持精确日期和日期范围
• 详细的错误信息：帮助快速诊断问题

快速开始

1. 配置 API 密钥

提供 API 密钥的两种方式（按优先级排序）：

1. .env 文件：在 ~/.openclaw/.env 中添加（优先级最高）

   BOCHA_API_KEY=sk-your-api-key
   

2. 环境变量：设置 BOCHA_API_KEY

   export BOCHA_API_KEY="sk-your-api-key"
   

API 密钥获取：访问 https://open.bochaai.com → API KEY 管理

2. 基本搜索

# 使用位置参数
python3 scripts/search.py "沪电股份"

# 使用 --query 选项
python3 scripts/search.py --query "人工智能" --count 5

# 返回详细摘要
python3 scripts/search.py "DeepSeek" --summary

# 限制时间范围
python3 scripts/search.py "AI新闻" --freshness oneWeek --count 10

3. 输出格式

# 原始 JSON 格式（API 原始响应）
python3 scripts/search.py "阿里巴巴" --format raw

# Brave/Bing 兼容格式（默认，适合 AI 使用）
python3 scripts/search.py "阿里巴巴" --format brave

# Markdown 格式（人类可读）
python3 scripts/search.py "阿里巴巴" --format md

高级用法

时间范围过滤

支持多种时间范围格式：

示例：

# 搜索 2025 年 4 月的内容
python3 scripts/search.py "苹果发布会" --freshness 2025-04

# 搜索 2025 年第一季度内容
python3 scripts/search.py "财报" --freshness 2025-01-01..2025-03-31

错误处理与重试

脚本内置错误处理和重试机制：

# 设置重试次数（默认 2 次）
python3 scripts/search.py "查询" --retries 3

# 设置超时时间（默认 30 秒）
python3 scripts/search.py "查询" --timeout 60

自定义 API 端点

支持备用 API 端点：

# 使用备用端点
python3 scripts/search.py "查询" --endpoint "https://api.bocha.cn/v1/web-search"

输出示例

Brave 兼容格式（默认）

{
  "type": "search",
  "query": "阿里巴巴",
  "totalResults": 12345,
  "resultCount": 10,
  "results": [
    {
      "index": 1,
      "title": "阿里巴巴发布2024年ESG报告",
      "url": "https://www.alibabagroup.com/document...",
      "description": "阿里巴巴集团发布《2024财年环境、社会和治理（ESG）报告》...",
      "summary": "报告显示，阿里巴巴扎实推进减碳举措...",
      "siteName": "阿里巴巴集团",
      "publishedDate": "2024-07-22T00:00:00+08:00"
    }
  ]
}

Markdown 格式

## 搜索结果: 阿里巴巴
*找到约 12345 条结果*

1. **阿里巴巴发布2024年ESG报告**
   *阿里巴巴集团*
   [https://www.alibabagroup.com/document...](https://www.alibabagroup.com/document...)
   阿里巴巴集团发布《2024财年环境、社会和治理（ESG）报告》...
   *摘要*: 报告显示，阿里巴巴扎实推进减碳举措...
   *发布时间*: 2024-07-22T00:00:00+08:00

在 OpenClaw 中使用

直接调用脚本

# 从 OpenClaw workspace 根目录调用
python3 skills/bocha-search-python/scripts/search.py "查询"

# 使用绝对路径
python3 /root/.openclaw/workspace/skills/bocha-search-python/scripts/search.py "查询"

集成到 Agent 工作流

在 Agent 的响应中调用搜索并处理结果：