Tlon/Urbit Plugin: Setup, Configuration, and Capabilities

Tlon is a decentralized messaging application built on Urbit. OpenClaw connects to your Urbit ship and handles DMs and group chat messages. By default, group replies require an @ mention, with additional authorization rules and an owner approval process layered on top.

Status: bundled plugin. DMs, group mentions, threads, rich text, image upload and download, and an owner approval system are supported. Reactions and polls are not.

Bundled plugin

Tlon ships bundled with current OpenClaw releases; packaged builds do not need a separate installation.

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.

Inbound durability

OpenClaw persists accepted Tlon DM and group chat events before agent dispatch. Pending or retryable turns survive a Gateway restart, and work remains serialized per group channel or direct peer. Stable Urbit message IDs also suppress a redelivered event while its queue record or retained completion record exists.

Delivery is at least once across the queue to agent boundary: a crash during handoff can replay a turn. Agent actions that produce external side effects should therefore remain idempotent where practical.

Private/LAN ships

OpenClaw blocks private and 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.

Note

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 means 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.

Set channels.tlon.implicitMentions.threadParticipation: false to require a new explicit mention for those follow-ups. Account overrides use channels.tlon.accounts.<id>.implicitMentions. Tlon does not currently produce replyToBot or quotedBot facts, so those flags have no effect here.

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. 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 and 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 or 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, every channel type that is supported
• Pairing, how DM authentication and pairing works
• Groups, group chat mechanics and mention gating
• Channel Routing, routing messages within sessions
• Security, access control and hardening measures