OpenAgent goplaces 技能实战：用 goplaces CLI 驱动 Google Places API（New）完成地点搜索、详情与评论查询

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• MCP Clients
• 交互助手
• 浏览器控制

OpenAgent 通过skills/目录以「技能（Skill）」形式组织外部 CLI 能力，其中goplaces技能封装了 Google Places API（New）的查询能力：搜索地点、解析地址、拉取详情与评论，默认输出人类可读文本，加--json后输出结构化 JSON 供脚本与 Agent 使用。读完本文，你将掌握 goplaces 的安装配置、六类核心命令的完整用法，并理解它在 OpenAgent 技能体系中的加载与调用原理。

goplaces 技能是什么

goplaces是 OpenAgent 内置技能之一，定义在 skills/goplaces/SKILL.md（该目录下仅此一个文件，无references/子目录）。它的定位是：通过 goplaces CLI 查询 Google Places API（New），覆盖文本搜索（text search）、地点详情（place details）、地址解析（resolve）和评论（reviews）四类操作。

从 SKILL.md 的 front matter 可以看出它的能力画像：

--- name: goplaces description: Query Google Places API (New) via the goplaces CLI for text search, place details, resolve, and reviews. Use for human-friendly place lookup or JSON output for scripts. metadata: { "openclaw": { "emoji": "📍", "requires": { "bins": ["goplaces"], "env": ["GOOGLE_PLACES_API_KEY"] }, "primaryEnv": "GOOGLE_PLACES_API_KEY", ... }, } ---

• name：技能唯一标识，也是 Agent 通过load_skill工具加载时的索引名；
• description：告诉 LLM 何时应调用该技能——用户需要「人类友好的地点查询」或「供脚本使用的 JSON 输出」时触发；
• metadata.openclaw.requires：声明硬依赖——需要goplaces可执行文件（bins）与GOOGLE_PLACES_API_KEY环境变量（env），缺一不可；
• primaryEnv：标注最关键的环境变量为GOOGLE_PLACES_API_KEY，便于运行时做依赖检查与提示。

这里的 front matter 由 skillmd/skillmd.go 中的Parse()解析，LoadFolder()（skillmd/skillmd.go）负责把SKILL.md正文与可选references/目录整体读入结构体。

安装 goplaces

goplaces 通过 Homebrew tap 分发，SKILL.md 中明确给出了官方安装方式：

brew install steipete/tap/goplaces

同时 metadata 中记录了结构化安装信息（install.kind = "brew"、formula = "steipete/tap/goplaces"、bins = ["goplaces"]），供 OpenAgent 或第三方 Agent 框架在自动安装流程中直接读取并使用。安装完成后，可用goplaces --help（或goplaces -h）确认二进制就绪。

依赖前提：goplaces 面向现代 Google Places API（New），调用需要可用的 Google Cloud 项目与 Places API（New）配额，且本机网络能访问 Google API 端点。

环境配置：两个环境变量

在 OpenAgent 中运行 goplaces 技能前，需要让GOOGLE_PLACES_API_KEY对 Agent 运行环境可见，例如写入.env或导出到 shell：

export GOOGLE_PLACES_API_KEY="AIza..." # 替换为你自己的密钥

GOOGLE_PLACES_BASE_URL仅在特殊场景使用：当你想把请求打到自建的 API 代理、mock 服务或兼容端点时，把它设置为对应 URL 即可，goplaces 会把所有 Places API 请求重定向过去——这也是无真实密钥环境下做联调的关键开关。

核心命令实战

SKILL.md 浓缩了 goplaces 最常用的六组命令。下面逐一展开。

1. 文本搜索（text search）：基础筛选

最基础的用法是直接搜关键词，并叠加营业状态、评分、条数等筛选：

goplaces search "coffee" --open-now --min-rating 4 --limit 5

参数语义：

• --open-now：只返回当前营业中的地点；
• --min-rating 4：只保留平均评分不低于 4 的地点；
• --limit 5：限制返回 5 条结果。

实际使用时可将三者自由组合，例如「附近营业中且评分高的餐厅」等需求即可一次查询完成。

2. 位置偏置（bias）：按经纬度与半径收敛结果

文本搜索默认全量匹配，若要限定在某个地理范围内，使用经纬度加半径偏置：

goplaces search "pizza" --lat 40.8 --lng -73.9 --radius-m 3000

• --lat/--lng：查询中心点经纬度（此处为纽约市区附近）；
• --radius-m 3000：以米为单位的搜索半径（3000 米）。

它属于「偏置」而非「硬性圈定」——优先返回中心附近的结果，更适合「在 XX 附近找 XX」这类模糊空间需求。

3. 分页：page-token 翻页

Places API（New）的搜索结果支持翻页。goplaces 用--page-token携带上一页返回的令牌继续取下一页：

goplaces search "pizza" --page-token "NEXT_PAGE_TOKEN"

首次查询结果的响应中会携带下一页令牌，将其原样填入即可获得后续批次。分页参数可与--limit、--open-now等筛选组合使用，用于大规模采集场景。

4. 地址解析（resolve）

resolve用于把一段模糊文本（地址、地名、地标名）解析成规范的地点：

goplaces resolve "Soho, London" --limit 5

典型场景是：用户给出「伦敦苏荷区」这种非结构化表述，Agent 先 resolve 拿到规范地点或 place_id，再进入后续的详情查询流程。

5. 地点详情与评论（details + reviews）

拿到 place_id 后，用details拉取完整详情，并可通过--reviews附带用户评论：

goplaces details <place_id> --reviews

• <place_id>：Places API 返回的地点唯一标识（来自 search / resolve 的结果）；
• --reviews：在详情中一并返回评论内容，适合做口碑摘要、评论分析类任务。

不带--reviews时仅返回地点基础信息（名称、地址、坐标、联系方式、评分等），按需控制响应体大小。

6. JSON 输出：供脚本与 Agent 消费

默认输出是经过排版的人类可读文本；需要结构化数据时加--json：

goplaces search "sushi" --json

--json可与上述任意命令组合（search / resolve / details 均适用），输出标准 JSON 供脚本解析或让 Agent 直接提取字段。这也是 SKILL.md description 中「JSON output for scripts」所对应的能力。

输出控制与三个注意事项

SKILL.md 的 Notes 节给出了三个容易踩坑的细节：

1. 关闭 ANSI 颜色：--no-color或设置环境变量NO_COLOR均可禁用彩色输出。管道重定向、写入日志文件、或需要纯净文本时务必使用，避免控制字符污染输出。

2. 价格等级映射：价格等级取值为0..4，含义为free → very expensive（0=免费，4=非常昂贵），用于按消费档位过滤地点。

3. type 过滤的单值限制：--type筛选虽然语法上可以重复传参，但API 只接受一个类型值，goplaces 只会发送第一个--type的值。想按多个类型筛选时，需要分多次查询后在本地合并结果。

在 OpenAgent 中：技能如何被加载与调用

goplaces 之所以能成为 Agent 的一项能力，靠的是 OpenAgent 的技能（Skill）机制，链路清晰可查：

1. 启动加载：object/init.go 的initSkillsFromFolder()在服务启动时扫描skills/目录（优先可执行文件旁，其次当前工作目录），逐个调用LoadSkill()读入；若无磁盘目录则回退到嵌入式 FS（object/init.go 的loadSkillsFromFS()）。解析失败的技能目录只会打印日志跳过，不会阻断服务启动。goplaces 由此成为 owner 为admin、type 为built-in的数据库记录。

2. 解析入库：object/skill.go 的LoadSkill()把 SKILL.md 映射为 Skill 对象：正文（Content）用于注入系统提示词，Description/Homepage/Emoji/Metadata来自 front matter 对应字段，references/下的文件进入References列表。

3. 目录注入：生成回答时，controllers/message_answer.go 调用GetSkillsCatalog()（object/skill.go）把当前 store 启用的技能目录（名称 + 描述 + 类型 + references）拼进提示词，并约束 Agent「涉及列表内技能领域时必须先 load_skill」。

4. 按需加载：Agent 通过内置load_skill工具（tool/skill.go）按名称加载技能完整指令；最终由LoadSkillPromptContent()（object/skill.go）返回技能正文，可选附带某个 reference 文件。对于 goplaces 这类无 references 的技能，加载结果就是本文开头那套命令清单，Agent 依此调用本机 goplaces 二进制完成任务。

5. 人工/脚本加载：若想在服务端手工读取某个技能文件夹，可调用GET /load-skill?path=<绝对路径>（controllers/skill.go），返回解析后的 Skill 对象（尚未入库），适合排查技能解析结果。

小结

goplaces 技能以最小的封装成本，把 Google Places API（New）的搜索、解析、详情、评论能力完整暴露给 OpenAgent 的 Agent 运行时：配置上仅需GOOGLE_PLACES_API_KEY一个必填变量，使用上覆盖筛选、偏置、分页、JSON 输出等日常全部场景，并有--no-color、价格等级、type 单值等细节约束兜底。理解 skills/goplaces/SKILL.md 这份清单，配合 OpenAgent 的 skillmd 解析与 load_skill 调用链路，你既可以手工完成地点查询，也可以把它作为模板，在skills/下以同样的 SKILL.md 格式快速接入更多外部 CLI 能力。

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• MCP Clients
• 交互助手
• 浏览器控制