IRC Channel Setup and Troubleshooting for OpenClaw

Use IRC when you want OpenClaw in classic channels (#room) and direct messages. Install the official IRC plugin, then configure it under channels.irc.

Quick start

1. Install the plugin:

openclaw plugins install @openclaw/irc

2. Set at least host, nick, and the channels to join in ~/.openclaw/openclaw.json:

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

3. Start/restart the Gateway:

openclaw gateway run

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.

Inbound durability

OpenClaw writes each accepted IRC PRIVMSG to its durable ingress queue before normal policy checks and agent dispatch. Pending or retryable messages survive a Gateway restart and remain serialized per channel or direct-message peer.

IRC does not provide a replayable delivery ID or resend messages missed by a disconnected client. OpenClaw therefore assigns a local ID that is stable only within the current TCP connection. The queue protects the local accept-to-dispatch window; it cannot recover a message that never reached OpenClaw or deduplicate a server resend across connections.

Connection settings

Named accounts inherit the channel-wide reply mode; override it with channels.irc.accounts.<id>.replyToMode.

Security defaults

• IRC uses raw TCP/TLS sockets outside OpenClaw operator-managed forward proxy routing. In deployments that require all egress through that forward proxy, set channels.irc.enabled=false unless direct IRC egress is explicitly approved.
• channels.irc.dmPolicy defaults to "pairing": unknown DM senders get a pairing code you approve with openclaw pairing approve irc <code>.
• 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:

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 (who may send direct messages): channels.irc.allowFrom
• Group sender allowlist (who may send to channels): channels.irc.groupAllowFrom
• Per-channel rules (channel, sender, and mention settings): channels.irc.groups["#channel"] combined with requireMention, allowFrom, enabled, tools, toolsBySender, skills, and systemPrompt
• channels.irc.groupPolicy="open" permits channels without explicit configuration (mention-gating still applies by default)

For allowlist entries, rely on stable sender identities (nick!user@host). Bare nick matching is changeable and only active when channels.irc.dangerouslyAllowNameMatching: true is set.

Common gotcha: allowFrom is for DMs, not channels

When logs contain entries like:

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

...the sender was rejected for group/channel messages. Resolve this by either:

• configuring channels.irc.groupAllowFrom (applies globally across all channels), or
• defining per-channel sender allowlists via channels.irc.groups["#channel"].allowFrom

Example (let anyone in #openclaw message the bot):

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#openclaw": { allowFrom: ["*"] },
      },
    },
  },
}

Reply triggering (mentions)

Even with a channel allowed (through groupPolicy plus groups) and the sender permitted, OpenClaw still applies mention-gating by default in group settings. The bot counts as mentioned if the message carries the connected bot nick or aligns with your configured mention patterns.

Consequently, logs may show drop channel … (missing-mention) unless the message includes a mention pattern that matches the bot.

To have the bot respond in an IRC channel without requiring a mention, turn off mention gating for that specific channel:

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

Alternatively, to permit all IRC channels (skipping per-channel allowlists) while still replying without mentions:

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

Security note (recommended for public channels)

Enabling allowFrom: ["*"] in a public channel lets any user prompt the bot. To lower exposure, limit the tools available for that channel.

Same tools for everyone in the channel

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

Different tools per sender (owner gets more power)

Apply toolsBySender to enforce a stricter policy on "*" and a more relaxed one on your own nick:

{
  channels: {
    irc: {
      groups: {
        "#openclaw": {
          allowFrom: ["*"],
          toolsBySender: {
            "*": {
              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
            },
            "id:alice": {
              deny: ["gateway", "nodes", "cron"],
            },
          },
        },
      },
    },
  },
}

Notes:

• toolsBySender keys must carry explicit prefixes (channel:, id:, e164:, username:, name:). For IRC, use id: with the sender identity value: id:alice or id:alice!~alice@203.0.113.7 for more precise matching.
• Unprefixed legacy keys remain accepted, matched solely as id:, and trigger a deprecation warning.
• The first sender policy that matches takes precedence; "*" serves as the wildcard fallback.

Details on group access versus mention-gating (and their interaction) are covered at: /channels/groups.

NickServ

To authenticate with NickServ after connecting:

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

NickServ identify runs automatically whenever a password is provided (set enabled to false to disable it). service defaults to NickServ; passwordFile offers an alternative to inline password.

Optional one-time registration upon connect (register: true requires registerEmail):

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

Turn off register once the nick is registered to prevent repeated REGISTER attempts.

Environment variables

Default account capabilities include:

• 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

A workspace .env cannot define IRC_HOST; refer to Workspace .env files for details.

Troubleshooting

• When the bot connects but stays silent in channels, check channels.irc.groups and whether mention-gating filters out messages (missing-mention). To have it respond without pings, configure requireMention:false for that channel.
• A failed login calls for checking nick availability and the server password.
• On a custom network, TLS failures require verifying host/port settings and certificate configuration.

Related

• Channels Overview, every supported channel
• Pairing, DM authentication and the pairing process
• Groups, group chat behavior and mention gating
• Channel Routing, session routing for messages
• Security, access model and hardening