OpenClaw 中文

深色模式

广告 · 本站推荐广告

位置解析 - 地理位置消息处理 ​

许多即时通讯平台支持发送 Location Message（地理位置消息）。OpenClaw 可以解析这些位置数据，让 Agent（智能体）基于用户位置提供更智能的响应。

概述 ​

当用户通过支持的渠道发送位置信息时，OpenClaw 会自动解析位置数据，并将其作为上下文传递给 Agent。Agent 可以利用这些信息提供基于位置的服务，例如附近搜索、导航建议、天气查询等。

用户发送位置
    │
    ▼
┌──────────────┐
│  渠道适配器    │  ← 解析平台特有的位置数据格式
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  位置标准化    │  ← 转换为 OpenClaw 统一格式
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Geocoding    │  ← （可选）反向地理编码，获取地址信息
│  (地理编码)    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Agent 处理   │  ← 位置数据作为上下文传递给 Agent
└──────────────┘

支持位置消息的渠道 ​

并非所有渠道都支持位置消息。以下是各渠道的支持情况：

渠道位置消息支持实时位置说明
WhatsApp✅ 完整✅ 支持支持静态位置和实时位置共享
Telegram✅ 完整✅ 支持支持静态位置和 Live Location
飞书✅ 完整❌ 不支持仅支持静态位置消息
企业微信✅ 完整❌ 不支持支持位置消息类型
钉钉⚠️ 部分❌ 不支持需通过自定义消息处理
Discord❌ 不支持❌ 不支持平台不支持原生位置消息
Slack❌ 不支持❌ 不支持平台不支持原生位置消息
Web Chat✅ 完整✅ 支持通过浏览器 Geolocation API

不支持位置消息的渠道

对于不支持原生位置消息的渠道（如 Discord、Slack），用户仍然可以通过文本描述位置（如"北京市朝阳区望京 SOHO"），Agent 可以通过 Geocoding 工具解析文本地址。

位置数据格式 ​

OpenClaw 统一格式 ​

无论来自哪个渠道，位置消息都会被转换为以下统一的 Location Object（位置对象）格式：

json
{
  "type": "location",
  "latitude": 39.9042,
  "longitude": 116.4074,
  "accuracy": 15.0,
  "altitude": 45.2,
  "heading": 180.0,
  "speed": 0.0,
  "address": {
    "formatted": "北京市东城区天安门广场",
    "country": "China",
    "countryCode": "CN",
    "province": "北京市",
    "city": "北京市",
    "district": "东城区",
    "street": "东长安街",
    "poi": "天安门广场"
  },
  "label": "天安门广场",
  "isLive": false,
  "timestamp": "2026-03-05T10:30:00Z",
  "source": {
    "channel": "telegram",
    "rawType": "location"
  }
}

字段说明 ​

字段类型必填说明
typestring✅固定值 "location"
latitudenumber✅纬度（Latitude），范围 -90 ~ 90
longitudenumber✅经度（Longitude），范围 -180 ~ 180
accuracynumber❌精度（米），GPS 定位精度
altitudenumber❌海拔高度（米）
headingnumber❌方向角（度），0-360，正北为 0
speednumber❌移动速度（米/秒）
addressobject❌解析后的地址信息（需启用 Geocoding）
labelstring❌用户在平台上标注的位置名称
isLiveboolean❌是否为实时位置共享
timestampstring✅位置数据的时间戳（ISO 8601）
sourceobject✅来源信息

各平台原始数据映射 ​

json
// WhatsApp 原始位置消息
{
  "type": "location",
  "location": {
    "latitude": 39.9042,
    "longitude": 116.4074,
    "name": "天安门广场",           // → label
    "address": "北京市东城区"       // → address.formatted
  }
}
json
// Telegram 原始位置消息
{
  "message": {
    "location": {
      "latitude": 39.9042,
      "longitude": 116.4074,
      "horizontal_accuracy": 15.0  // → accuracy
    },
    "venue": {                      // 如果是 Venue 类型
      "title": "天安门广场",        // → label
      "address": "北京市东城区"     // → address.formatted
    }
  }
}
json
// 飞书原始位置消息
{
  "msg_type": "location",
  "content": {
    "latitude": "39.9042",
    "longitude": "116.4074",
    "name": "天安门广场",          // → label
    "address": "北京市东城区天安门" // → address.formatted
  }
}

在 Agent 中使用位置数据 ​

位置上下文注入 ​

当 Agent 收到位置消息时，位置数据会自动注入到 Context（上下文）中：

yaml
agents:
  main:
    systemPrompt: |
      你是一个智能助手。

      {% if context.location %}
      用户分享了他们的位置：
      - 坐标：{{ context.location.latitude }}, {{ context.location.longitude }}
      - 地址：{{ context.location.address.formatted | default("未知") }}
      - 标注：{{ context.location.label | default("无") }}

      你可以基于这个位置提供附近的推荐、天气信息或导航建议。
      {% endif %}

位置相关工具 ​

OpenClaw 提供以下位置相关的内置工具：

yaml
agents:
  main:
    tools:
      - name: nearby_search
        description: "搜索用户附近的地点"
        config:
          provider: "amap"        # 高德地图 / google / mapbox
          apiKey: "${AMAP_API_KEY}"
          defaultRadius: 1000     # 默认搜索半径（米）

      - name: weather_by_location
        description: "查询指定位置的天气"
        config:
          provider: "openweather"
          apiKey: "${WEATHER_API_KEY}"

      - name: route_planning
        description: "规划两点之间的路线"
        config:
          provider: "amap"
          apiKey: "${AMAP_API_KEY}"

交互示例 ​

用户: [发送位置：北京市朝阳区望京 SOHO]

Agent: 收到你的位置！你在望京 SOHO 附近。我可以帮你：

1. 🍽️ 搜索附近的餐厅
2. ☕ 查找附近的咖啡店
3. 🌤️ 查看当前天气
4. 🚗 规划到某地的路线

请告诉我你需要什么帮助？

用户: 帮我找附近的咖啡店

Agent: 为你找到望京 SOHO 附近 500 米内的咖啡店：

1. ☕ Manner Coffee — 望京 SOHO T1 一层，约 50 米
2. ☕ 星巴克臻选 — 望京 SOHO T2 一层，约 120 米
3. ☕ Peet's Coffee — 望京 SOHO T3 一层，约 200 米

需要查看详细信息或导航到某家店吗？

Geocoding（地理编码）集成 ​

Geocoding（地理编码）将坐标转换为可读地址（反向地理编码），或将文本地址转换为坐标（正向地理编码）。

配置 Geocoding 服务 ​

yaml
geocoding:
  enabled: true
  provider: amap
  apiKey: "${AMAP_API_KEY}"
  language: "zh_CN"
  # 自动反向编码：收到位置消息时自动解析地址
  autoReverse: true
  # 缓存设置
  cache:
    enabled: true
    ttl: "24h"          # 缓存 24 小时
    maxSize: 10000      # 最多缓存 10000 条
yaml
geocoding:
  enabled: true
  provider: google
  apiKey: "${GOOGLE_MAPS_API_KEY}"
  language: "zh-CN"
  autoReverse: true
  cache:
    enabled: true
    ttl: "24h"
yaml
geocoding:
  enabled: true
  provider: mapbox
  accessToken: "${MAPBOX_ACCESS_TOKEN}"
  language: "zh"
  autoReverse: true

Geocoding 使用示例 ​

bash
# 手动测试反向地理编码
openclaw geocode reverse --lat 39.9042 --lng 116.4074

# 输出示例：
# Formatted: 北京市东城区天安门广场
# Country: China (CN)
# Province: 北京市
# City: 北京市
# District: 东城区
# POI: 天安门广场

# 正向地理编码（文本地址 → 坐标）
openclaw geocode forward "上海市浦东新区陆家嘴"

# 输出示例：
# Latitude: 31.2397
# Longitude: 121.4998
# Formatted: 上海市浦东新区陆家嘴街道

实时位置（Live Location） ​

部分平台支持 Live Location（实时位置共享），用户可以持续分享其位置更新。

配置 ​

yaml
location:
  liveLocation:
    enabled: true
    # 更新间隔（秒）— 控制位置更新的最小间隔
    minUpdateInterval: 10
    # 最长持续时间
    maxDuration: "1h"
    # 收到实时位置更新时的行为
    onUpdate: "context"       # context（更新上下文）/ notify（通知 Agent）/ ignore（忽略）

性能注意

实时位置更新可能非常频繁（每秒多次）。建议设置合理的 minUpdateInterval 以避免对 Agent 造成过大的上下文更新压力。

实时位置事件 ​

json
{
  "type": "location_update",
  "location": {
    "latitude": 39.9042,
    "longitude": 116.4074,
    "accuracy": 10.0,
    "speed": 1.5,
    "heading": 45.0
  },
  "isLive": true,
  "updateSequence": 15,
  "startedAt": "2026-03-05T10:00:00Z",
  "expiresAt": "2026-03-05T11:00:00Z"
}

Privacy（隐私保护） ​

位置数据是高度敏感的个人信息，必须谨慎处理。

隐私配置 ​

yaml
location:
  privacy:
    # 位置数据保留策略
    retention:
      enabled: true
      maxAge: "24h"           # 位置数据最多保留 24 小时
      onExpire: "delete"      # 过期后删除

    # 精度模糊化
    fuzzing:
      enabled: false          # 是否启用位置模糊化
      radiusMeters: 500       # 模糊化半径（米）

    # 日志脱敏
    logging:
      maskCoordinates: true   # 日志中隐藏精确坐标
      logLevel: "info"        # 位置相关日志级别

    # 用户通知
    consent:
      enabled: true           # 首次收到位置时提示用户
      message: "我收到了你的位置信息。该信息仅用于本次对话，不会被永久存储。"

隐私最佳实践 ​

重要提醒

处理位置数据时必须遵守相关法律法规：

  • 明确告知用户位置数据的用途
  • 不要将位置数据用于未经授权的用途
  • 设置合理的数据保留期限
  • 日志中不要记录精确坐标
  • 传输过程中确保加密（HTTPS）
  1. 最小化收集：只在业务需要时处理位置数据
  2. 及时删除：设置合理的 retention.maxAge，用完即删
  3. 精度适当：如果不需要精确位置，启用 fuzzing 模糊化
  4. 日志脱敏：启用 logging.maskCoordinates，避免在日志中泄露位置
  5. 用户知情：启用 consent，让用户了解位置数据的处理方式

调试位置功能 ​

bash
# 测试位置解析
openclaw location test --lat 31.2304 --lng 121.4737

# 输出示例：
# Location parsed successfully
# Geocoded address: 上海市黄浦区南京东路
# Provider: amap
# Cache: miss (first query)

# 查看位置相关日志
openclaw logs --filter "location" --tail 20

# 模拟位置消息（开发测试用）
openclaw location simulate --channel telegram --user user_test \
  --lat 39.9042 --lng 116.4074 --label "天安门广场"

最佳实践 ​

  1. 选择合适的 Geocoding 服务：国内用户推荐高德地图，海外用户推荐 Google Maps
  2. 启用缓存：Geocoding API 调用有成本，启用缓存减少重复请求
  3. 处理缺失数据：不是所有位置消息都包含完整信息，代码中做好空值处理
  4. 尊重用户隐私：位置是敏感数据，务必遵守隐私保护原则
  5. 设置超时：Geocoding API 调用可能较慢，设置合理的超时避免阻塞

🇨🇳 中国用户须知

推荐使用高德地图 API： 高德地图在国内的地理编码精度和覆盖度最佳，且访问速度快。前往 高德开放平台 注册获取 API Key，免费额度每日 30 万次调用。

坐标系注意事项： 中国境内的地理坐标需要注意坐标系的差异：

  • WGS84：GPS 原始坐标，国际标准（WhatsApp、Telegram 使用此坐标系）
  • GCJ-02：国测局坐标，又称「火星坐标」（高德地图、腾讯地图使用）
  • BD-09：百度坐标系（仅百度地图使用）

OpenClaw 内置坐标转换功能，可在配置中指定：

yaml
geocoding:
  provider: amap
  coordinateSystem: gcj02     # 自动将 WGS84 转换为 GCJ-02
  autoConvert: true           # 启用自动坐标转换

合规要求： 根据《中华人民共和国测绘法》，在中国境内使用地图服务和地理编码功能，必须使用经审批的地图服务商（如高德、百度、腾讯）。请勿使用未经审批的境外地图服务直接展示中国地图。

基于MIT协议开源 | 内容翻译自 官方文档，同步更新

Copyright © 2026 OpenClaw 中文社区