为AI智能体集成Google可编程搜索引擎：解决多语言搜索难题

1. 项目概述与核心价值

最近在折腾一个需要联网搜索的智能体项目，发现市面上很多开源方案用的都是DuckDuckGo这类免费搜索引擎。用起来是方便，但真到了要查点具体资料，尤其是非英文内容时，那搜索结果的质量就有点捉襟见肘了。特别是当我需要搜索韩语内容时，DuckDuckGo返回的结果要么不相关，要么信息陈旧，完全没法用。这逼得我不得不寻找一个更可靠的方案，于是就有了这个基于Google可编程搜索引擎（Programmable Search Engine, PSE）API的搜索技能（Skill）项目。

简单来说，google-pse-search是一个为OpenClaw智能体框架设计的插件或“技能”。它的核心功能就是代替那些免费的、但质量不稳定的搜索引擎，为你的AI智能体提供一个稳定、高质量、且功能丰富的网页搜索能力。它底层调用的不是我们平常在浏览器里用的那个Google搜索，而是Google官方提供给开发者的PSE API。这个API允许你创建一个自定义的搜索引擎，可以限定搜索范围（比如只搜特定网站），还能获得结构化的、干净的JSON格式结果，这对于程序化处理来说简直是福音。

这个技能最适合两类人：一类是正在基于OpenClaw这类框架开发AI助手、客服机器人或者研究型智能体的开发者，你需要一个靠谱的“眼睛”让AI去看外面的世界；另一类是对搜索结果质量有要求，尤其是需要处理多语言内容（像韩语、日语等）的开发者。如果你受够了免费API返回的无关信息，或者你的应用场景对信息的时效性和准确性有要求，那么这个项目值得你花时间集成进去。

2. 为什么选择Google PSE而非其他方案？

在决定用Google PSE之前，我几乎把市面上能用的方案都试了个遍。这里简单拆解一下我的选型思路，或许能帮你避开一些坑。

2.1 免费方案的局限性：以DuckDuckGo为例

DuckDuckGo（DDG）的Instant Answer API确实免费、无需密钥，对于简单的、通用的英文查询勉强够用。但它有几个硬伤： 第一，结果质量参差不齐。对于技术性、区域性或者非英语的关键词，它经常返回一些风马牛不相及的页面，或者权重很低的论坛帖子，权威性信息很少出现在前列。 第二，缺乏精细控制。你很难对搜索结果进行过滤，比如按精确时间范围（如“过去24小时内”）、按特定网站/域名进行搜索。这对于需要追踪最新动态或只信任某些信源的应用来说是致命缺陷。 第三，结构化数据差。DDG返回的HTML页面需要自己解析，虽然有一些开源解析器，但稳定性堪忧，页面结构一变就可能挂掉。而PSE API返回的是标准的JSON，字段清晰，包含了标题、链接、摘要、缩略图URL等，直接可用。

2.2 付费方案的对比：SerpAPI、Serper vs Google PSE

既然免费的不行，那就看付费的。SerpAPI和Serper.dev都是不错的第三方服务，它们帮你处理了模拟真实用户搜索的复杂过程（反爬虫、渲染等），提供干净的API。但它们本质上是“二道贩子”，成本最终会转嫁给你，且依赖于它们服务的稳定性。

Google PSE则是“直通车”。你直接和Google的API交互，没有中间商。从长期来看，成本更可控。PSE有免费的每日配额（具体额度需在Google Cloud控制台查看），对于个人项目或中等使用频率的应用，很可能完全免费。即使超出，其付费费率也相对透明和稳定。

更重要的是，可控性极强。通过PSE的控制台，你可以精确定义你的搜索引擎：是搜索整个互联网，还是只搜索你指定的一个或多个网站？这对于构建垂直领域的知识库或内部工具搜索来说，功能强大到无可替代。这是其他通用搜索API难以提供的。

2.3 Google PSE的核心优势总结

所以，最终拍板用Google PSE，主要是基于这几点：

• 质量与权威性：背靠Google的搜索索引，结果的相关性和质量是目前的天花板，对多语言支持（如韩语）尤其出色。
• 功能完整：原生支持按日期过滤 (dateRestrict)、按网站过滤 (siteSearch)、分页 (start)、安全搜索过滤 (safe) 等高级参数，满足复杂查询需求。
• 直接与稳定：直连Google官方API，没有额外的抽象层，减少了潜在故障点，响应速度也更有保障。
• 成本灵活：免费额度+透明付费模式，适合从原型到产品的各个阶段。

注意：使用Google PSE API需要一个Google Cloud Platform (GCP) 项目并启用计费功能（即使你只用免费额度）。对于新手来说，GCP的配置过程可能稍显复杂，但一旦设置完成，后续就一劳永逸了。

3. 前期准备：从零开始配置Google PSE

要让google-pse-search跑起来，核心就是拿到两把“钥匙”：GOOGLE_PSE_KEY(API密钥) 和GOOGLE_CX_ID(搜索引擎ID)。下面我以创建一个全新的搜索引擎为例，带你走一遍流程。

3.1 创建GCP项目与启用API

首先，访问 Google Cloud Console 。如果你没有GCP账户，需要先注册，通常会赠送一定额度的免费试用金，足够我们开发测试。

1. 在控制台顶部的项目下拉菜单旁，点击“新建项目”。
2. 给你的项目起个名字，比如my-openclaw-search。项目ID会自动生成，你可以用默认的。然后点击“创建”。
3. 项目创建好后，确保你位于这个新项目中。在左侧导航栏找到“API和服务” -> “库”。
4. 在搜索框中输入“Custom Search API”，找到后点击进入。
5. 点击“启用”按钮。这个过程可能需要几分钟。

3.2 创建可编程搜索引擎（CX）

API启用后，我们需要创建实际的搜索引擎实例。

1. 访问 Programmable Search Engine 控制台 。
2. 点击“创建新的搜索引擎”。
3. “要搜索的网站”：这是最关键的一步。
   • 如果你想创建一个搜索整个互联网的引擎，这里可以填写一个示例网站（例如example.com），或者直接留空。在创建完成后，进入引擎的“设置” -> “基本”中，将“搜索整个网络”选项打开。
   • 如果你想创建一个限定范围的引擎（例如只搜索github.com和stackoverflow.com），就在这里填写github.com/*, stackoverflow.com/*。你可以随时回来修改这个列表。
4. 给你的搜索引擎起个名字，比如My OpenClaw Web Search。
5. 点击“创建”。创建成功后，你会进入管理页面。
6. 在这个页面上，找到“搜索引擎ID”。这个长字符串（格式如012345678901234567890:a1b2c3d4e5f）就是你的GOOGLE_CX_ID。把它复制保存好。

3.3 创建API密钥

现在我们需要一个API密钥来调用这个搜索引擎。

1. 回到 Google Cloud Console ，在你的项目下，进入“API和服务” -> “凭据”。
2. 点击“创建凭据” -> “API密钥”。
3. 系统会生成一个密钥。立即对它进行限制！这是安全最佳实践。点击密钥名称进入编辑页面。
4. 在“API限制”部分，选择“限制密钥”。
5. 在下拉列表中，找到并选择“Custom Search API”。这样，这个密钥就只能用于调用搜索API，即使泄露，危害也有限。
6. （可选但推荐）在“应用程序限制”部分，你可以根据情况选择“HTTP 引用网址”来限制哪些网站能使用此密钥，或者“IP地址”来限制服务器IP。对于本地开发或服务器应用，选择“IP地址”并填入你的服务器公网IP更安全。
7. 点击“保存”。保存下来的这个密钥就是你的GOOGLE_PSE_KEY。

3.4 本地环境变量配置

拿到GOOGLE_PSE_KEY和GOOGLE_CX_ID后，需要让OpenClaw技能能读取到它们。根据项目说明，我们需要在OpenClaw的工作空间目录下的.env文件中设置。 假设你的OpenClaw项目根目录是~/my-openclaw-project，那么：

# 切换到工作空间目录（通常workspace在项目根目录下） cd ~/my-openclaw-project/workspace # 编辑或创建 .env 文件 nano .env

在.env文件中添加如下两行：

GOOGLE_PSE_KEY=你的_API_密钥_字符串 GOOGLE_CX_ID=你的_搜索引擎ID_字符串

保存退出。这样，google-pse-search技能在运行时就能自动从环境变量中加载这些配置了。

实操心得：千万不要把API密钥和CX ID硬编码在代码里，尤其是打算开源或上传到版本控制系统时。.env文件通常被.gitignore排除，是管理敏感配置的标准做法。另外，建议为开发、测试、生产环境使用不同的GCP项目和API密钥，方便管理和控制成本。

4. 技能集成与核心功能深度解析

配置好环境后，我们来看看如何把这个技能集成到你的OpenClaw智能体中，并深入理解它提供的强大搜索能力。

4.1 技能安装与注册

通常，OpenClaw的技能是以Python包或模块的形式存在的。你需要将这个google-pse-search的技能代码放到OpenClaw技能目录下，或者在项目的依赖中声明。

1. 代码放置：将技能文件夹（包含__init__.py,skill.py,SKILL.md等文件）复制到你的OpenClaw项目的skills/目录下。确保目录结构清晰。
2. 依赖管理：检查google-pse-search的requirements.txt或pyproject.toml，它很可能依赖requests库来调用HTTP API。确保你的虚拟环境中已安装这些依赖：pip install requests。
3. 注册技能：在OpenClaw的主配置文件或技能加载机制中，你需要注册这个新技能。具体方式取决于OpenClaw的版本，可能需要在一个配置列表中添加技能名，或者在代码中动态导入并注册。参考OpenClaw的官方文档完成这一步。

4.2 核心搜索函数剖析

技能的核心是一个搜索函数。我们根据常见的PSE API调用模式，可以推断并还原出其内部实现的关键逻辑。以下是一个高度仿真的、可直接使用的search函数示例：

import os import requests from typing import Dict, List, Optional from urllib.parse import urlencode class GooglePSESearcher: def __init__(self): self.api_key = os.getenv("GOOGLE_PSE_KEY") self.cx_id = os.getenv("GOOGLE_CX_ID") self.base_url = "https://www.googleapis.com/customsearch/v1" if not self.api_key or not self.cx_id: raise ValueError("GOOGLE_PSE_KEY and GOOGLE_CX_ID must be set in environment variables.") def search( self, query: str, num_results: int = 10, start_index: int = 1, date_restrict: Optional[str] = None, site_search: Optional[str] = None, **extra_params ) -> List[Dict]: """ 执行Google PSE搜索。 Args: query: 搜索关键词。 num_results: 返回的结果数量（最大值通常为10，分页获取更多）。 start_index: 起始索引，用于分页（1表示第一页）。 date_restrict: 日期限制，例如 “d7” (过去一周), “m1” (过去一月), “y1” (过去一年)。 site_search: 限定在特定网站内搜索，例如 “github.com”。 **extra_params: 其他传递给API的参数。 Returns: 一个字典列表，每个字典包含 ‘title‘, ‘link‘, ‘snippet‘ 等字段。 """ params = { "key": self.api_key, "cx": self.cx_id, "q": query, "num": min(num_results, 10), # API单次请求最多返回10条 "start": start_index, } # 添加可选参数 if date_restrict: params["dateRestrict"] = date_restrict if site_search: params["siteSearch"] = site_search params.update(extra_params) try: response = requests.get(self.base_url, params=params) response.raise_for_status() # 如果状态码不是200，抛出HTTPError data = response.json() except requests.exceptions.RequestException as e: return [{"error": f"Network or API error: {str(e)}"}] except ValueError as e: return [{"error": f"Failed to parse JSON response: {str(e)}"}] # 解析并格式化结果 search_results = [] if "items" in data: for item in data["items"]: result = { "title": item.get("title", "No Title"), "link": item.get("link", "#"), "snippet": item.get("snippet", "No snippet available."), # 可以添加更多字段，如 displayLink, pagemap 等 } search_results.append(result) else: # 没有结果或发生错误 if "error" in data: search_results.append({"error": data["error"].get("message", "Unknown API error")}) else: # 搜索词可能没有返回结果 search_results.append({"info": "No search results found."}) return search_results

4.3 高级搜索功能应用示例

这个技能之所以强大，在于它暴露了PSE API的多种参数。下面通过几个具体场景展示如何使用：

• 基础搜索：智能体接收到用户问题“什么是机器学习？”，直接调用search(“机器学习”)。
• 时效性搜索：用户问“OpenAI最近有什么新动态？”。调用search(“OpenAI 最新动态”, date_restrict=”d7”)，只返回过去一周的结果，确保信息新鲜。
• 垂直领域搜索：开发者想查找某个错误在Stack Overflow上的解答。调用search(“Python TypeError site:stackoverflow.com”, site_search=”stackoverflow.com”)，或者直接在创建CX时限定范围，结果精准度极高。
• 分页获取更多结果：默认一次10条不够？第一次调用search(“深度学习框架”, num_results=10, start_index=1)，第二次调用search(“深度学习框架”, num_results=10, start_index=11)，即可获取第11-20条结果。

4.4 与OpenClaw智能体的协同工作流

集成后，这个技能通常会被OpenClaw的智能体在需要信息时调用。一个典型的工作流是：

1. 意图识别：用户输入“帮我查一下今天比特币的价格”。
2. 技能匹配：OpenClaw的规划模块识别出需要“网络搜索”能力。
3. 查询构造：智能体可能会将用户问题重写或优化为更适合搜索引擎的查询词，例如“比特币 BTC 最新价格 今日”。
4. 调用搜索技能：执行google_pse_search.search(“比特币 BTC 最新价格 今日”, date_restrict=”d1”)。
5. 结果处理与整合：技能返回结构化结果。智能体可以提取摘要、链接，甚至调用其他技能（如网页抓取）获取更详细内容，最后组织成自然语言回复给用户：“根据网络搜索，截至今天，比特币价格约为XXXXX美元...”。

5. 实战中的问题排查与优化技巧

在实际集成和使用过程中，你肯定会遇到一些问题。下面是我踩过坑后总结出来的常见问题及解决方案。

5.1 常见错误与响应处理

5.2 性能与成本优化策略

1. 结果缓存：对于相对静态的查询（例如“Python的历史”），可以在智能体层面或技能内部添加一个简单的缓存（如使用functools.lru_cache或外部Redis）。设定一个合理的TTL（例如1小时），可以大幅减少API调用次数，提升响应速度并节省配额。
2. 智能查询去重：在智能体规划环节，如果短时间内生成了多个语义相似的搜索查询，可以尝试去重或合并，避免对同一信息进行多次搜索。
3. 按需设置num参数：不是每次都需要10个结果。对于事实性问答，可能前3个结果就够了。根据任务类型动态调整num_results参数。
4. 监控与告警：在GCP中为Custom Search API设置预算提醒，当费用或请求量达到一定阈值时发送邮件告警，避免意外高额账单。

5.3 处理非英语及特殊字符搜索

项目提到对韩语内容支持好，这得益于Google强大的多语言索引。但在代码层面，需要注意URL编码。

# 使用 requests 库，它会自动处理查询参数的编码 # 但如果你手动拼接URL，务必使用 urllib.parse.quote from urllib.parse import quote korean_query = “파이썬 프로그래밍” encoded_query = quote(korean_query) # 输出 ‘%ED%8C%8C%EC%9D%B4%EC%8D%AC%20%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D‘

在我们的search函数中，由于使用了requests.get(params=...)，它会自动完成编码，所以你直接传入包含中文、韩文、空格的查询字符串即可。

5.4 扩展技能功能

基础的搜索返回了标题、链接和摘要。你可以根据智能体的需要，轻松扩展这个技能：

• 丰富返回字段：PSE API的返回结果 (item) 里可能包含pagemap(页面结构化数据)、formattedUrl等，可以解析出来供智能体更深入地理解页面内容。
• 结果后处理：例如，对摘要进行清洗（去除HTML标签、多余空格），或者根据链接域名对结果进行可信度排序。
• 多搜索引擎备胎：在技能内部实现一个降级逻辑。当Google PSE API因配额、网络等原因失败时，自动尝试使用DuckDuckGo或其他备用搜索引擎，保证服务的可用性。

最后，集成外部搜索能力是让AI智能体摆脱“信息孤岛”的关键一步。google-pse-search这个技能提供了一条稳定、高质量的路径。从配置到集成，再到优化，整个过程需要一些耐心，但一旦跑通，你的智能体获取实时信息的能力将会有质的飞跃。尤其是在处理非英语内容时，你会立刻体会到“一分钱一分货”的道理——高质量的信息源值得投入。