How to Connect OpenClaw to IRC

Prerequisites

• ✓An OpenClaw gateway already installed and runnable with the `openclaw gateway run` command.
• ✓Access to an IRC server (private IRC server recommended; public networks like Libera.Chat, OFTC, or Snoonet are supported if you accept the security tradeoffs).
• ✓Permission to create or join at least one IRC channel such as `#openclaw` for the bot.
• ✓A NickServ account on your IRC network if you plan to use NickServ identification or registration.

Steps

1. 1

   Enable the IRC channel in your OpenClaw config

   Start by turning on the IRC extension in your main OpenClaw config so the gateway knows to connect. json` and add an `irc` block under `channels` with `enabled: true`.

   This is also where you point OpenClaw at your IRC host, port, and initial channels.

   jsonCopy

   {
     channels: {
       irc: {
         enabled: true,
         host: "irc.example.com",
         port: 6697,
         tls: true,
         nick: "openclaw-bot",
         channels: ["#openclaw"],
       },
     },
   }

2. 2

   Prefer a private IRC server or choose a public network carefully

   Decide where your bot will live: a private IRC server is safer for bot coordination, while public networks expose it to anyone who can see the channel. If you intentionally use a public IRC network, stick to well-known networks and avoid predictable channel names for internal bot traffic.

   This choice affects how strict you should be with access control and tools.

   textCopy

   Prefer a private IRC server for bot coordination. If you intentionally use a public IRC network, common choices include Libera.Chat, OFTC, and Snoonet. Avoid predictable public channels for bot or swarm backchannel traffic.

3. 3

   Control who can DM or talk to the bot in channels

   Configure access control so random IRC users cannot drive your agent. groups` to decide which channels the bot listens to, and `allowFrom` / `groupAllowFrom` to decide which senders can trigger it.

   This step prevents the common gotcha where the bot connects but silently drops channel messages due to allowlists.

   jsonCopy

   {
     channels: {
       irc: {
         groupPolicy: "allowlist",
         groups: {
           "#tuirc-dev": { allowFrom: ["*"] },
         },
       },
     },
   }

4. 4

   Decide whether the bot requires mentions in channels

   By default, OpenClaw uses mention-gating in group contexts, so it drops channel messages that do not mention the bot. If you want the bot to respond to every message in a channel, disable mention gating for that channel and keep an eye on who can send messages.

   You can also open all channels and still disable mention gating with a wildcard group.

   jsonCopy

   {
     channels: {
       irc: {
         groupPolicy: "allowlist",
         groups: {
           "#tuirc-dev": {
             requireMention: false,
             allowFrom: ["*"],
           },
         },
       },
     },
   }
   
   {
     channels: {
       irc: {
         groupPolicy: "open",
         groups: {
           "*": { requireMention: false, allowFrom: ["*"] },
         },
       },
     },
   }

5. 5

   Restrict tools for public channels and per-sender access

   If you allow `allowFrom: ["*"]` in a public channel, lock down which tools the bot can use there so strangers cannot trigger sensitive operations. You can define a single tools policy for everyone in a channel, or use `toolsBySender` so your own nick keeps more capabilities while the wildcard `*` stays restricted.

   This is critical when your bot runs tools that touch runtime, filesystem, or external systems.

   jsonCopy

   {
     channels: {
       irc: {
         groups: {
           "#tuirc-dev": {
             allowFrom: ["*"],
             tools: {
               deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
             },
           },
         },
       },
     },
   }
   
   {
     channels: {
       irc: {
         groups: {
           "#tuirc-dev": {
             allowFrom: ["*"],
             toolsBySender: {
               "*": {
                 deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
               },
               "id:eigen": {
                 deny: ["gateway", "nodes", "cron"],
               },
             },
           },
         },
       },
     },
   }

6. 6

   Configure NickServ identification or registration if needed

   If your IRC network uses NickServ, configure OpenClaw to identify after connecting so it can hold your chosen nick. You can also enable one-time registration on connect for a fresh bot nick, then disable registration once it is done to avoid repeated REGISTER attempts.

   This keeps your bot compliant with networks that enforce registered nicks.

   jsonCopy

   {
     channels: {
       irc: {
         nickserv: {
           enabled: true,
           service: "NickServ",
           password: "your-nickserv-password",
         },
       },
     },
   }
   
   {
     channels: {
       irc: {
         nickserv: {
           register: true,
           registerEmail: "bot@example.com",
         },
       },
     },
   }

7. 7

   Start or restart the OpenClaw gateway to connect to IRC

   irc` settings and connects to your IRC server. Watch the logs for connection, NickServ, and message handling events to confirm access control and mention behavior work as expected.

   Any changes to the config require another restart to take effect.

   bashCopy

   openclaw gateway run

Configuration

Troubleshooting

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": { allowFrom: ["*"] },
      },
    },
  },
}

{
  channels: {
    irc: {
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "your-nickserv-password",
      },
    },
  },
}

{
  channels: {
    irc: {
      nickserv: {
        register: true,
        registerEmail: "bot@example.com",
      },
    },
  },
}

{
  channels: {
    irc: {
      enabled: true,
      host: "irc.example.com",
      port: 6697,
      tls: true,
      nick: "openclaw-bot",
      channels: ["#openclaw"],
    },
  },
}

Frequently asked questions