OpenClaw
OpenClaw Tlon Channel
Decentralized
Advanced
Connect OpenClaw to Tlon, the decentralized messenger built on Urbit. This integration enables your AI assistant to receive and respond to direct messages and group mentions across Tlon's peer-to-peer network — no centralized servers, no corporate accounts, just your Urbit ship identity and an authentication code. Ideal for sovereign computing enthusiasts and organizations that value true data ownership.
Quick Info
Difficulty
Advanced
Category
Decentralized
Features Supported
1
/ 6
Tlon Supported Features
Text Messages
Supported
Media & Files
Not Supported
Reactions
Not Supported
Threads
Not Supported
Voice Messages
Not Supported
Group Chat
Not Supported
Tlon Prerequisites
- OpenClaw Gateway installed and running
- A running Urbit ship (planet, star, or comet) accessible via HTTP
- The ship's authentication code (obtainable from the ship's web interface)
- Node.js 18+ installed on your server
Tlon Quick Setup
1
Install the Tlon plugin
Run 'openclaw plugins install @openclaw/tlon' to add the Tlon channel. Alternatively, use 'openclaw onboard' or 'openclaw channels add' and select Tlon from the plugin list. Restart the Gateway after installation.
2
Configure your Urbit ship credentials
Set your Urbit ship identifier (e.g., ~sampel-palnet), the ship's host URL (e.g., http://localhost:8080), and the authentication code as environment variables. Reference them in your openclaw.json configuration using ${URBIT_SHIP}, ${URBIT_URL}, and ${URBIT_CODE}.
3
Start and send a test message
Restart the Gateway with 'openclaw start'. Open the Tlon app on your Urbit ship and send a direct message to the bot's ship. The bot should decrypt, process, and respond automatically.
Tlon Configuration Example
config.json
{
"channels": {
"tlon": {
"ship": "${URBIT_SHIP}",
"url": "${URBIT_URL}",
"code": "${URBIT_CODE}",
"enabled": true
}
}
}Tlon Deep Dive
Architecture Overview
Tlon is a messaging application built on Urbit, a peer-to-peer computing platform where each user runs their own server (called a "ship"). Unlike centralized platforms, your data lives on your ship and you control it entirely.
The message flow works as follows:
1. A user sends a DM or mentions the bot in a Tlon group chat
2. The message is delivered via Urbit's Ames networking protocol to the bot's ship
3. OpenClaw receives the message through the ship's HTTP API
4. The Gateway processes the message through your AI agent and posts the response back via the same API
Because Urbit is a peer-to-peer network, there is no central server that can be shut down or censored. Each ship maintains its own state, and messages are delivered directly between ships through the Ames protocol.
The bot runs as a companion process alongside your Urbit ship — it connects via the ship's local HTTP API, not through any external service.
Urbit ships have persistent identity: a planet like ~sampel-palnet is your permanent address on the network.
Plugin Installation
The Tlon channel is distributed as an optional OpenClaw plugin rather than being built into the core Gateway. This keeps the base installation lightweight while allowing you to add Tlon/Urbit support when needed.
Installation methods:
• **npm (recommended):** Run 'openclaw plugins install @openclaw/tlon' to install the stable release.
• **Local development:** Clone the plugin repository and use 'openclaw plugins install ./extensions/tlon' to install from a local checkout.
• **Interactive setup:** Run 'openclaw onboard' or 'openclaw channels add' and select Tlon from the list.
After installation, restart the Gateway for the plugin to take effect.
Run 'openclaw plugins list' to verify the Tlon plugin is installed and active.
Urbit Ship Setup & Authentication
To connect OpenClaw to Tlon, you need three pieces of information from your Urbit ship:
1. **Ship identifier** — Your Urbit identity (e.g., ~sampel-palnet). This is the ship that will act as the bot.
2. **Host URL** — The HTTP endpoint where the ship is accessible. Urbit defaults to port 80, falling back to 8080 if port 80 is in use (e.g., http://localhost:8080). Check your ship's startup logs for the actual port.
3. **Authentication code** — A secret code used to authenticate API requests. You can find this in your ship's web interface under Settings, or by running '+code' in the Dojo (Urbit's command line).
OpenClaw uses these credentials to authenticate with the ship's HTTP API and subscribe to incoming messages.
openclaw.json
{
"channels": {
"tlon": {
"ship": "${URBIT_SHIP}",
"url": "${URBIT_URL}",
"code": "${URBIT_CODE}"
}
}
}
Never hardcode your authentication code directly in openclaw.json. Always use environment variables (e.g., ${URBIT_CODE}) and set them via 'export URBIT_CODE="sampel-ticlyt-migfun-falmel"' in your shell or a .env file.
Auto-Discovery & Channel Pinning
By default, OpenClaw auto-discovers group channels on your Urbit ship, allowing the bot to respond to mentions in any group it has joined. You can disable auto-discovery and manually pin specific channels instead.
Channel paths in Tlon follow the format: chat/~host-ship/channel-name. For example, 'chat/~host-ship/general' refers to the 'general' chat channel hosted by ~host-ship.
When auto-discovery is disabled, only pinned channels will be monitored. This is useful when you want the bot to participate in specific conversations without being triggered in every group.
openclaw.json
{
"channels": {
"tlon": {
"autoDiscovery": false,
"channels": [
"chat/~host-ship/general",
"chat/~host-ship/support"
]
}
}
}
Auto-discovery is enabled by default. Set autoDiscovery: false to restrict the bot to only pinned channels.
Channel paths use the format chat/~host-ship/channel-name. Check your Tlon app for the exact path of each channel.
DM Policies
DM (Direct Message) policies control who can interact with your AI assistant via Tlon. Because Urbit ships have persistent identities, access control is based on ship addresses.
OpenClaw supports the following DM policies for the Tlon channel:
• **open (default)** — Any ship can send a DM to the bot. Since Tlon DMs require both parties to be on the Urbit network, this is relatively safe.
• **allowlist** — Only ships listed in allowFrom can message the bot. All others are ignored.
When allowFrom is set to an empty array, all ships are permitted (equivalent to open mode). Add specific ship addresses to restrict access.
openclaw.json
{
"channels": {
"tlon": {
"allowFrom": [
"~sampel-palnet",
"~timluc-miptev"
]
}
}
}Group Access Control
Group channels in Tlon have their own access control layer. By default, groups are restricted — the bot will only respond in groups where authorized ships are explicitly listed.
Each group channel can be configured with:
• **authorized** — A list of ship addresses that can trigger the bot in this group
• **mode** — Either 'restricted' (only authorized ships can trigger) or 'open' (any group member can trigger)
In groups, the bot responds only when explicitly mentioned with an @ mention. This prevents the bot from replying to every message in a busy group chat.
openclaw.json
{
"channels": {
"tlon": {
"groups": {
"chat/~host-ship/general": {
"mode": "restricted",
"authorized": ["~sampel-palnet"]
},
"chat/~host-ship/public": {
"mode": "open"
}
}
}
}
}
In restricted mode, only ships listed in 'authorized' can trigger bot responses.
Group responses require @ mentions — the bot will not respond to regular messages even in open mode.
Delivery Targets (CLI & Cron)
OpenClaw supports sending proactive messages via the CLI or scheduled cron jobs. For the Tlon channel, you can target both DMs and group channels.
DM delivery targets:
• ~sampel-palnet — Send a DM to this ship
• dm/~sampel-palnet — Explicit DM format
Group delivery targets:
• chat/~host-ship/channel — Post to a specific group channel
• group:~host-ship/channel — Alternative group format
This is useful for sending scheduled notifications, alerts, or periodic reports to specific ships or group channels.
CLI examples
# Send a DM to a specific ship
openclaw send tlon ~sampel-palnet "Your daily report is ready."
# Post to a group channel
openclaw send tlon chat/~host-ship/general "System status: all clear."Media Handling Limitations
The current Tlon integration supports text messages only. Reactions, polls, and native media uploads are not supported due to limitations in the plugin's Urbit API integration.
When the AI agent generates a response that includes media (images, files, etc.), the plugin falls back to text-only delivery:
• Images — The URL is appended to the message text instead of being displayed inline
• Files — A download link is included in the text response
• Reactions — Not supported; the bot cannot react to messages
• Threads — Not supported; all replies go to the main conversation
Future plugin updates may add native media support as the Tlon platform evolves.
If your AI agent frequently generates image responses, consider including a note in the system prompt that the Tlon channel is text-only.
URLs in messages are clickable in the Tlon app — users can tap to view media content in their browser.
Tlon Configuration Reference
| Key | Type | Default | Description |
|---|---|---|---|
| ship | string | (required) | Your Urbit ship identifier (e.g., ~sampel-palnet). This is the ship that acts as the bot. |
| url | string | "http://localhost:8080" | HTTP endpoint where the Urbit ship is accessible |
| code | string | (required) | Authentication code for the Urbit ship's HTTP API. Use an environment variable reference. |
| enabled | boolean | true | Enable or disable the Tlon channel |
| name | string | "" | Display name for this channel instance |
| autoDiscovery | boolean | true | Automatically discover and monitor all group channels on the ship |
| channels | string[] | [] | List of group channel paths to monitor when autoDiscovery is disabled (e.g., chat/~host-ship/general) |
| allowFrom | string[] | [] | List of ship addresses allowed to DM the bot. Empty array permits all ships. |
| groups | object | {} | Per-group access control configuration with mode and authorized ship lists |
| groups.<path>.mode | string | "restricted" | Group access mode: 'restricted' (only authorized ships) or 'open' (any group member) |
| groups.<path>.authorized | string[] | [] | List of ship addresses authorized to trigger the bot in this group (when mode is 'restricted') |
ship
Type:
string
Default:
(required)
Your Urbit ship identifier (e.g., ~sampel-palnet). This is the ship that acts as the bot.
url
Type:
string
Default:
"http://localhost:8080"
HTTP endpoint where the Urbit ship is accessible
code
Type:
string
Default:
(required)
Authentication code for the Urbit ship's HTTP API. Use an environment variable reference.
enabled
Type:
boolean
Default:
true
Enable or disable the Tlon channel
name
Type:
string
Default:
""
Display name for this channel instance
autoDiscovery
Type:
boolean
Default:
true
Automatically discover and monitor all group channels on the ship
channels
Type:
string[]
Default:
[]
List of group channel paths to monitor when autoDiscovery is disabled (e.g., chat/~host-ship/general)
allowFrom
Type:
string[]
Default:
[]
List of ship addresses allowed to DM the bot. Empty array permits all ships.
groups
Type:
object
Default:
{}
Per-group access control configuration with mode and authorized ship lists
groups.<path>.mode
Type:
string
Default:
"restricted"
Group access mode: 'restricted' (only authorized ships) or 'open' (any group member)
groups.<path>.authorized
Type:
string[]
Default:
[]
List of ship addresses authorized to trigger the bot in this group (when mode is 'restricted')
Tlon Frequently Asked Questions
Tlon Troubleshooting
Bot starts but does not receive any messages
The ship URL or authentication code may be incorrect, or the ship is not running.
Verify the ship is accessible by opening the URL in a browser. Check that the authentication code is correct (run '+code' in the Dojo). Ensure environment variables are exported correctly: 'echo $URBIT_URL' and 'echo $URBIT_CODE'.
Error: authentication failed
The authentication code has expired or is incorrect. Urbit ships can rotate their authentication codes.
Retrieve a fresh authentication code from the ship's web interface (Settings) or by running '+code' in the Dojo. Update the URBIT_CODE environment variable and restart the Gateway.
Bot responds to DMs but not in group channels
Auto-discovery may be disabled and the group channel is not pinned, or the group access control is blocking the sender.
Check if autoDiscovery is set to false — if so, add the group channel to the channels array. Verify the sender's ship is in the group's authorized list (for restricted mode). Remember that group responses require @ mentions.
Plugin not found after installation
The Gateway was not restarted after plugin installation, or the installation failed silently.
Run 'openclaw plugins list' to verify the Tlon plugin is installed. If not listed, re-run 'openclaw plugins install @openclaw/tlon'. Restart the Gateway with 'openclaw start' after installation.
Connection drops frequently
The Urbit ship's HTTP API may be unreachable due to network issues or the ship being under heavy load.
Check your network connectivity to the ship. If running remotely, ensure the HTTP port is not blocked by a firewall. Consider running the bot on the same machine as the ship to minimize latency. Check the ship's Dojo for error messages.