OpenStreet Map Skill (for OpenClaw)
This skill provides two capabilities:
- 1. Query one place's location information.
- Render an annotated map image for multiple places with numbered markers and a legend.
Prerequisites
- - Python 3.10+
- Internet access (Nominatim + OSM tile endpoints)
Optional environment variable:
- -
OPENSTREET_MAP_HOST: Override only the openstreetmap.org host suffix in the default endpoints. Recommended form: openstreetmap.org. If http:// or https:// is provided, only the host part is used.
When set, the skill uses:
- - Geocode endpoint: INLINECODE5
- Tile endpoint: INLINECODE6
Examples:
- -
OPENSTREET_MAP_HOST=openstreetmap.org -> INLINECODE8 - INLINECODE9 -> INLINECODE10
Install
CODEBLOCK0
Capability 1: Query location info
CODEBLOCK1
Output is JSON including display_name, lat, lon, and type metadata.
Capability 2: Render annotated map
Input JSON file format (array):
CODEBLOCK2
Render command:
CODEBLOCK3
Render command with base64 JSON input:
CODEBLOCK4
Optional: render command returning base64-encoded image (no file written):
CODEBLOCK5
Optional: render command writing file and returning base64:
CODEBLOCK6
INLINECODE14 input/output options:
- -
--points-file / --points-base64: points source (mutually exclusive, one required). - INLINECODE17 : save image to path. This is the default and recommended output mode.
- INLINECODE18 : include base64-encoded PNG in JSON stdout under
image_base64. Use only when the caller cannot access output files directly. - At least one of
--output or --base64 must be provided.
Recommended: Default to file output with --output.
Do not use --base64 unless file delivery is impossible, because base64 image payloads consume a large number of tokens.
CODEBLOCK7
Behavior:
- - Selects a suitable zoom level to fit all points.
- Downloads OSM tiles and stitches them into one map image.
- Draws numbered markers on each place.
- Appends a three-column legend under the map showing index and place name.
- Saves final image to
--output path if specified.
JSON output structure:
CODEBLOCK8
- -
output: present only when --output is provided. - INLINECODE27 : present only when
--base64 is set. PNG image encoded as standard base64. Avoid this in normal flows because it significantly increases token usage.
Notes for OpenClaw integration
- - Expose these two CLI actions as callable tools in OpenClaw:
-
locate: maps to
python tools/openstreet_skill.py locate ...
-
render: maps to
python tools/openstreet_skill.py render ...
- - For
render, default to --output file delivery instead of --base64 to keep responses small. - Return JSON stdout to the caller and treat non-zero exit code as failure.
- Respect OSM usage policy by not sending high-frequency requests.
OpenStreet Map 技能（适用于 OpenClaw）
该技能提供两个功能：
- 1. 查询某个地点的位置信息。
- 为多个地点渲染带有编号标记和图例的注释地图图像。
前提条件
- - Python 3.10+
- 互联网连接（Nominatim + OSM 瓦片端点）
可选环境变量：
- - OPENSTREETMAPHOST：仅覆盖默认端点中的 openstreetmap.org 主机后缀。推荐格式：openstreetmap.org。如果提供了 http:// 或 https://，则仅使用主机部分。
设置后，技能将使用：
- - 地理编码端点：https://nominatim.${OPENSTREETMAPHOST}/search
- 瓦片端点：https://tile.${OPENSTREETMAPHOST}/{z}/{x}/{y}.png
示例：
- - OPENSTREETMAPHOST=openstreetmap.org -> https://nominatim.openstreetmap.org/search
- OPENSTREETMAPHOST=https://openstreetmap.org -> https://tile.openstreetmap.org/{z}/{x}/{y}.png
安装
bash
pip install -r requirements.txt
功能 1：查询位置信息
bash
python tools/openstreet_skill.py locate --query 上海外滩 --limit 1
输出为 JSON 格式，包含 display_name、lat、lon 和类型元数据。
功能 2：渲染注释地图
输入 JSON 文件格式（数组）：
json
[
{name: 点 A, lat: 31.2304, lon: 121.4737},
{name: 点 B, query: 上海外滩}
]
渲染命令：
bash
python tools/openstreet_skill.py render \
--points-file examples/points.json \
--output output/annotated_map.png \
--width 1600 \
--height 800
使用 base64 JSON 输入的渲染命令：
bash
python tools/openstreet_skill.py render \
--points-base64 W3sibmFtZSI6IlBvaW50IEEiLCJsYXQiOjMxLjIzMDQsImxvbiI6MTIxLjQ3Mzd9LHsibmFtZSI6IlBvaW50IEIiLCJxdWVyeSI6IlRoZSBCdW5kIFNoYW5naGFpIn1d \
--output output/annotated_map.png
可选：渲染命令返回 base64 编码的图像（不写入文件）：
bash
python tools/openstreet_skill.py render \
--points-base64 ... \
--base64
可选：渲染命令写入文件并返回 base64：
bash
python tools/openstreet_skill.py render \
--points-base64 ... \
--output output/annotated_map.png \
--base64
render 输入/输出选项：
- - --points-file / --points-base64：点来源（互斥，必须提供一个）。
- --output：将图像保存到路径。这是默认且推荐的输出模式。
- --base64：在 JSON 标准输出中的 image_base64 下包含 base64 编码的 PNG。仅在调用方无法直接访问输出文件时使用。
- 必须提供 --output 或 --base64 中的至少一个。
推荐：默认使用 --output 进行文件输出。
除非无法通过文件传递，否则不要使用 --base64，因为 base64 图像负载会消耗大量令牌。
bash
python tools/openstreet_skill.py render \
--points-file examples/points.json \
--output output/annotated_map.png
行为：
- - 选择合适的缩放级别以容纳所有点。
- 下载 OSM 瓦片并将其拼接成一张地图图像。
- 在每个地点上绘制编号标记。
- 在地图下方附加一个三列图例，显示索引和地点名称。
- 如果指定了 --output 路径，则保存最终图像。
JSON 输出结构：
json
{
zoom: 14,
size: { width: 1200, height: 880 },
places: [
{ index: 1, name: 点 A, lat: 31.2304, lon: 121.4737 }
],
output: output/annotated_map.png
}
- - output：仅在提供 --output 时存在。
- image_base64：仅在设置 --base64 时存在。PNG 图像编码为标准 base64。在正常流程中避免使用，因为它会显著增加令牌使用量。
OpenClaw 集成说明
- - 将这两个 CLI 操作作为可调用工具暴露给 OpenClaw：
- locate：映射到 python tools/openstreet_skill.py locate ...
- render：映射到 python tools/openstreet_skill.py render ...
- - 对于 render，默认使用 --output 文件交付而不是 --base64，以保持响应较小。
- 将 JSON 标准输出返回给调用方，并将非零退出码视为失败。
- 遵守 OSM 使用政策，不发送高频率请求。
