Connecting OpenClaw to Tlon

I know the frustration of trying to get a bot running on a decentralized network. You usually end up wrestling with unique protocols or authentication methods that don’t play nice with your existing setup. It often feels like you’re building everything from scratch just to send a simple message.

If you want to bring your bot into the Urbit ecosystem, the Tlon plugin is the way to go. I’ve found it’s the most direct path to handling DMs and group chats without overcomplicating your stack.

What You’ll Need

• A running Urbit ship.
• Your ship URL and login code.
• OpenClaw installed on your system.
• The Tlon plugin package.

Quick Start

Setting this up takes about five minutes. I recommend following these four steps to get your bot online:

1. Install the plugin Run this command to grab the plugin from the npm registry:

   openclaw plugins install @openclaw/tlon

   If you are running from a local git repo, use:

   openclaw plugins install ./extensions/tlon

2. Add your configuration Update your config file with your ship details. Here is a minimal setup for a single account:

   {
     channels: {
       tlon: {
         enabled: true,
         ship: "~sampel-palnet",
         url: "https://your-ship-host",
         code: "lidlut-tabwed-pillex-ridrup",
       },
     },
   }

3. Restart the gateway Apply the changes by restarting your OpenClaw gateway instance.

4. Verify the connection Test the integration by sending a DM to your bot ship or mentioning it in a group channel.

Managing Groups and Access

By default, the plugin discovers channels automatically. If you want to pin specific channels or turn off auto-discovery, you can use these settings:

{
  channels: {
    tlon: {
      groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
      autoDiscoverChannels: false,
    },
  },
}

You can also control who talks to your bot. Use dmAllowlist for private messages or set specific rules for group channels to keep things organized:

{
  channels: {
    tlon: {
      defaultAuthorizedShips: ["~zod"],
      authorization: {
        channelRules: {
          "chat/~host-ship/general": {
            mode: "restricted",
            allowedShips: ["~zod", "~nec"],
          },
          "chat/~host-ship/announcements": {
            mode: "open",
          },
        },
      },
    },
  },
}

Troubleshooting

• Bot isn’t responding in a group: Check if you mentioned the bot. Group replies require an @ mention (like ~your-bot-ship) to trigger a response.
• Media uploads are failing: The plugin does not support native media uploads. It uses a fallback where the URL is appended to the text caption.
• Reactions or polls aren’t working: These features are currently not supported by the Tlon plugin.
• Replies appearing in threads: This is the default behavior. If an inbound message is in a thread, OpenClaw will reply within that same thread.

If you run into other issues, ask the AI Setup Assistant.

What’s Next

• Plugins Documentation