OpenClaw goplaces 技能实战：Google Places API CLI 的安装、配置与查询命令全解-平芜编程栈

OpenClaw goplaces 技能实战：Google Places API CLI 的安装、配置与查询命令全解

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

OpenClaw 以「技能（Skill）」为单位扩展 Agent 的动手能力，goplaces是其中对接 Google Places API（New）的 CLI 技能：一条命令即可完成地点文本搜索、详情与评论查询、地址解析，并支持--json输出用于脚本化。本文基于仓库中的 goplaces 技能定义，完整讲清该技能的元数据契约、依赖声明、安装与环境变量配置、全部常用命令及参数语义，并结合 OpenClaw 源码说明技能如何被解析、检测与修复，读完即可在自己的 OpenClaw 环境中直接启用该技能。

一、goplaces 技能定位：为 Agent 提供 Places 查询能力

goplaces 是一个「现代版 Google Places API (New)」的命令行封装，其设计原则是：默认输出人类可读文本，加--json切换为脚本友好的 JSON。技能描述（来自 SKILL.md 的 frontmatter）为：

Query Google Places for text search, place details, resolve, reviews, or scriptable JSON via goplaces.

在 OpenClaw 的技能体系里，每个技能就是一个目录加一个SKILL.md文件，frontmatter 声明元数据，正文给出安装方式、配置要求与常用命令。skills/goplaces/目录下的这份 SKILL.md 即遵循该约定，覆盖四类典型操作：

文本搜索（search）：按关键词搜索地点，支持营业状态、评分、数量等过滤与地理偏置、分页；
地址/地点解析（resolve）：把「Soho, London」这类自由文本解析为结构化地点；
地点详情（details）：按place_id拉取详情，可附带评论（--reviews）；
脚本化 JSON：任意查询加--json，供 Agent 或管道程序消费。

二、技能元数据：frontmatter 与 OpenClaw 依赖契约

先看 SKILL.md 的完整 frontmatter，它是 OpenClaw 加载、校验和修复该技能的唯一声明来源：

--- name: goplaces description: "Query Google Places for text search, place details, resolve, reviews, or scriptable JSON via goplaces." homepage: https://github.com/steipete/goplaces metadata: openclaw: emoji: 📍 requires: bins: ["goplaces"] env: ["GOOGLE_PLACES_API_KEY"] primaryEnv: "GOOGLE_PLACES_API_KEY" install: - id: "brew" kind: "brew" formula: "steipete/tap/goplaces" bins: ["goplaces"] label: "Install goplaces (brew)" ---

各字段的作用：

字段	作用
`name`/`description`	技能标识与一句话能力描述，用于技能索引与模型侧展示
`metadata.openclaw.requires.bins`	声明运行前置：系统必须存在`goplaces`可执行文件
`metadata.openclaw.requires.env`	声明必须注入的环境变量：`GOOGLE_PLACES_API_KEY`
`metadata.openclaw.primaryEnv`	标记主凭据变量，供配置引导与状态检测优先检查
`metadata.openclaw.install`	可执行的安装规格（install spec），此技能提供 Homebrew 方式安装`steipete/tap/goplaces`，装完后校验`goplaces`二进制存在

这套契约并非装饰：OpenClaw 的 frontmatter 解析器会真正校验安装规格。从源码看，frontmatter 解析模块中的parseInstallSpec支持brew、node、go、uv、download五种安装方式，并对 brew formula 做安全校验——公式名必须匹配BREW_FORMULA_PATTERN（以字母数字开头，仅允许@ + . _ / -等安全字符），拒绝以-开头、包含\或..的输入。steipete/tap/goplaces正是通过该校验后，才会进入技能状态报告中的可安装项。

当技能缺失依赖时，doctor 命令会基于同一份契约生成修复建议。仓库中的 doctor skills 测试恰好以 goplaces 为样例构造了「缺少二进制 + 缺少环境变量」的场景，断言 doctor 输出包含如下提示：

2 allowed skills are not usable in this environment (missing binaries, env vars, or config). - calendar, places Disable unused skills: openclaw doctor --fix Inspect details: openclaw skills check --agent <id> or openclaw skills info <name> --agent <id>

也就是说，若你在某台机器上装了 OpenClaw 但没装goplaces、也没设置GOOGLE_PLACES_API_KEY，运行openclaw doctor会明确告诉你该技能不可用、缺什么，并给出openclaw doctor --fix或openclaw skills info goplaces --agent <id>的排查入口。

三、安装：通过 Homebrew 安装 goplaces

技能声明的安装方式是 Homebrew（第三方 tap）：

brew install steipete/tap/goplaces

安装成功后goplaces进入 PATH，满足 frontmatter 中requires.bins: ["goplaces"]的前置条件。仓库测试 onboard-skills.test.ts 中同样以name: "goplaces"的技能条目验证了技能入库流程，说明该技能与 OpenClaw 的技能发现/入库链路是完整对接的。

在容器化部署场景中，OpenClaw 也给出了针对 goplaces 的专门说明。Docker VM 运行时文档列出了镜像内置的 CLI 工具（其中goplaces for Google Places），并说明对于goplaces这类下载的 release 二进制，需要在容器内确认其位置，验证命令为：

docker compose exec openclaw-gateway which goplaces

如果which查不到，通常意味着该版本镜像未包含此二进制，需要确认镜像版本或按文档说明补充下载。

四、配置：两个环境变量

goplaces 的配置只有两个变量：

环境变量	必需性	说明
`GOOGLE_PLACES_API_KEY`	必需	Google Places API 凭据，frontmatter 中同时声明于`requires.env`与`primaryEnv`
`GOOGLE_PLACES_BASE_URL`	可选	覆盖 API 基础地址，用于测试或经由代理转发请求

建议把GOOGLE_PLACES_API_KEY配置在 OpenClaw 运行环境（例如 systemd 单元、Docker 环境变量或 shell profile）中，保证 Agent 执行技能时进程能继承到该变量——否则技能状态会因missing.env被判定为不可用。GOOGLE_PLACES_BASE_URL则适合本地 mock 服务或企业代理场景：不改代码即可把全部 Places 请求指到自定义端点。

五、常用命令与参数详解

以下命令全部继承自 SKILL.md 的「Common commands」小节，是日常使用的主力命令集。

1. 文本搜索（search）

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

参数语义：

"coffee"：搜索关键词，建议加引号防止 shell 分词；
--open-now：只返回当前营业中的地点；
--min-rating 4：最低评分过滤（示例取 4 分及以上）；
--limit 5：限制返回条数。

2. 地理偏置搜索（bias）

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

--lat/--lng：搜索中心点坐标（示例为纽约一带）；
--radius-m 3000：以米为单位的搜索半径，示例为 3 公里。

地理偏置让搜索围绕给定坐标展开，适合「我在某经纬度附近找店」这类 Agent 场景。

3. 分页（page-token）

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

Places 搜索的分页不靠页码而靠 token：第一次搜索的响应会带回下一页 token，把它原样填入--page-token即可继续拉取。脚本化流程通常是「首查 → 记录 token → 循环翻页」。

4. 地址解析（resolve）

goplaces resolve "Soho, London" --limit 5

把自由文本地名解析为结构化地点列表，--limit限制候选数量。适合从用户口语化输入中拿到place_id，再交给details命令深入查询。

5. 地点详情（details）

goplaces details <place_id> --reviews

<place_id>：Places API 返回的地点唯一标识（可来自 search/resolve 结果）；
--reviews：附带该地点的评论信息。

6. JSON 输出（scriptable）

goplaces search "sushi" --json

加--json后输出结构化 JSON，可直接被jq或 Agent 代码解析。这是技能描述中「scriptable JSON」承诺的落点：人机输出双模式是 goplaces 的核心设计。

六、输出与过滤的细节注意事项

原文档「Notes」小节给出三条对实操很关键的行为说明，必须留意：

禁用彩色输出：--no-color参数或NO_COLOR环境变量均可关闭 ANSI 颜色。重定向到文件或管道时建议显式关闭，避免转义码污染 JSON/文本处理。
价格等级取值：价格过滤使用0..4五档，从 free（免费）到 very expensive（非常昂贵）。脚本中按档位传值即可。
类型过滤只取第一个--type：由于 Places API 一次只接受一个类型，--type即使传多个，实际也只发送第一个值。需要多类型搜索时应分多次调用，而非依赖单次命令。

七、源码视角：goplaces 技能在 OpenClaw 中的生命周期

把前面各节串起来，goplaces 在 OpenClaw 内经历的生命周期是：

加载与解析：技能 frontmatter 解析器读取 SKILL.md，提取name、description、metadata.openclaw（含requires与install规格），并对 brew formula 等安装字段做安全校验；
状态检测：技能状态模块（如 status.ts 定义的技能状态报告）按requires检查二进制与环境变量是否齐备，缺项会归入missing.bins/missing.env；
诊断与修复：openclaw doctor走 doctor-skills 逻辑的测试所覆盖的路径，把不可用技能按字母序压缩列出，并提示openclaw doctor --fix自动禁用或安装；
入库与调用：技能通过 onboard-skills 流程等链路进入工作区技能集，供 Agent 在会话中调用。

理解这条链路后，排查 goplaces 不可用的思路就是逐层对照：frontmatter 声明的goplaces二进制在不在 PATH、GOOGLE_PLACES_API_KEY有没有注入、安装规格能否被 doctor 识别，三问即可定位绝大多数问题。

八、小结与适用边界

goplaces 技能 = 一个SKILL.md+ 一个外部 CLI 二进制：元数据负责「声明依赖与安装方式」，CLI 负责「执行 Places 查询」；
上手三步：brew install steipete/tap/goplaces→ 注入GOOGLE_PLACES_API_KEY（可选GOOGLE_PLACES_BASE_URL）→ 用search / resolve / details三类命令干活，脚本化场景统一加--json；
关键行为备忘：颜色输出可用--no-color关闭、价格档位为 0..4、--type只生效第一个值、分页依赖--page-token；
适用前提：命令语义以当前仓库 SKILL.md 的声明为准，实际参数全集取决于所安装 goplaces 版本，遇到差异以goplaces --help为准。