• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

本文以 OpenClaw 仓库中的 IRC 渠道文档为核心，讲解如何把 OpenClaw 接入经典 IRC 网络（#room频道与私聊），并深入源码层剖析其双闸门访问控制（渠道准入 + 发送者准入）、mention 门控的判定逻辑、allowlist 身份匹配规则、NickServ 认证流程以及全部环境变量与默认值。读完后，你可以独立完成 IRC 插件的配置、排障（日志中的drop …提示），并为公开频道设计一套安全的按发送者分层的工具权限策略。

一、IRC 渠道定位：扩展插件 + 主配置

IRC 是 OpenClaw 支持的渠道之一：它以扩展插件的形式随仓库分发（见 irc/openclaw.plugin.json，插件 id 为irc，注册渠道irc），但所有配置都写在主配置的channels.irc节点下，而不是插件私有配置。

从 irc/src/accounts.ts 可以看到，账户解析时会合并channels.irc（默认账户）与channels.irc.accounts.<id>（多账户）两部分配置，支持defaultAccount指定默认账户。是否"配置完成"的标准很朴素：host和nick都存在（configured: Boolean(host && nick)），否则监控器会直接抛出IRC is not configured for account "…" (need host and nick in channels.irc)（见 irc/src/monitor.ts）。

快速开始

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

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

3. 启动或重启 gateway：

openclaw gateway run

其中channels（复数，注意与顶层渠道命名空间channels区分）是机器人连接成功后要JOIN的频道列表。在 irc/src/client.ts 中，收到001（welcome）消息后，客户端先发送 NickServ 命令（如已启用），再依次对channels数组执行JOIN <频道>。

源码中的默认值速查

结合 irc/src/accounts.ts 的resolveIrcAccount，默认账户的解析规则如下：

二、安全默认：dmPolicy 与 groupPolicy

原文档给出的安全默认值得逐条落实：

• channels.irc.dmPolicy默认为"pairing"：陌生人私聊会触发配对（pairing）质询，而非直接对话；
• channels.irc.groupPolicy默认为"allowlist"：未在groups中配置的频道消息一律丢弃；
• groupPolicy="allowlist"时，必须设置channels.irc.groups才能放行任何频道；
• 除非你明确接受明文传输，否则保持channels.irc.tls: true。

这些默认值在配置模式中有明确定义（irc/src/config-schema.ts）：

dmPolicy: DmPolicySchema.optional().default("pairing"), groupPolicy: GroupPolicySchema.optional().default("allowlist"),

另外还有一个重要的 schema 校验：dmPolicy="open"时allowFrom必须包含"*"，否则配置校验直接报错（channels.irc.dmPolicy="open" requires channels.irc.allowFrom to include "*"），见 irc/src/config-schema.ts 中的requireOpenAllowFrom校验。这避免了"开放策略 + 空 allowlist"这种语义矛盾的配置。

群组消息的三道判定（源码视角）

从 irc/src/policy.ts 与 irc/src/inbound.ts 的实现可以还原出一条群组消息的完整判定链，与 docs/channels/groups.md 中描述的通用群组流程一致：

1. 渠道准入（resolveIrcGroupAccessGate）：groupPolicy="disabled"一律丢弃；allowlist模式下，频道必须命中groups的键（精确匹配，找不到时按小写不敏感再匹配一次，最后尝试"*"通配键），否则记录irc: drop channel <target> (not allowlisted)；open模式放行未配置频道，但groups["#x"].enabled: false的显式禁用仍然生效；
2. 发送者准入（resolveIrcGroupSenderAllowed）：优先使用命中频道的allowFrom（每频道列表），为空时回退到全局groupAllowFrom；两者都为空时，仅当groupPolicy === "open"才放行。未通过的发送者记录irc: drop group sender nick!user@host (policy=allowlist)后丢弃——这正是原文档"Common gotcha"小节对应的日志；
3. mention 门控（resolveIrcMentionGate）：群组消息默认要求消息中 @ 到机器人；requireMention: false可关闭；被 @ 或携带已授权控制命令的消息放行，否则记录irc: drop channel <target> (missing-mention)。

注意 irc/src/inbound.ts 中有一处有意的设计：groupAllowFromFallbackToAllowFrom: false，即群组发送者 allowlist 不会回退到私聊的allowFrom——两个名单是完全独立的，这也是原文档反复强调"allowFrom是给私聊用的"的源码依据。

三、访问控制详解：两套"门"与身份匹配规则

IRC 渠道有两套彼此独立的闸门：

1. 渠道准入（groupPolicy+groups）：机器人是否接受来自某个频道的消息；
2. 发送者准入（groupAllowFrom/ 每频道groups["#channel"].allowFrom）：在该频道里，谁可以触发机器人。

配置键总览：

• 私聊发送者准入（DM allowlist）：channels.irc.allowFrom
• 群组发送者准入（全局，作用于所有频道）：channels.irc.groupAllowFrom
• 每频道控制（渠道 + 发送者 + mention 规则）：channels.irc.groups["#channel"]
• groupPolicy="open"放行未配置的频道（默认仍然有 mention 门控）

为什么必须用nick!user@host稳定身份

allowlist 条目应使用稳定的发送者身份（nick!user@host），裸 nick 匹配是可变的（任何人可以抢占该 nick），只有显式打开channels.irc.dangerouslyAllowNameMatching: true才启用——源码注释称之为 "Break-glass override"（见 irc/src/types.ts）。

匹配逻辑在 irc/src/normalize.ts 中：buildIrcAllowlistCandidates为一条入站消息生成候选身份集合——

• nick（仅当dangerouslyAllowNameMatching: true）；
• nick!user、nick@host、nick!user@host（后三者总可用，字段缺失时跳过）；

条目与 allowlist 均小写化后做集合匹配；allowlist 含"*"时直接全放行（source: "wildcard"）。这解释了为什么文档推荐id:eigen!~eigen@174.127.248.171这类完整写法做"更强的匹配"。

常见坑：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: ["*"] }, }, }, }, }

"*"作为每频道allowFrom的通配值在 irc/src/normalize.ts 的resolveIrcAllowlistMatch中直接判定放行。

四、回复触发：mention 门控

即使频道被groupPolicy+groups放行、发送者也被允许，OpenClaw 在群组上下文中默认开启 mention 门控：消息必须包含匹配机器人的 @ 提及，否则记录drop channel … (missing-mention)并丢弃（不进入会话上下文）。

从 irc/src/inbound.ts 可以看到判定细节：提及匹配由两部分组成——通用的mentionPatterns正则集合（buildMentionRegexes），以及针对当前实际 nick 的显式正则\b<nick>\b[:,]?（忽略大小写、允许后跟逗号/冒号）。注意这里用的是连接后的实际 nick（client.nick）而非配置中的nick，因此若 nick 冲突后发生了回退（见下文 NickServ GHOST 流程），匹配目标也会自动跟随。

要让机器人在某个频道无需被 @ 即回复，对该频道关闭 mention 门控：

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

或者放行所有IRC 频道（不设每频道 allowlist）且不要求提及：

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

requireMention的解析优先级（irc/src/policy.ts）：命中频道的requireMention>"*"通配配置的requireMention> 默认true。即每频道配置优先于通配配置，都未设置则要求提及。

关于群组消息的统一语义（会话键、/activation命令等），可参考 docs/channels/groups.md。

五、公开频道的安全加固：tools 与 toolsBySender

如果公开频道里使用了allowFrom: ["*"]，任何人都能向机器人发提示词。降低风险的做法是限制该频道可用的工具。

场景一：频道内所有人同一套工具限制

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

group:runtime、group:fs是内置工具组，展开逻辑见 src/agents/tool-policy.test.ts 中的expandToolGroups(["group:runtime", "BASH", "apply-patch", "group:fs"])；安全审计建议（src/security/audit-extra.sync.ts）也明确：对开放群组优先拒绝group:runtime/group:fs，并考虑tools.fs.workspaceOnly与沙箱。

场景二：按发送者区分（owner 拥有更多权限）

使用toolsBySender：对"*"用更严格的策略，对自己的 nick 用更宽松的策略：

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

键名规则（实现位于 config/group-policy.ts）：

• toolsBySender的键推荐使用id:前缀表示 IRC 发送者身份，如id:eigen或更强的id:eigen!~eigen@174.127.248.171；
• 无类型的旧式裸键仍被接受，但只按id:语义匹配，且运行时会对每个此类键发出一条弃用警告（OPENCLAW_TOOLS_BY_SENDER_UNTYPED_KEY）；
• 第一个匹配到的发送者策略生效，"*"是通配兜底（parseSenderPolicyKey中*单独归类为 wildcard，typed 键按类型分桶匹配）。

六、NickServ：认证、注册与 nick 冲突自救

连接后向 NickServ 认证：

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

可选的一次性注册（connect 时执行）：

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

注意：nick 注册完成后应把register关掉，避免重复发起REGISTER。schema 层也强制这一点的一半：register=true时registerEmail必填，否则配置校验报错（irc/src/config-schema.ts）。

源码层面的行为（irc/src/client.ts）：收到001后，buildIrcNickServCommands生成命令序列——

1. PRIVMSG NickServ :IDENTIFY <password>（service缺省为NickServ）；
2. 若register: true，追加PRIVMSG NickServ :REGISTER <password> <email>，缺 email 直接抛错IRC NickServ register requires registerEmail。

此外还有两个值得了解的容错机制：

• nick 冲突自救：若登录阶段收到 nick 已被占用/无效的错误码（433/436），且启用了带密码的 NickServ，客户端会先发送PRIVMSG NickServ :GHOST <nick> <password>再重新NICK；GHOST 失败才回退到一个<nick>_形式的备选 nick（buildFallbackNick，最长 30 字符，非法字符过滤），见 irc/src/client.ts 与 client.ts；
• 服务器密码错误：收到432/464/465会直接以IRC login failed (…)失败退出。

七、环境变量

默认账户（defaultaccount）支持以下环境变量，解析顺序为"配置文件 > 环境变量"，仅在默认账户生效（见 irc/src/accounts.ts）：

非默认账户（channels.irc.accounts.<id>）不读取这些变量，多账户场景请在各自账户配置中显式填写。

八、排障指南

对应原文档 Troubleshooting 小节，结合源码中真实的日志文案给出定位方法：

• 机器人连上了但频道里从不回复：依次检查channels.irc.groups是否包含该频道（日志：irc: drop channel <target> (not allowlisted)），以及 mention 门控是否丢弃了消息（日志：irc: drop channel <target> (missing-mention)）。若希望无需 @ 即回复，为该频道设置requireMention: false。
• 登录失败：核实 nick 是否可用、服务器密码是否正确。客户端会给出IRC login failed (433): nickname in use这类带错误码的报错；若配置了 NickServ，客户端会尝试GHOST恢复，仍失败才回退备选 nick。
• TLS 连接失败：在自定义网络下检查 host/port 与证书配置；tls: false时才走明文net.connect。
• 私聊被丢弃：日志irc: drop DM sender <id> (dmPolicy=pairing)表示对方尚未完成配对；dmPolicy=disabled则所有私聊直接丢弃。
• 群组发送者被丢弃：日志irc: drop group sender <id> (policy=allowlist)，按第三节"常见坑"设置groupAllowFrom或每频道allowFrom。
• 配置校验报错：dmPolicy="open"未包含allowFrom: ["*"]、register=true缺registerEmail等，schema 会在启动前直接拒绝，错误信息指明具体路径。

九、其他值得知道的细节

• 消息切分：出站消息按默认每段 350 字符（messageChunkMaxChars）切分，优先在空格处断行（irc/src/client.ts, client.ts），避免 IRC 单行长度限制截断；
• PING/PONG 保活：客户端自动应答服务器PING（irc/src/client.ts），无需额外配置；
• 自环防护：监控器会忽略发送者 nick 与自身连接 nick 相同的PRIVMSG，防止机器人自激（irc/src/monitor.ts）；
• 每频道额外能力：IrcGroupSchema（irc/src/config-schema.ts）还支持skills（限制该频道可用的技能）、systemPrompt（该频道专属系统提示词，注入GroupSystemPrompt）、enabled: false（显式禁用单个频道）与tools/toolsBySender；
• 主动发消息：sendMessageIrc在连接未就绪时会临时建立一条连接发送后立即QUIT，并支持irc:/user:/channel:前缀的目标归一化（irc/src/send.ts、irc/src/normalize.ts）。

小结

OpenClaw 的 IRC 渠道把"经典 IRC 网络机器人"的安全模型做成了三层防线：groupPolicy/groups管渠道准入，groupAllowFrom/每频道allowFrom管发送者准入（且与私聊allowFrom完全隔离），requireMention管触发时机；公开频道再通过tools/toolsBySender做工具级最小权限。配合 NickServ 认证、nick!user@host稳定身份与环境变量注入，即可在 Libera.Chat 等网络上安全地运行一个受控的 AI IRC 机器人。相关源码集中在 irc/ 目录，行为测试可参考 irc/src/inbound.policy.test.ts 与 irc/src/policy.ts 对应的用例。

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯