文档

IRC

Use IRC when you want OpenClaw in classic 渠道s (#room) and direct messages.
IRC ships as an extension plugin, but it is configured in the main config under channels.irc.

快速开始

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

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
irc: {
enabled: true,
host: “irc.libera.chat”,
port: 6697,
tls: true,
nick: “openclaw-bot”,
渠道s: [“#openclaw”],
},
},
}


3. Start/restart gateway:

```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway run

Security defaults

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

Access control

There are two separate “gates” for IRC 渠道s:

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

Config keys:

DM allowlist (DM sender access): channels.irc.allowFrom
Group sender allowlist (渠道 sender access): channels.irc.groupAllowFrom
Per-渠道 controls (渠道 + sender + mention rules): channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" allows unconfigured 渠道s (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 渠道s

If you see logs like:

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

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

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

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

“`json55 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
irc: {
groupPolicy: “allowlist”,
groups: {
“#tuirc-dev”: { allowFrom: [“*”] },
},
},
},
}


## Reply triggering (mentions)

Even if a channel is allowed (via `groupPolicy` + `groups`) and the sender is allowed, OpenClaw defaults to **mention-gating** in group contexts.

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:

```json55  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}

Or to allow all IRC 渠道s (no per-渠道 allowlist) and still reply without mentions:

“`json55 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
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, restrict tools for that channel.

### Same tools for everyone in the channel

```json55  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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:

“`json55 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
irc: {
groups: {
“#tuirc-dev”: {
allowFrom: [““],
toolsBySender: {
““: {
deny: [“group:runtime”, “group:fs”, “网关”, “nodes”, “cron”, “browser”],
},
“id:eigen”: {
deny: [“网关”, “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 (and how they interact), see: [/channels/groups](/channels/groups).

## NickServ

To identify with NickServ after connect:

```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "your-nickserv-password",
      },
    },
  },
}

可选项 one-time registration on connect:

json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { irc: { nickserv: { register: true, registerEmail: "bot@example.com", }, }, }, }

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

Environment variables

Default account supports:

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

故障排查

If the bot connects but never replies in 渠道s, verify 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 渠道.
If login fails, verify nick availability and server password.
If TLS fails on a custom network, verify host/port and certificate setup.

IRC