Connect OpenClaw to IRC: Setup Guide in 3 Minutes

Setting up a bot for IRC can feel like a trip back in time, but it remains one of the most reliable ways to keep a developer community connected. If you have ever struggled with bot permissions or wondered why your bot is ghosting your messages in a channel, this guide will help you get everything running smoothly.

You can use IRC when you want OpenClaw in classic channels (#room) and direct messages. IRC ships as an extension plugin, but you configure it in the main config under channels.irc.

Quick start

1. Enable IRC config in ~/.openclaw/openclaw.json.
2. Set at least:

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

3. Start/restart gateway:

openclaw gateway run

Security defaults

OpenClaw comes with safe defaults to ensure you do not accidentally expose your bot.

• channels.irc.dmPolicy defaults to "pairing".
• channels.irc.groupPolicy defaults to "allowlist".
• With groupPolicy="allowlist", set channels.irc.groups to define allowed channels.
• Use TLS (channels.irc.tls=true) unless you intentionally accept plaintext transport.

Access control

There are two separate “gates” for IRC channels that you need to manage:

1. Channel access (groupPolicy + groups): whether the bot accepts messages from a channel at all.
2. Sender access (groupAllowFrom / per-channel groups["#channel"].allowFrom): who is allowed to trigger the bot inside that channel.

Config keys:

• DM allowlist (DM sender access): channels.irc.allowFrom
• Group sender allowlist (channel sender access): channels.irc.groupAllowFrom
• Per-channel controls (channel + sender + mention rules): channels.irc.groups["#channel"]
• channels.irc.groupPolicy="open" allows unconfigured channels (still mention-gated by default)

Allowlist entries should use stable sender identities (nick!user@host). Bare nick matching is mutable and only enabled when channels.irc.dangerouslyAllowNameMatching: true.

Common gotcha: allowFrom is for DMs, not channels

If you see logs like irc: drop group sender alice!ident@host (policy=allowlist), it means the sender was not allowed for group/channel messages. You can fix it by either:

• setting channels.irc.groupAllowFrom (global for all channels), or
• setting per-channel sender allowlists: channels.irc.groups["#channel"].allowFrom

Example (allow anyone in #tuirc-dev to talk to the bot):

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

Reply triggering (mentions)

Even if a channel is allowed and the sender is authorized, OpenClaw defaults to mention-gating in group contexts. You might see logs like drop channel … (missing-mention) unless the message includes a mention pattern that matches the bot.

To make the bot reply in an IRC channel without needing a mention, disable mention gating for that channel:

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

Or to allow all IRC channels (no per-channel allowlist) and still reply without mentions:

{
  channels: {
    irc: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: false, allowFrom: ["*"] },
      },
    },
  },
}

Security note (recommended for public channels)

If you allow allowFrom: ["*"] in a public channel, anyone can prompt the bot. To reduce risk, you should restrict tools for that channel.

Same tools for everyone in the channel

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

Different tools per sender (owner gets more power)

Use toolsBySender to apply a stricter policy to "*" and a looser one to your nick:

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

Notes:

• toolsBySender keys should use id: for IRC sender identity values: id:eigen or id:eigen!~eigen@174.127.248.171 for stronger matching.
• Legacy unprefixed keys are still accepted and matched as id: only.
• The first matching sender policy wins; "*" is the wildcard fallback.

For more on group access vs mention-gating, check out the /channels/groups documentation.

NickServ

To identify with NickServ after connecting:

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

Optional one-time registration on connect:

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

Disable register after the nick is registered to avoid repeated attempts.

Environment variables

The default account supports these variables:

• IRC_HOST
• IRC_PORT
• IRC_TLS
• IRC_NICK
• IRC_USERNAME
• IRC_REALNAME
• IRC_PASSWORD
• IRC_CHANNELS (comma-separated)
• IRC_NICKSERV_PASSWORD
• IRC_NICKSERV_REGISTER_EMAIL

Troubleshooting

• If the bot connects but never replies in channels, verify channels.irc.groups and check if mention-gating is dropping messages (missing-mention). If you want it to reply without pings, set requireMention:false for the channel.
• If login fails, verify nick availability and server password.
• If TLS fails on a custom network, verify host/port and certificate setup.
• Check your logs for specific error codes if the connection drops unexpectedly.

Next steps

• Channels Overview — all supported channels
• Pairing — DM authentication and pairing flow
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening

Still having trouble? Try the AI Setup Assistant.