docs/channels/irc.md
Use IRC when you want OpenClaw in classic channels (#room) and direct messages.
Install the official IRC plugin, then configure it under channels.irc.
openclaw plugins install @openclaw/irc
~/.openclaw/openclaw.json:{
channels: {
irc: {
enabled: true,
host: "irc.example.com",
port: 6697,
tls: true,
nick: "openclaw-bot",
channels: ["#openclaw"],
},
},
}
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.
| Key | Default | Notes |
|---|---|---|
host | none (required) | IRC server hostname |
port | 6697 with TLS, 6667 plain | 1-65535 |
tls | true | Set false only for intentional plaintext |
nick | none (required) | Bot nick |
username | nick, else openclaw | IRC username |
realname | OpenClaw | Realname/GECOS field |
password / passwordFile | none | Server password; file must be a regular file |
channels | none | Channels to join (["#openclaw"]) |
accounts / defaultAccount | none | Multi-account setup; env vars fill only the default account |
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".groupPolicy="allowlist", set channels.irc.groups to define allowed channels.channels.irc.tls=true) unless you intentionally accept plaintext transport.There are two separate "gates" for IRC channels:
groupPolicy + groups): whether the bot accepts messages from a channel at all.groupAllowFrom / per-channel groups["#channel"].allowFrom): who is allowed to trigger the bot inside that channel.Config keys:
channels.irc.allowFromchannels.irc.groupAllowFromchannels.irc.groups["#channel"] with requireMention, allowFrom, enabled, tools, toolsBySender, skills, and systemPromptchannels.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.
allowFrom is for DMs, not channelsIf you see logs like:
irc: drop group sender alice!ident@host (policy=allowlist)...it means the sender wasn't allowed for group/channel messages. Fix it by either:
channels.irc.groupAllowFrom (global for all channels), orchannels.irc.groups["#channel"].allowFromExample (allow anyone in #openclaw to talk to the bot):
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#openclaw": { allowFrom: ["*"] },
},
},
},
}
Even if a channel is allowed (via groupPolicy + groups) and the sender is allowed, OpenClaw defaults to mention-gating in group contexts. The bot counts as mentioned when the message contains the connected bot nick or matches your configured mention patterns.
That means you may 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: {
"#openclaw": {
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: ["*"] },
},
},
},
}
If you allow allowFrom: ["*"] in a public channel, anyone can prompt the bot.
To reduce risk, restrict tools for that channel.
{
channels: {
irc: {
groups: {
"#openclaw": {
allowFrom: ["*"],
tools: {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
},
},
},
},
}
Use toolsBySender to apply a stricter policy to "*" and a looser one to your 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 should use explicit prefixes (channel:, id:, e164:, username:, name:). For IRC use id: with the sender identity value: id:alice or id:[email protected] for stronger matching.id: only, and emit a deprecation warning."*" is the wildcard fallback.For more on group access vs mention-gating (and how they interact), see: /channels/groups.
To identify with NickServ after connect:
{
channels: {
irc: {
nickserv: {
enabled: true,
service: "NickServ",
password: "your-nickserv-password",
},
},
},
}
NickServ identify runs by default whenever a password is set (enabled only needs to be false to opt out). service defaults to NickServ; passwordFile is an alternative to inline password.
Optional one-time registration on connect (register: true requires registerEmail):
{
channels: {
irc: {
nickserv: {
register: true,
registerEmail: "[email protected]",
},
},
},
}
Disable register after the nick is registered to avoid repeated REGISTER attempts.
Default account supports:
IRC_HOSTIRC_PORTIRC_TLSIRC_NICKIRC_USERNAMEIRC_REALNAMEIRC_PASSWORDIRC_CHANNELS (comma-separated)IRC_NICKSERV_PASSWORDIRC_NICKSERV_REGISTER_EMAILIRC_HOST cannot be set from a workspace .env; see Workspace .env files.
channels.irc.groups and whether mention-gating is dropping messages (missing-mention). If you want it to reply without pings, set requireMention:false for the channel.