IRC | Docs | OpenClaw

如果你想让 OpenClaw 加入经典 IRC 频道（#room）和私信，可以使用 IRC 频道。IRC 以扩展插件形式提供，但在主配置的 channels.irc 下进行配置。

快速开始

在 ~/.openclaw/openclaw.json 中启用 IRC 配置。
至少设置以下内容：

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

启动/重启 Gateway：

openclaw gateway run

安全默认值

channels.irc.dmPolicy 默认为 "pairing"。
channels.irc.groupPolicy 默认为 "allowlist"。
当 groupPolicy="allowlist" 时，需设置 channels.irc.groups 来定义允许的频道。
除非你有意接受明文传输，否则请使用 TLS（channels.irc.tls=true）。

访问控制

IRC 频道有两道独立的访问门槛：

频道访问（groupPolicy + groups）：机器人是否接受来自某个频道的消息。
发送者访问（groupAllowFrom / 按频道的 groups["#channel"].allowFrom）：频道内谁可以触发机器人。

配置键：

私信白名单（私信发送者访问）：channels.irc.allowFrom
群组发送者白名单（频道发送者访问）：channels.irc.groupAllowFrom
按频道控制（频道 + 发送者 + 提及规则）：channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" 允许未配置的频道（默认仍需提及）

白名单条目应使用稳定的发送者身份（nick!user@host）。纯昵称匹配是可变的，仅在 channels.irc.dangerouslyAllowNameMatching: true 时启用。

常见误区：`allowFrom` 用于私信而非频道

如果你在日志中看到：

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

表示该发送者不在群组/频道消息的白名单中。解决方法：

设置 channels.irc.groupAllowFrom（对所有频道全局生效），或
设置按频道的发送者白名单：channels.irc.groups["#channel"].allowFrom

示例（允许 #tuirc-dev 中的任何人与机器人对话）：

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

回复触发（提及）

即使频道已允许（通过 groupPolicy + groups）且发送者也已允许，OpenClaw 在群组环境中默认仍启用提及过滤。

这意味着如果消息不包含匹配机器人的提及模式，你可能会在日志中看到 drop channel … (missing-mention) 的记录。

要让机器人在 IRC 频道中不需要提及就能回复，请为该频道禁用提及过滤：

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

或者允许所有 IRC 频道（无按频道白名单）且不需要提及即可回复：

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

安全须知（推荐用于公共频道）

如果你在公共频道中设置了 allowFrom: ["*"]，任何人都可以向机器人发送提示。为降低风险，请限制该频道可用的工具。

频道内所有人相同的工具权限

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

按发送者差异化工具权限（所有者拥有更多权限）

使用 toolsBySender 为 "*" 应用更严格的策略，为你自己的昵称应用更宽松的策略：

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

注意事项：

toolsBySender 的键应使用 id: 前缀标识 IRC 发送者身份：id:eigen 或 id:[email protected] 以实现更强的匹配。
旧版无前缀键仍被接受，仅作为 id: 匹配。
第一个匹配的发送者策略生效；"*" 是通配符回退。

关于群组访问与提及过滤的交互方式，详见：/channels/groups。

NickServ

连接后向 NickServ 认证：

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

可选的首次连接注册：

{
  "channels": {
    "irc": {
      "nickserv": {
        "register": true,
        "registerEmail": "[email protected]"
      }
    }
  }
}

昵称注册完成后请禁用 register，以避免重复发送 REGISTER 请求。

环境变量

默认账户支持：

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS（逗号分隔）
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

故障排查

如果机器人连接成功但从不在频道中回复，请检查 channels.irc.groups 以及提及过滤是否在丢弃消息（missing-mention）。如果想让它不需要被提及就回复，请为该频道设置 requireMention:false。
如果登录失败，请验证昵称可用性和服务器密码。
如果 TLS 在自定义网络上失败，请验证主机/端口和证书设置。