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

Install the Tlon plugin.
Gather your ship URL and login code.
Configure channels.tlon.
Restart the gateway.
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

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)

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.

Overview

Messaging platforms

Configuration

Tlon

Tlon (plugin)

Plugin required

Setup

Private/LAN ships

Group channels

Access control

Owner and approval system

Auto-accept settings

Delivery targets (CLI/cron)

Bundled skill

Capabilities

Troubleshooting

Configuration reference

Notes

​Tlon (plugin)

​Plugin required

​Setup

​Private/LAN ships

​Group channels

​Access control

​Owner and approval system

​Auto-accept settings

​Delivery targets (CLI/cron)

​Bundled skill

​Capabilities

​Troubleshooting

​Configuration reference

​Notes

Tlon (plugin)

Plugin required

Setup

Private/LAN ships

Group channels

Access control

Owner and approval system

Auto-accept settings

Delivery targets (CLI/cron)

Bundled skill

Capabilities

Troubleshooting

Configuration reference

Notes