Skip to main content

​
Tlon (plugin)

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: supported via plugin. DMs, group mentions, thread replies, rich text formatting, and image uploads are supported. Reactions and polls are not yet supported.

​
Plugin required

Tlon ships as a plugin and is not bundled with the core install. Install via CLI (npm registry): 
openclaw plugins install @openclaw/tlon
Local checkout (when running from a git repo): 
openclaw plugins install ./extensions/tlon
Details: Plugins

​
Setup

  1. Install the Tlon plugin.
  2. Gather your ship URL and login code.
  3. Configure channels.tlon.
  4. Restart the gateway.
  5. DM the bot or mention it in a group channel.
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
    },
  },
}

​
Private/LAN ships

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:8080
  • http://192.168.x.x:8080
  • http://my-ship.local:8080
⚠️ Only enable this if you trust your local network. This setting disables SSRF protections for requests to your ship URL.

​
Group channels

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,
    },
  },
}

​
Access control

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",
          },
        },
      },
    },
  },
}

​
Owner and approval system

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:
  • DM requests from ships not in the allowlist
  • Mentions in channels without authorization
  • Group invite requests

​
Auto-accept settings

Auto-accept DM invites (for ships in dmAllowlist): 
{
  channels: {
    tlon: {
      autoAcceptDmInvites: true,
    },
  },
}
Auto-accept group invites: 
{
  channels: {
    tlon: {
      autoAcceptGroupInvites: true,
    },
  },
}

​
Delivery targets (CLI/cron)

Use these with openclaw message send or cron delivery:
  • DM: ~sampel-palnet or dm/~sampel-palnet
  • Group: chat/~host-ship/channel or group:~host-ship/channel

​
Bundled skill

The Tlon plugin includes a bundled skill (@tloncorp/tlon-skill) that provides CLI access to Tlon operations:
  • Contacts: get/update profiles, list contacts
  • Channels: list, create, post messages, fetch history
  • Groups: list, create, manage members
  • DMs: send messages, react to messages
  • Reactions: add/remove emoji reactions to posts and DMs
  • Settings: manage plugin permissions via slash commands
The skill is automatically available when the plugin is installed.

​
Capabilities

FeatureStatus
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)

​
Troubleshooting

Run this ladder first: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
Common failures:
  • DMs ignored: sender not in dmAllowlist and no ownerShip configured for approval flow.
  • Group messages ignored: channel not discovered or sender not authorized.
  • Connection errors: check ship URL is reachable; enable allowPrivateNetwork for local ships.
  • Auth errors: verify login code is current (codes rotate).

​
Configuration reference

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 all group invites.
  • 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.

​
Notes

  • Group replies require a mention (e.g. ~your-bot-ship) to respond.
  • Thread replies: if the inbound message is in a thread, OpenClaw replies in-thread.
  • Rich text: Markdown formatting (bold, italic, code, headers, lists) is converted to Tlon’s native format.
  • Images: URLs are uploaded to Tlon storage and embedded as image blocks.