IRC

当您希望在经典渠道（#room）和私信中使用 OpenClaw 时，请使用 IRC。 IRC 作为捆绑插件提供，但在主配置中的 channels.irc 下进行配置。

快速开始

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

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

建议使用私有 IRC 服务器进行机器人协调。如果您有意使用公共 IRC 网络，常见的选择包括 Libera.Chat、OFTC 和 Snoonet。避免使用可预测的公共渠道进行机器人或群组后端流量传输。

启动/重启网关：

openclaw gateway run

安全默认值

IRC 使用原始 TCP/TLS 套接字，在 OpenClaw 运营商管理的转发代理路由之外。在需要所有出口流量都经过该转发代理的部署中，请设置 OpenClawchannels.irc.enabled=false，除非明确批准直接的 IRC 出口流量。
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 + groupsOpenClaw）且发送者是被允许的，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

无法从工作区 .env 设置 IRC_HOST；请参阅工作区 .env 文件。

故障排除

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

IRC