Tlon - OpenClaw

Tlon is a decentralized messenger built on Urbit. OpenClaw connects to your Urbit ship and responds to DMs and group chat messages. Group replies require an @ mention by default, with authorization rules and an owner-approval flow layered on top. Status: bundled plugin. DMs, group mentions, threads, rich text, image upload/download, and an owner approval system are supported. Reactions and polls are not.

Bundled plugin

Tlon ships bundled in current OpenClaw releases; packaged builds do not need a separate install. On an older build or custom install that excludes it, install from npm:

openclaw plugins install @openclaw/tlon

Use the bare package name to track the current release tag. Pin a version (@openclaw/tlon@x.y.z) only for reproducible installs. From a local checkout:

openclaw plugins install ./path/to/local/tlon-plugin

Details: Plugins

Setup

openclaw channels add --channel tlon --ship ~sampel-palnet --url https://your-ship-host --code lidlut-tabwed-pillex-ridrup

Or edit config directly:

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

Restart the gateway after editing config directly. Then DM the bot or @ mention it in a group channel.

Private/LAN ships

OpenClaw blocks private/internal hostnames and IP ranges for SSRF protection by default. If your ship runs on a private network (localhost, LAN IP, internal hostname), opt in explicitly:

{
  channels: {
    tlon: {
      url: "http://localhost:8080",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
    },
  },
}

Applies to targets like http://localhost:8080, http://192.168.x.x:8080, and http://my-ship.local:8080. Only enable this for a ship URL you trust; it disables SSRF protection for that account’s HTTP requests.

channels.tlon.allowPrivateNetwork (flat key) is retired. openclaw doctor --fix moves it to channels.tlon.network.dangerouslyAllowPrivateNetwork automatically.

Group channels

Pin channels manually, or turn on auto-discovery:

{
  channels: {
    tlon: {
      groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
      autoDiscoverChannels: true,
    },
  },
}

autoDiscoverChannels defaults to false when unset in config; the setup wizard defaults the prompt to yes and writes true explicitly. With it on, OpenClaw scries joined groups on startup, watches new channels as group invites are accepted, and rechecks every 2 minutes.

Access control

DM allowlist (empty = no DMs allowed unless the sender is ownerShip):

{
  channels: {
    tlon: {
      dmAllowlist: ["~zod", "~nec"],
    },
  },
}

Group authorization defaults to restricted per channel. Set defaultAuthorizedShips for a baseline, and override per channel nest:

{
  channels: {
    tlon: {
      defaultAuthorizedShips: ["~zod"],
      authorization: {
        channelRules: {
          "chat/~host-ship/general": {
            mode: "restricted",
            allowedShips: ["~zod", "~nec"],
          },
          "chat/~host-ship/announcements": {
            mode: "open",
          },
        },
      },
    },
  },
}

Once the bot has replied inside a thread, it keeps responding to later messages in that thread without requiring another mention.

Owner and approval system

{
  channels: {
    tlon: {
      ownerShip: "~your-main-ship",
    },
  },
}

The owner ship is authorized everywhere: DM invites are always auto-accepted, group invites are always auto-accepted, and channel messages always pass authorization. The owner does not need to be in dmAllowlist, defaultAuthorizedShips, or groupInviteAllowlist. When ownerShip is set, unauthorized requests do not just get dropped — they queue a pending approval and DM the owner:

DM requests from ships not on dmAllowlist
Mentions in channels where the sender fails authorization
Group invites from ships not on groupInviteAllowlist (when auto-accept is off, or on but the inviter is not allowlisted)

The owner replies in DM to act on a request:

Owner reply	Effect
`approve` / `deny` / `block`	Acts on the most recent pending approval
`approve <id>` / `deny <id>`	Acts on a specific approval by id
`block`	Also blocks the ship natively so it cannot reconnect
`unblock ~ship`	Reverses a native block
`blocked`	Lists currently blocked ships
`pending`	Lists pending approval requests

Without ownerShip configured, unauthorized DMs and channel mentions are just dropped and logged; there is no approval prompt.

Auto-accept settings

Auto-accept DM invites from ships already on dmAllowlist (the owner is always auto-accepted regardless of this flag):

{
  channels: {
    tlon: {
      autoAcceptDmInvites: true,
    },
  },
}

Auto-accept group invites from an allowlist (fails closed: with autoAcceptGroupInvites: true and an empty groupInviteAllowlist, no non-owner invite is accepted):

{
  channels: {
    tlon: {
      autoAcceptGroupInvites: true,
      groupInviteAllowlist: ["~zod"],
    },
  },
}

Hot-reload via Urbit settings store

Most of the settings above (dmAllowlist, groupInviteAllowlist, groupChannels, defaultAuthorizedShips, autoDiscoverChannels, autoAcceptDmInvites, autoAcceptGroupInvites, ownerShip, showModelSignature) are mirrored into the ship’s %settings agent (desk moltbot, bucket tlon) on first run and then read live from there, so changes made via a Landscape client or the bundled skill’s settings commands apply without a gateway restart. channelRules and pending approvals are also persisted there as JSON. File config stays the source of truth for values never written to the settings store.

Delivery targets (CLI/cron)

Use 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 plugin bundles @tloncorp/tlon-skill, a CLI for direct Urbit operations, available automatically once the plugin is installed:

Activity: mentions, replies, unreads
Channels: list, create, rename
Contacts: list/get/update profiles
Groups: create, join, invite/request flows, roles
Hooks: manage channel hooks
Messages: history, search
DMs: send, react, accept/decline
Posts: react, delete
Notebook: post to diary channels
Settings: hot-reload plugin config via the settings store above

Capabilities

Feature	Status
Direct messages	Supported
Groups/channels	Supported (mention-gated by default)
Threads	Supported (keeps replying once it has joined)
Rich text	Markdown converted to Tlon’s native format
Images	Downloaded inbound, uploaded outbound
Reactions	Only via the bundled skill
Polls	Not supported
Native commands	Owner-only by default

Troubleshooting

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

Common failures:

DMs ignored: sender not in dmAllowlist and no ownerShip configured for the approval flow.
Group messages ignored: channel not discovered/pinned, or sender fails authorization with no ownerShip to queue an approval.
Connection errors: check the ship URL is reachable; set network.dangerouslyAllowPrivateNetwork for local ships.
Auth errors: login codes rotate — copy the current code from your ship.

Configuration reference

Full configuration: Configuration

Key	Meaning
`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.network.dangerouslyAllowPrivateNetwork`	Allow localhost/LAN ship URLs (SSRF opt-in).
`channels.tlon.ownerShip`	Owner ship: always authorized, receives approval requests.
`channels.tlon.dmAllowlist`	Ships allowed to DM (empty = none besides owner).
`channels.tlon.autoAcceptDmInvites`	Auto-accept DMs from ships in `dmAllowlist`.
`channels.tlon.autoAcceptGroupInvites`	Auto-accept group invites from `groupInviteAllowlist`.
`channels.tlon.groupInviteAllowlist`	Ships whose group invites are auto-accepted.
`channels.tlon.autoDiscoverChannels`	Auto-discover joined group channels (default: `false`).
`channels.tlon.groupChannels`	Manually pinned channel nests.
`channels.tlon.defaultAuthorizedShips`	Ships authorized for all channels (used when no rule matches).
`channels.tlon.authorization.channelRules`	Per-channel-nest auth mode + allowlist.
`channels.tlon.showModelSignature`	Append `_[Generated by <model>]_` to replies.
`channels.tlon.responsePrefix`	Static prefix prepended to outbound replies.
`channels.tlon.accounts.<id>`	Additional named accounts (multi-ship setups).

Notes

Group replies need an @ mention (e.g. ~your-bot-ship) unless the bot already joined that thread.
Thread replies land in-thread; the bot also gets the last 10 messages of thread context prepended for the agent.
Rich text (bold, italic, code, headers, lists) converts to Tlon’s native format.
Sending an inbound message that asks for a channel summary (for example “summarize this channel”) triggers a built-in history summarization instead of the normal reply flow.

Channels Overview — all supported channels
Pairing — DM authentication and pairing flow
Groups — group chat behavior and mention gating
Channel Routing — session routing for messages
Security — access model and hardening

​Bundled plugin

​Setup

​Private/LAN ships

​Group channels

​Access control

​Owner and approval system

​Auto-accept settings

​Hot-reload via Urbit settings store

​Delivery targets (CLI/cron)

​Bundled skill

​Capabilities

​Troubleshooting

​Configuration reference

​Notes

​Related

Bundled plugin

Setup

Private/LAN ships

Group channels

Access control

Owner and approval system

Auto-accept settings

Hot-reload via Urbit settings store

Delivery targets (CLI/cron)

Bundled skill

Capabilities

Troubleshooting

Configuration reference

Notes

Related