IRC

当你希望 OpenClaw 出现在经典频道（#room）和直接消息中时，请使用 IRC。
安装官方 IRC 插件，然后在 channels.irc 下进行配置。

快速开始

安装插件：

openclaw plugins install @openclaw/irc

至少在 ~/.openclaw/openclaw.json 中设置 host、nick，以及要加入的频道：

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

启动/重启网关：

openclaw gateway run

建议为机器人协调使用私有 IRC 服务器。如果你有意使用公共 IRC 网络，常见选择包括 Libera.Chat、OFTC 和 Snoonet。避免将机器人或 swarm 后端通信流量放在可预测的公共频道中。

入站持久性

OpenClaw 在进行正常的策略检查和代理分发之前，会将每个被接受的 IRC PRIVMSG 写入其持久化的入站队列。待处理或可重试的消息在 Gateway 重启后仍会保留，并且会按频道或直接消息对端进行序列化。 IRC 不提供可回放的传递 ID，也不会重新发送断开连接的客户端错过的消息。因此，OpenClaw 会分配一个本地 ID，该 ID 只在当前 TCP 连接内保持稳定。该队列保护的是本地“接收至分发”窗口；它既无法恢复从未到达 OpenClaw 的消息，也无法对跨连接的服务器重发进行去重。

连接设置

Key	Default	Notes
`host`	none (required)	IRC 服务器主机名
`port`	`6697` with TLS, `6667` plain	1-65535
`tls`	`true`	仅在有意使用明文时设置为 `false`
`nick`	none (required)	Bot 昵称
`username`	nick, else `openclaw`	IRC 用户名
`realname`	`OpenClaw`	Realname/GECOS 字段
`password` / `passwordFile`	none	服务器密码；文件必须是普通文件
`channels`	none	要加入的频道（`["#openclaw"]`）
`accounts` / `defaultAccount`	none	多账户设置；环境变量仅填充默认账户

安全默认值

IRC 使用原始 TCP/TLS 套接字，不经过 OpenClaw 运维管理的前向代理路由。在要求所有出站流量都必须经过该前向代理的部署中，除非已明确批准直接 IRC 出站，否则请设置 channels.irc.enabled=false。
channels.irc.dmPolicy 默认值为 "pairing"：未知的 DM 发送者会获得一个配对代码，您可使用 openclaw pairing approve irc <code> 批准该代码。
channels.irc.groupPolicy 默认值为 "allowlist"。
当 groupPolicy="allowlist" 时，请设置 channels.irc.groups 以定义允许的频道。
除非您有意接受明文传输，否则请使用 TLS（channels.irc.tls=true）。

访问控制

IRC 频道有两个独立的“门禁”：

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

配置键：

DM 白名单（DM 发送者访问）：channels.irc.allowFrom
组发送者白名单（频道发送者访问）：channels.irc.groupAllowFrom
每频道控制（频道 + 发送者 + 提及规则）：channels.irc.groups["#channel"]，包含 requireMention、allowFrom、enabled、tools、toolsBySender、skills 和 systemPrompt
channels.irc.groupPolicy="open" 允许未配置的频道（默认情况下仍然需要提及触发）

白名单条目应使用稳定的发送者身份（nick!user@host）。仅按裸 nick 匹配是不稳定的，只有在 channels.irc.dangerouslyAllowNameMatching: true 时才启用。

常见误区：`allowFrom` 适用于 DM，不适用于频道

如果你看到类似这样的日志：

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

……这意味着该发送者不被允许发送群组/频道消息。你可以通过以下任一方式修复：

设置 channels.irc.groupAllowFrom（全局应用于所有频道），或
为每个频道单独设置发送者白名单：channels.irc.groups["#channel"].allowFrom

示例（允许 #openclaw 中的任何人和机器人对话）：

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

回复触发（提及）

即使某个频道是允许的（通过 groupPolicy + groups），并且发送者也是允许的，OpenClaw 在群组上下文中默认仍会启用提及门控。当消息包含已连接机器人的昵称，或匹配你配置的提及模式时，机器人就会被视为已被提及。这意味着你可能会看到类似 drop channel … (missing-mention) 的日志，除非消息中包含与机器人匹配的提及模式。如果你想让机器人在 IRC 频道中无需提及也能回复，请为该频道关闭提及门控：

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

或者允许所有 IRC 频道（不使用按频道白名单），同时仍然无需提及即可回复：

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

安全说明（公共频道推荐）

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

频道中的所有人使用相同工具

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

不同发送者使用不同工具（所有者权限更高）

使用 toolsBySender 为 "*" 应用更严格的策略，并为你的 nick 应用更宽松的策略：

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

注意：

toolsBySender 键应使用显式前缀（channel:、id:、e164:、username:、name:）。对于 IRC，请使用发送者身份值的 id:：id:alice，或者 id:[email protected] 以获得更强的匹配。
旧式未加前缀的键仍然可接受，但只按 id: 匹配，并会发出弃用警告。
首个匹配到的发送者策略生效；"*" 是通配符回退项。

关于组访问与提及门控的更多信息（以及它们如何交互），请参见：/channels/groups。

NickServ

连接后使用 NickServ 进行身份验证：

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

当设置了密码时，NickServ identify 默认会运行（只需将 enabled 设为 false 即可选择退出）。service 默认值为 NickServ；passwordFile 是内联 password 的替代方案。可选的一次性连接注册（register: true 需要 registerEmail）：

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

在 nick 注册完成后，请禁用 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

IRC_HOST 不能从工作区的 .env 中设置；请参见 Workspace .env 文件。

故障排查

如果机器人已连接但在频道中从不回复，请检查 channels.irc.groups，以及提及门控是否正在丢弃消息（missing-mention）。如果你希望它在没有 ping 的情况下回复，请为该频道设置 requireMention:false。
如果登录失败，请检查 nick 是否可用以及服务器密码是否正确。
如果在自定义网络上 TLS 失败，请检查主机/端口和证书设置。

概览

主流消息平台

开发者与自托管

区域平台

配置

快速开始

入站持久性

连接设置

安全默认值

访问控制

常见误区：`allowFrom` 适用于 DM，不适用于频道

回复触发（提及）

安全说明（公共频道推荐）

频道中的所有人使用相同工具

不同发送者使用不同工具（所有者权限更高）

NickServ

环境变量

故障排查

相关内容

​快速开始

​入站持久性

​连接设置

​安全默认值

​访问控制

​常见误区：allowFrom 适用于 DM，不适用于频道

​回复触发（提及）

​安全说明（公共频道推荐）

​频道中的所有人使用相同工具

​不同发送者使用不同工具（所有者权限更高）

​NickServ

​环境变量

​故障排查

​相关内容

快速开始

入站持久性

连接设置

安全默认值

访问控制

常见误区：`allowFrom` 适用于 DM，不适用于频道

回复触发（提及）

安全说明（公共频道推荐）

频道中的所有人使用相同工具

不同发送者使用不同工具（所有者权限更高）

NickServ

环境变量

故障排查

相关内容