IRC

Use IRC when you want OpenClaw in classic channels (

) and direct messages. IRC ships as a bundled plugin, but it is configured in the main config under .

Quick start

1. Enable IRC config in
   text

   Copy

   ~/.openclaw/openclaw.json
   .
2. Set at least:

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

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. Start/restart gateway:

bash
Copy
openclaw gateway run

Security defaults

• text

  Copy

  channels.irc.dmPolicy
  defaults to
  text

  Copy

  "pairing"
  .
• text

  Copy

  channels.irc.groupPolicy
  defaults to
  text

  Copy

  "allowlist"
  .
• With
  text

  Copy

  groupPolicy="allowlist"
  , set
  text

  Copy

  channels.irc.groups
  to define allowed channels.
• Use TLS (
  text

  Copy

  channels.irc.tls=true
  ) unless you intentionally accept plaintext transport.

Access control

There are two separate “gates” for IRC channels:

1. Channel access (
   text

   Copy

   groupPolicy
   +
   text

   Copy

   groups
   ): whether the bot accepts messages from a channel at all.
2. Sender access (
   text

   Copy

   groupAllowFrom
   / per-channel
   text

   Copy

   groups["#channel"].allowFrom
   ): who is allowed to trigger the bot inside that channel.

Config keys:

• DM allowlist (DM sender access):
  text

  Copy

  channels.irc.allowFrom
• Group sender allowlist (channel sender access):
  text

  Copy

  channels.irc.groupAllowFrom
• Per-channel controls (channel + sender + mention rules):
  text

  Copy

  channels.irc.groups["#channel"]
• text

  Copy

  channels.irc.groupPolicy="open"
  allows unconfigured channels (still mention-gated by default)

Allowlist entries should use stable sender identities (

). Bare nick matching is mutable and only enabled when .

Common gotcha:

text

Copy

allowFrom

is for DMs, not channels

If you see logs like:

• text

  Copy

  irc: drop group sender alice!ident@host (policy=allowlist)

…it means the sender wasn’t allowed for group/channel messages. Fix it by either:

• setting
  text

  Copy

  channels.irc.groupAllowFrom
  (global for all channels), or
• setting per-channel sender allowlists:
  text

  Copy

  channels.irc.groups["#channel"].allowFrom

Example (allow anyone in

to talk to the bot):

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

Reply triggering (mentions)

Even if a channel is allowed (via

+ ) and the sender is allowed, OpenClaw defaults to mention-gating in group contexts.

That means you may see logs like

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:

json5
Copy
{
  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:

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

Security note (recommended for public channels)

If you allow

in a public channel, anyone can prompt the bot. To reduce risk, restrict tools for that channel.

Same tools for everyone in the channel

json5
Copy
{
  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

to apply a stricter policy to and a looser one to your nick:

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

Notes:

• text

  Copy

  toolsBySender
  keys should use
  text

  Copy

  id:
  for IRC sender identity values:
  text

  Copy

  id:eigen
  or
  text

  Copy

  id:eigen!~eigen@174.127.248.171
  for stronger matching.
• Legacy unprefixed keys are still accepted and matched as
  text

  Copy

  id:
  only.
• The first matching sender policy wins;
  text

  Copy

  "*"
  is the wildcard fallback.

For more on group access vs mention-gating (and how they interact), see: /channels/groups.

NickServ

To identify with NickServ after connect:

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

Optional one-time registration on connect:

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

Disable

after the nick is registered to avoid repeated REGISTER attempts.

Environment variables

Default account supports:

• text

  Copy

  IRC_HOST
• text

  Copy

  IRC_PORT
• text

  Copy

  IRC_TLS
• text

  Copy

  IRC_NICK
• text

  Copy

  IRC_USERNAME
• text

  Copy

  IRC_REALNAME
• text

  Copy

  IRC_PASSWORD
• text

  Copy

  IRC_CHANNELS
  (comma-separated)
• text

  Copy

  IRC_NICKSERV_PASSWORD
• text

  Copy

  IRC_NICKSERV_REGISTER_EMAIL

cannot be set from a workspace ; see Workspace

text

Copy

.env

files.

Troubleshooting

• If the bot connects but never replies in channels, verify
  text

  Copy

  channels.irc.groups
  and whether mention-gating is dropping messages (
  text

  Copy

  missing-mention
  ). If you want it to reply without pings, set
  text

  Copy

  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.

Related

• 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