AMap GUI — 地图容器 CLI 命令行参数模式

通过命令行实时操控运行在 Electron 容器中的高德地图 JSAPI 2.0 实例。

前置条件

读取并导出 API Key（优先执行）

在任何操作前，必须先确保 AMAP_KEY 已在当前 shell 环境中生效。
OpenClaw 的 skill env 注入不一定对 agent 的 exec 环境生效，因此需要主动读取配置并 export。

执行以下命令，从 OpenClaw 配置中读取 Key 并导出到当前环境：

CODEBLOCK0

判断逻辑：

• - AMAP_KEY 读取成功且非空 → 继续后续步骤
• INLINECODE2 仍为空 → 提示用户在 OpenClaw WebGUI 设置页面配置 AMAP_KEY（申请地址：https://lbs.amap.com），配置完成后重试
• INLINECODE4 为空 → 不阻断流程，但新版 Key 可能需要它，建议一并配置
• 两个变量 export 后全局生效，所有后续 amap-gui 命令无需再加 AMAP_KEY=xxx 前缀

安装 amap-gui

首先确认 amap-gui CLI 是否已安装，若未安装则执行安装：

CODEBLOCK1

如果 amap-gui --version 执行失败（命令不存在），必须先执行 npm install -g @amap-lbs/amap-gui 安装后再继续。

必须先配置高德地图 API Key（两个）

INLINECODE10 需要高德地图开放平台的 Key 才能加载地图。支持两种配置方式，任选其一。

环境变量	是否必须	说明
INLINECODE11	必须	Web JS API Key
INLINECODE12

推荐设置 | JS API 安全密钥（部分账号类型必须） |

方式一：通过 OpenClaw WebGUI 页面配置（推荐）

在 OpenClaw 的 WebGUI 设置页面中，直接填写以下环境变量：

• - AMAP_KEY — 填入你的高德 Web JS API Key
• INLINECODE14 — 填入对应的安全密钥（可选但推荐）

配置后无需手动执行 export，OpenClaw 会自动将其注入到运行环境中。

方式二：通过终端手动配置

CODEBLOCK2

判断逻辑：

• - AMAP_KEY 已设置（任意方式）→ 可继续后续步骤
• INLINECODE17 未设置 → 必须先让用户配置，否则 GUI 启动后地图无法加载，显示错误
• INLINECODE18 未设置 → 默认为空字符串（老版 Key 可正常使用，新版 Key 需要设置）

若用户尚未申请 Key，引导其前往 lbs.amap.com 创建「Web端(JS API)」类型的 Key，同时在控制台获取对应的安全密钥。

前置判断：容器未启动则先主动启动

在执行任何地图操作之前，必须先做前置判断：

1. 1. 确认 AMAP_KEY 已设置（见上方）

1. 2. 检查状态：

CODEBLOCK3

1. 3. 判断逻辑：

- 若返回 status: "not_running" → 容器未运行 - 若返回 status: "running" 且 mapReady: true → 可以执行命令

1. 4. 若未运行，主动执行启动（不要依赖自动启动，显式执行）：

CODEBLOCK4

1. 5. 等待就绪：start 命令会阻塞直到地图就绪（约 3-8 秒），返回 mapReady: true 后再继续后续命令。

注意：不采用自动/后台静默启动方式，由 Agent 在检测到未运行时显式执行 amap-gui start。

命令格式

CODEBLOCK5

生命周期命令（无需参数）：

CODEBLOCK6

status 返回示例（容器运行中）：

CODEBLOCK7

status 返回示例（容器未运行）：

CODEBLOCK8

start 返回示例：

CODEBLOCK9

stop 返回示例：

CODEBLOCK10

交互感知命令（无需参数）：

CODEBLOCK11

地图操作命令（通过命令行参数传参，返回 CommandResult<T> JSON）：

CODEBLOCK12

结果输出原则：从容器准确获取 JSON 状态/结果，解析后以文字告知用户，不需要截图。

命令	解析字段	告知用户
INLINECODE26	center, zoom, style	当前中心、缩放、样式
INLINECODE27

pois | 名称、地址、距离、类型 |
| route | summary.distance, summary.time, summary.steps | 里程、耗时、路线步骤 |

核心命令

地图状态控制 — mapState

CODEBLOCK13

参数：

参数	类型	必填	说明
INLINECODE29	INLINECODE30 \	INLINECODE31	No	操作类型，默认 INLINECODE32
INLINECODE33

lng,lat | No | 中心点坐标（经度,纬度） |
| --zoom | 3-20 | No | 缩放级别 |
| --rotation | 0-360 | No | 旋转角度 |
| --pitch | 0-83 | No | 俯仰角度 |
| --style | string | No | 地图样式 |

可用样式：normal dark light whitesmoke fresh grey graffiti macaron blue darkblue INLINECODE53

注意：命令行模式下 --center 仅接受 lng,lat 坐标格式，不支持地名。如需使用地名，请使用 --json 模式。

mapState get 返回示例：

CODEBLOCK14

返回字段	类型	说明
INLINECODE57	INLINECODE58	当前地图中心点坐标
INLINECODE59

number | 当前缩放级别 |
| data.rotation | number | 当前旋转角度 |
| data.pitch | number | 当前俯仰角度 |
| data.style | string | 当前地图样式名称 |
| data.bounds | object | 当前可视区域边界（西南角、东北角坐标） |

mapState set 返回示例：

CODEBLOCK15

设置成功后返回的是设置后的实际地图状态，可用于确认视角是否已正确应用。

路径规划 — route

CODEBLOCK16

参数：

参数	类型	必填	说明
INLINECODE69	INLINECODE70 或 INLINECODE71	Yes	起点（地名或坐标）
INLINECODE72

string | No | 起点显示名称（配合坐标使用） |
| --to | 地名 或 lng,lat | Yes | 终点（地名或坐标） |
| --to-name | string | No | 终点显示名称（配合坐标使用） |
| --type | string | Yes | 出行方式：driving walking riding transit |
| --waypoints | p1,p2,... | No | 逗号分隔的途经点（仅 driving，最多 16 个） |
| --policy | string | No | 驾车策略：fastest least_fee shortest no_highway avoid_jam |
| --strategy | string | No | 公交策略：fastest least_cost least_walk most_comfort no_subway |
| --city | string | transit 必填 | 城市名（公交模式必须指定） |

地图效果：规划完成后自动绘制路线（带描边+方向箭头），标记起点（绿色）、途经点（蓝色）、终点（红色）。

驾车路线返回示例：

CODEBLOCK17

CODEBLOCK18

返回字段	类型	说明
INLINECODE103	INLINECODE104	出行方式
INLINECODE105

object | 起点信息（名称 + 解析后的坐标） |
| data.to | object | 终点信息（名称 + 解析后的坐标） |
| data.summary.distance | number | 总距离（米） |
| data.summary.time | number | 预计耗时（秒） |
| data.summary.tolls | number | 过路费（元，仅驾车） |
| data.summary.steps[] | array | 路线步骤列表 |
| steps[].instruction | string | 该步骤的文字导航指引 |
| steps[].distance | number | 该步骤距离（米） |
| steps[].time | number | 该步骤耗时（秒） |

步行路线返回示例：

CODEBLOCK19

CODEBLOCK20

公交路线返回示例：

CODEBLOCK21

CODEBLOCK22

POI 搜索 — searchPOI

CODEBLOCK23

参数：

参数	类型	必填	说明
INLINECODE123	INLINECODE124	Yes	搜索关键词
INLINECODE125

string | No | 搜索城市 |
| --center | lng,lat | No | 周边搜索中心坐标（不传则为关键词搜索） |
| --radius | number | No | 周边搜索半径（米），默认 3000 |
| --pageSize | number | No | 每页数量，默认 10 |
| --pageIndex | number | No | 页码，默认 1 |

注意：命令行模式下 --center 仅接受 lng,lat 坐标格式，不支持地名。如需使用地名作为搜索中心，请使用 --json 模式。

地图效果：搜索结果自动标记在地图上（分类图标），点击可查看详情弹窗。

关键词搜索返回示例：

CODEBLOCK24

CODEBLOCK25

周边搜索返回示例：

CODEBLOCK26

CODEBLOCK27

返回字段	类型	说明
INLINECODE138	INLINECODE139	搜索关键词
INLINECODE140

string | 搜索城市（关键词搜索时） |
| data.center | [lng, lat] | 搜索中心坐标（周边搜索时） |
| data.radius | number | 搜索半径（周边搜索时） |
| data.total | number | 匹配结果总数 |
| data.pageSize | number | 每页数量 |
| data.pageIndex | number | 当前页码 |
| data.pois[] | array | POI 结果列表 |
| pois[].name | string | POI 名称 |
| pois[].address | string | POI 地址 |
| pois[].location | [lng, lat] | POI 坐标 |
| pois[].tel | string | 联系电话 |
| pois[].type | string | POI 类型分类 |
| pois[].distance | number | 距搜索中心的距离（米，仅周边搜索） |
| pois[].id | string | POI 唯一标识 |

getLastEvent — 获取用户最后一次地图交互事件

CODEBLOCK28

无需参数，直接调用。返回用户在 GUI 上最后一次交互的事件信息。

事件类型：

INLINECODE168	触发方式	返回字段
INLINECODE169	点击地图空白处	INLINECODE170
INLINECODE171

点击地图上的 POI 标记 | title + address + position |
| poi_select | 在左侧搜索结果列表中选中 | title + address + position |

返回字段说明：

字段	说明
INLINECODE179	是否有事件记录（false 表示用户尚未操作）
INLINECODE181

事件类型（见上表）|
| lastEvent.title | POI 名称（poi_click / poi_select 时有值）|
| lastEvent.address | POI 地址（poi_click / poi_select 时有值）|
| lastEvent.position | 坐标 [lng, lat]，所有事件类型均有值 |

返回示例：

CODEBLOCK29

典型用法：用户在地图上点选某地点后，AI 通过 getLastEvent 获取位置，再衔接路线规划等操作，无需用户重复说出地名。

CODEBLOCK30

命令行参数 vs JSON 模式对比

特性	命令行参数模式	JSON 模式
地名作为坐标	INLINECODE191/--to 支持地名	INLINECODE193/center 支持地名
地名作为搜索中心

❌ --center 仅支持坐标 | ✅ center 支持地名 | | 地名作为地图中心 | ❌ --center 仅支持坐标 | ✅ center 支持地名 | | 途经点 | --waypoints p1,p2 逗号分隔 | waypoints 数组 | | 优先级 | 低 | 高（--json 会覆盖其他参数） | | 适用场景 | 简单命令、快速操作 | 复杂参数、精确控制 |

关键规则

1. 1. 前置判断 — 操作前先 amap-gui status；若未运行则显式执行 amap-gui start，确认 mapReady: true 后再继续
2. route 的 --from/--to 支持地名 — 直接传地名字符串，容器内部自动 geocode
3. mapState 和 searchPOI 的 --center 仅支持坐标 — 格式为 lng,lat，如 INLINECODE209
4. 坐标格式 — 经度,纬度（lng,lat），如 INLINECODE211
5. transit 必须传 --city — 公交模式必须指定城市
6. --waypoints 仅 driving — 途经点只有驾车模式支持，多个途经点用逗号分隔
7. 不需要 clear 命令 — 新命令自动清除上一次的路线/标记
8. --json 优先 — 当 --json 与其他参数同时使用时，--json 的值优先
9. 命令名大小写不敏感 — searchpoi、searchPOI、SearchPOI 均等效，mapstate 等同 mapState，getlastevent 等同 INLINECODE223
10. 停止容器 — 完成后用 amap-gui stop 停止

典型工作流

场景 1：用户想看某地的地图

CODEBLOCK31

场景 2：用户想从 A 到 B 怎么走

CODEBLOCK32

场景 3：用户想找附近的 XX

CODEBLOCK33

场景 4：连续操作 — 搜索后导航

CODEBLOCK34

场景 5：用户点选地图后导航

CODEBLOCK35

场景 6：完成后停止

CODEBLOCK36