本页内容
本页内容
插件指南
地理定位插件
捆绑的 geolocation 插件将连接客户端的 IP 地址变成粗略的城市。它随 OpenClaw 一起提供，在首次使用时下载其数据库，并完全从本地副本进行应答，因此查找永远不会将地址发送给第三方。
它只拥有一件事：地点地址。它不决定查找哪些地址，不存储结果，也不是授权输入。 Control UI 使用它来标记个人 Activity 卡上的设备。当代理请求 include: ["location"] 时，核心 presence 工具使用相同的查找所有者。
快速开始
默认情况下，该插件已捆绑并处于活动状态。要查看其工作原理，请打开 Activity，选择一个人，然后查看他们的设备行。远程客户端显示其地址和解析的城市：
全新安装后的第一个视图在数据库下载时不显示任何城市；一旦准备好，该行就会自行填充，无需重新加载。直接检查插件：
使用实际可路由的地址。数据库中不存在诸如 203.0.113.0/24 之类的保留范围，并回答 {"found": false}：
第一个呼叫还会下载数据库，因此预计最多需要一分钟，而后续呼叫将从本地副本应答。
网关查找
通过 operator.read 进行身份验证的呼叫者可以将 geolocation.lookup 与 {"ips":["8.8.8.8"]} 一起使用。请求最多接受 200 个 IPv4 或 IPv6 地址，并为 results 中的每个不同地址返回一个条目。每个条目包括 ip、status（found、not-found 或 unavailable）、可用位置字段和 attribution。
presence 工具仅在请求位置时调用此方法。禁用插件或数据库中断会留下可用的状态和网络详细信息；位置被报告为不可用。查找使用记录的连接 IP，从不请求 GPS，并且不会将 IP 发送到外部服务。客户端时区仍然是单独报告的事实。
为什么有些客户端从不显示位置
仅当网关记录了该客户端的可用公共地址时，位置才会出现，但通常不会：
- 对于环回客户端，Connect 处理完全忽略
ip，因此通过 SSH 隧道或本地端口转发到达网关的任何内容都没有需要解析的地址。 - Tailscale 客户端到达
100.64/10运营商级 NAT 地址，LAN 客户端到达专用地址。两者都会被记录和显示，但没有地理定位数据库包含它们，因此插件会回答这些范围的found: false，而根本不加载数据库。因此，仅 tailnet 或 LAN-only 网关永远不会下载。 - 移动运营商、VPN 和企业出口解析为运营商的出口点，而不是个人。答案肯定是错误的而不是缺失的。
这就是设备行还携带客户端报告的时区的原因。无论浏览器如何到达网关，浏览器都知道自己的区域，因此 Europe/Vienna 在地址不再提供信息的地方继续准确地工作。将城市视为提示，将区域视为更可靠的信号。请参阅 Presence 了解这两个字段的生成方式。
配置
每个选项都是可选的。默认设置是工作设置。
| 选项 | 默认值 | 用途 |
|---|---|---|
databaseUrl |
每月 DB-IP City Lite 构建 | MMDB 来源。 {yyyy} 和 {mm} 扩展到发布月份。 |
attributionText |
IP Geolocation by DB-IP |
每个结果旁边都会显示信用。 |
attributionUrl |
https://db-ip.com |
信用的链接目标。 |
refreshDays |
30 |
再次下载之前缓存的数据库可能会变得多么陈旧。 |
每月构建会在该月的几天后出现，因此插件会尝试当前月份并回退到上个月。不需要月份替换的源按书面方式获取。
使用不同的数据库
将 databaseUrl 与两个属性字段一起设置。信用属于您指向的任何数据集，因此在不更改信用的情况下更改源会错误地分配数据：
任何 MaxMind 格式的城市数据库都可以使用，包括自托管镜像或您已获得许可的商业版本。缓存文件以源 URL 命名，因此切换源无法在新提供商的信用下提供先前提供商的数据。
数据许可证
默认数据库为 DB-IP City Lite，授权 CC BY 4.0。该许可证需要归属，这就是为什么信用是每个响应的一部分，并且呈现在值旁边而不是隐藏在设置中。
OpenClaw 在运行时下载此数据库并且从不重新分发它，因此许可证附加到您的部署对数据的使用，而不是附加到 OpenClaw 本身。插件代码及其使用的 maxmind 阅读器是 MIT。没有免费的市级IP数据库获得MIT-许可；该义务与数据同在。
预计城市级准确度在 55-80% 范围内，对于上述移动、VPN 和 CGNAT 情况，情况更糟。
数据库是如何管理的
下载是惰性的并且是需求驱动的。它发生在第一次授权查找 public 地址时，例如打开某人的活动视图或询问客服人员是否存在位置详细信息。无人检查的网关（或者仅通过环回、隧道、LAN 或尾网到达的网关）永远不会下载任何内容。
在第一次限定查找时，插件将数据库提取到 <state-dir>/geolocation/ 中，在发布之前对其进行解析，并保留它直到其老化时间超过 refreshDays。
有四种行为值得了解，因为它们决定了您在失败期间会看到什么：
- 响应是根据压缩上限读取的，并根据磁盘上限膨胀的，两者在读取时都会强制执行。被替换的源无法分配无限的主体，压缩炸弹也无法膨胀超过限制。
- 未解析为 MMDB 的主体将被丢弃，而不替换工作数据库。速率限制页面或截断的下载无法破坏一分钟前正在运行的网关。
- A 下载失败或无效数据库提供缓存副本并记录警告。如果无法将有效下载保存到磁盘，则查找会从内存中使用它并记录缓存写入失败。
- 一个网关中的并发首次查找共享一个下载。单独的网关独立地暂存其下载，并在替换缓存之前关闭完整的文件，因此另一个网关永远不会读取部分写入的下载。
故障排查
在任何设备行上都没有位置。 要么网关没有记录地址——仅显示平台和时区的行没有 ip，这对于环回和隧道客户端来说是预期的——要么存在的每个地址都是私有或运营商级的 NAT，插件在不咨询数据库的情况下回答。在这两种情况下都不会损坏任何东西。
每次查找都会返回 503. 数据库不可用 — 仍在下载，或者每个候选 URL 均失败。检查网关日志中是否有 geolocation: downloaded 或命名它尝试的每个 URL 的 geolocation database download failed 行。没有出站网络访问权限的网关无法获取数据库；将 databaseUrl 指向内部镜子。
A found: false 答案。 数据库没有该地址的条目。这是数据限制，而不是失败。请注意，503 和 found: false 是故意不同的：一个意味着插件无法应答，另一个意味着数据库没有该地址的位置。
A 城市错误。 确认该地址是本人的，而不是 VPN 或承运人出口。如果确实有误，DB-IP接受更正，或者将databaseUrl指向覆盖范围更好的商业数据库。