openclaw/docs/channels/tlon.md

summary	read_when	title
Tlon/Urbit support status, capabilities, and configuration	Working on Tlon/Urbit channel features	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/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.

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