|
…
|
||
|---|---|---|
| .. | ||
| src | ||
| index.ts | ||
| openclaw.plugin.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
Geolocation plugin
Resolves a client IP address to a coarse city, so surfaces that already show a connecting address can show a place instead of only a number.
How it works
The plugin exposes one authenticated route:
GET /plugins/geolocation/lookup?ip=<address>
It answers { found, city?, region?, country?, countryCode?, attribution }. A
database that is missing or still downloading returns 503, never
found: false — "we cannot answer" and "this address has no place" are
different answers and callers must be able to tell them apart.
The database is downloaded on first lookup into
<state-dir>/geolocation/, kept until it ages past refreshDays, and reused
from disk after that. A failed refresh serves the cached copy rather than taking
lookups down. A body that does not parse as an MMDB is discarded without
replacing a working database.
Data source and license
The default source is DB-IP City Lite, licensed CC BY 4.0. That license requires attribution, so every answer carries the credit and the Control UI renders it next to the value. The database is downloaded at runtime and never redistributed by OpenClaw.
All plugin code is MIT, as is the maxmind reader it uses. No free city-level
IP database is MIT-licensed; the obligation lives with the data, not the code.
To use a different source, set databaseUrl and set attributionText /
attributionUrl to whatever that source requires. {yyyy} and {mm} expand to
a release month, and the previous month is tried when the current build is not
published yet.
Accuracy
City-level IP geolocation is right roughly 55-80% of the time and is worst exactly where it matters most: mobile carriers, VPNs, and corporate egress all resolve to the operator's exit point rather than the person. Treat the answer as a hint. The client-reported time zone shown beside it is often the better signal, because it survives proxies and CGNAT ranges where the address does not.