Tlon

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/[email protected]) 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.

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:

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

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

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.

Related

• 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