docs/channels/tlon.md
Tlon is a decentralized messenger built on Urbit. OpenClaw connects to your Urbit ship and can respond to DMs and group chat messages. Group replies require an @ mention by default and can be further restricted via allowlists.
Status: bundled plugin. DMs, group mentions, thread replies, rich text formatting, and image uploads are supported. Reactions and polls are not yet supported.
Tlon ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.
If you are on an older build or a custom install that excludes Tlon, install a current npm package:
Install via CLI (npm registry):
openclaw plugins install @openclaw/tlon
Use the bare package to follow the current official release tag. Pin an exact version only when you need a reproducible install.
Local checkout (when running from a git repo):
openclaw plugins install ./path/to/local/tlon-plugin
Details: Plugins
channels.tlon.Minimal config (single account):
{
channels: {
tlon: {
enabled: true,
ship: "~sampel-palnet",
url: "https://your-ship-host",
code: "lidlut-tabwed-pillex-ridrup",
ownerShip: "~your-main-ship", // recommended: your ship, always allowed
},
},
}
By default, OpenClaw blocks private/internal hostnames and IP ranges for SSRF protection. If your ship is running on a private network (localhost, LAN IP, or internal hostname), you must explicitly opt in:
{
channels: {
tlon: {
url: "http://localhost:8080",
allowPrivateNetwork: true,
},
},
}
This applies to URLs like:
http://localhost:8080http://192.168.x.x:8080http://my-ship.local:8080⚠️ Only enable this if you trust your local network. This setting disables SSRF protections for requests to your ship URL.
Auto-discovery is enabled by default. You can also pin channels manually:
{
channels: {
tlon: {
groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
},
},
}
Disable auto-discovery:
{
channels: {
tlon: {
autoDiscoverChannels: false,
},
},
}
DM allowlist (empty = no DMs allowed, use ownerShip for approval flow):
{
channels: {
tlon: {
dmAllowlist: ["~zod", "~nec"],
},
},
}
Group authorization (restricted by default):
{
channels: {
tlon: {
defaultAuthorizedShips: ["~zod"],
authorization: {
channelRules: {
"chat/~host-ship/general": {
mode: "restricted",
allowedShips: ["~zod", "~nec"],
},
"chat/~host-ship/announcements": {
mode: "open",
},
},
},
},
},
}
Set an owner ship to receive approval requests when unauthorized users try to interact:
{
channels: {
tlon: {
ownerShip: "~your-main-ship",
},
},
}
The owner ship is automatically authorized everywhere — DM invites are auto-accepted and
channel messages are always allowed. You don't need to add the owner to dmAllowlist or
defaultAuthorizedShips.
When set, the owner receives DM notifications for:
Auto-accept DM invites (for ships in dmAllowlist):
{
channels: {
tlon: {
autoAcceptDmInvites: true,
},
},
}
Auto-accept group invites from trusted ships:
{
channels: {
tlon: {
autoAcceptGroupInvites: true,
groupInviteAllowlist: ["~zod"],
},
},
}
autoAcceptGroupInvites fails closed when groupInviteAllowlist is empty. Set the
allowlist to the ships whose group invites should be accepted automatically.
Use these with openclaw message send or cron delivery:
~sampel-palnet or dm/~sampel-palnetchat/~host-ship/channel or group:~host-ship/channelThe Tlon plugin includes a bundled skill (@tloncorp/tlon-skill)
that provides CLI access to Tlon operations:
The skill is automatically available when the plugin is installed.
| Feature | Status |
|---|---|
| Direct messages | ✅ Supported |
| Groups/channels | ✅ Supported (mention-gated by default) |
| Threads | ✅ Supported (auto-replies in thread) |
| Rich text | ✅ Markdown converted to Tlon format |
| Images | ✅ Uploaded to Tlon storage |
| Reactions | ✅ Via bundled skill |
| Polls | ❌ Not yet supported |
| Native commands | ✅ Supported (owner-only by default) |
Run this ladder first:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
Common failures:
dmAllowlist and no ownerShip configured for approval flow.allowPrivateNetwork for local ships.Full configuration: Configuration
Provider options:
channels.tlon.enabled: enable/disable channel startup.channels.tlon.ship: bot's Urbit ship name (e.g. ~sampel-palnet).channels.tlon.url: ship URL (e.g. https://sampel-palnet.tlon.network).channels.tlon.code: ship login code.channels.tlon.allowPrivateNetwork: allow localhost/LAN URLs (SSRF bypass).channels.tlon.ownerShip: owner ship for approval system (always authorized).channels.tlon.dmAllowlist: ships allowed to DM (empty = none).channels.tlon.autoAcceptDmInvites: auto-accept DMs from allowlisted ships.channels.tlon.autoAcceptGroupInvites: auto-accept group invites from allowlisted ships.channels.tlon.groupInviteAllowlist: ships whose group invites may be auto-accepted.channels.tlon.autoDiscoverChannels: auto-discover group channels (default: true).channels.tlon.groupChannels: manually pinned channel nests.channels.tlon.defaultAuthorizedShips: ships authorized for all channels.channels.tlon.authorization.channelRules: per-channel auth rules.channels.tlon.showModelSignature: append model name to messages.~your-bot-ship) to respond.