> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install ./path/to/local/tlon-plugin
```
Details: [Plugins](/tools/plugin)
## Setup
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels add --channel tlon --ship ~sampel-palnet --url https://your-ship-host --code lidlut-tabwed-pillex-ridrup
```
Or edit config directly:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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`):
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
tlon: {
dmAllowlist: ["~zod", "~nec"],
},
},
}
```
Group authorization defaults to `restricted` per channel. Set `defaultAuthorizedShips` for a
baseline, and override per channel nest:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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 ` / `deny ` | 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):
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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):
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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`](https://github.com/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](#bundled-skill) |
| Polls | Not supported |
| Native commands | Owner-only by default |
## Troubleshooting
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/gateway/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 ]_` to replies. |
| `channels.tlon.responsePrefix` | Static prefix prepended to outbound replies. |
| `channels.tlon.accounts.` | 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](/channels) — all supported channels
* [Pairing](/channels/pairing) — DM authentication and pairing flow
* [Groups](/channels/groups) — group chat behavior and mention gating
* [Channel Routing](/channels/channel-routing) — session routing for messages
* [Security](/gateway/security) — access model and hardening