How to Connect OpenClaw to Tlon (Urbit)

Prerequisites

• ✓An existing OpenClaw gateway running a current packaged release that includes bundled plugins.
• ✓Access to an Urbit ship with its ship name, ship URL, and a valid login code (e.g. `~sampel-palnet`, `https://your-ship-host`, `lidlut-tabwed-pillex-ridrup`).
• ✓Permission to restart your OpenClaw gateway after changing its configuration.

Steps

1. 1

   Ensure the Tlon plugin is available

   Tlon ships as a bundled plugin in current OpenClaw releases, so you usually do not need to install anything extra. If you run an older build or a custom install that excludes Tlon, install the plugin so the gateway can speak to your Urbit ship.

   bashCopy

   openclaw plugins install @openclaw/tlon

2. 2

   Install the Tlon plugin from a local checkout when developing

   If you are hacking on the Tlon plugin from a git repo, point OpenClaw at your local checkout instead of the npm registry. This keeps your gateway using your local changes while you iterate.

   bashCopy

   openclaw plugins install ./path/to/local/tlon-plugin

3. 3

   Configure the basic Tlon channel connection

   tlon` block so OpenClaw knows which ship to log into and which ship owns the bot. This is where you wire in the ship URL, login code, and owner ship that always has access.

   jsonCopy

   {
     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 allowed
       },
     },
   }

4. 4

   Allow private or LAN Urbit ships when needed

   If your Urbit ship runs on localhost or a LAN IP, OpenClaw blocks it by default for SSRF protection. Explicitly enable private network access for the Tlon channel so the gateway can reach your ship.

   jsonCopy

   {
     channels: {
       tlon: {
         url: "http://localhost:8080",
         allowPrivateNetwork: true,
       },
     },
   }

5. 5

   Control which Tlon group channels your bot joins

   By default, OpenClaw auto-discovers group channels, but you can pin specific nests or disable discovery entirely. This is useful when you want the bot only in a few curated channels.

   jsonCopy

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

6. 6

   Disable auto-discovery of Tlon group channels when locking down scope

   If you do not want OpenClaw to auto-join or discover new Tlon channels, turn off auto-discovery. You can then rely entirely on `groupChannels` and explicit invites.

   jsonCopy

   {
     channels: {
       tlon: {
         autoDiscoverChannels: false,
       },
     },
   }

7. 7

   Configure DM allowlists and group authorization

   Tighten access by specifying which ships can DM the bot and which ships are allowed in each channel. This prevents random ships from talking to your agent and gives you per-channel control.

   jsonCopy

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

8. 8

   Set the owner ship and auto-accept behavior

   Configure an owner ship to receive approval requests and decide who can talk to the bot. You can also enable auto-accept for DM and group invites to reduce manual approvals for trusted ships.

   jsonCopy

   {
     channels: {
       tlon: {
         ownerShip: "~your-main-ship",
       },
     },
   }

9. 9

   Enable auto-accept for DM and group invites when appropriate

   If you want smoother onboarding for allowlisted ships and group invites, turn on the auto-accept flags. This lets OpenClaw accept DMs from `dmAllowlist` ships and all group invites without manual intervention.

   jsonCopy

   {
     channels: {
       tlon: {
         autoAcceptDmInvites: true,
       },
     },
   }

10. 10

    Restart the gateway and test with a DM or group mention

    After updating the configuration, restart your OpenClaw gateway so the Tlon channel comes up with the new settings. Then DM the bot or mention it in a group channel to confirm it responds as expected.

Configuration

Troubleshooting

{
  channels: {
    tlon: {
      dmAllowlist: ["~zod", "~nec"],
    },
  },
}

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

{
  channels: {
    tlon: {
      url: "http://localhost:8080",
      allowPrivateNetwork: true,
    },
  },
}

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

Frequently asked questions