Connect Tlon (Urbit) to Your AI Agent

What Works

Direct messages, group channels, threads, rich text and images all work. Markdown your agent writes gets converted into Tlon's native formatting rather than arriving as raw asterisks, and images move in both directions.

Reactions and polls are the gap. The agent can be driven to react through the bundled Urbit toolkit, but it will not react as part of a normal reply, and polls are not supported at all.

The channel is bundled with current OpenClaw releases, so on a hosted instance there is nothing to install.

What You Need

• A running Urbit ship for the agent, reachable over the network.
• The ship name, its URL, and its current login code.

Give the agent its own ship rather than sharing your personal one. A comet or a moon is fine. The login code has to be stored for the agent to connect, and you do not want that to be the code to the identity you use yourself.

Login codes rotate. If the connection worked and then started failing authentication, this is almost always why — copy the current code from your ship.

Hosted Ships and Home Ships

If your ship is hosted somewhere with a public URL, this is straightforward: point the agent at that URL and it connects.

If your ship runs at home on your own network, a hosted agent cannot reach it. There is a setting that permits private and LAN addresses, but it exists for the case where the agent and the ship are on the same network — it does not make a home ship reachable from the internet. That setting also switches off a protection against the agent being tricked into making requests to internal addresses, so only turn it on for a ship URL you control.

Group Channels

In groups the agent stays quiet unless it is mentioned. That is the right default: an agent that answers every message in a busy channel gets muted by everyone within a day.

Once it has replied in a thread it keeps following that thread without needing to be mentioned again, which is what makes actual back-and-forth possible. You can turn that off if you would rather every single message required an explicit mention.

You can pin the channels it watches by hand, or let it discover the channels your ship has joined and pick up new ones as you join them. Discovery is off unless you turn it on.

Deciding Who Can Talk to It

This is the part worth setting up properly, because it is where Tlon support is genuinely nicer than most channels.

Nominate an owner ship — yours. The owner is authorised everywhere, is auto-accepted for DMs and group invites, and never needs to be on any list.

With an owner set, anything unauthorised does not just get dropped. Someone new DMs the agent, or mentions it somewhere it does not have permission, and you get a DM asking whether to allow it. You reply in that DM to approve or deny, and you can block a ship outright so it cannot reconnect, list what is pending, and reverse a block later.

Without an owner configured, unauthorised messages are silently dropped and logged. The agent looks broken to the person messaging it, and you never find out they tried. Set the owner.

Beyond that you can allow specific ships to DM, set a baseline of ships authorised across all channels, and override that per channel — including making one channel open to everyone in it while the rest stay restricted.

Changing Settings Without a Restart

Most access settings are mirrored into your ship's own settings store on first run and read live from there afterwards. That means you can change them from a Landscape client and they take effect immediately, without restarting the agent. Pending approvals live there too.

Message Durability

Accepted messages are written down before the agent is asked to handle them, so a restart mid-turn does not lose the message, and work stays ordered per channel and per person. Redelivered messages are suppressed rather than answered twice.

The tradeoff is at-least-once delivery: a crash at exactly the wrong moment can replay a turn. If you give the agent tools with real side effects, that is worth knowing.

Troubleshooting

• DMs ignored. The sender is not permitted and no owner ship is set, so there is no approval prompt and the message is simply dropped.
• Group messages ignored. The channel was never pinned or discovered, or the sender fails authorisation with no owner to ask.
• Authentication errors after it previously worked. The login code rotated.
• Cannot connect at all. The ship URL is not reachable from the agent — the usual case is a ship at home and an agent in the cloud.
• It replies but nobody reacts. Reactions are not part of normal replies on this channel.

Need a Hand?

Contact support from your dashboard with your ship name and URL and we will get it connected. Do not send the login code in chat — we will tell you where to put it.