IRC

IRC 渠道让你的小龙虾在经典频道（#room）和私信中畅游。 IRC 以扩展插件形式提供，但配置写在主配置文件的 channels.irc 节点下。

快速开始

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.irc.dmPolicy 默认为 "pairing"（私信需配对审批）。
• channels.irc.groupPolicy 默认为 "allowlist"（频道需白名单）。
• 当 groupPolicy="allowlist" 时，通过 channels.irc.groups 设置允许的频道列表。
• 除非你明确接受明文传输，否则请启用 TLS（channels.irc.tls=true）。

访问控制

IRC 频道有两道独立的"闸门"：

1. 频道访问（groupPolicy + groups）：机器人是否接受来自某频道的消息。
2. 发送者访问（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:eigen!~eigen@174.127.248.171（更精确匹配）。
• 旧版无前缀键仍然被接受，仅按 id: 方式匹配。
• 第一个匹配的发送者策略优先生效；"*" 是通配符兜底。

关于群组访问与提及门控的更多交互细节，请参见：群组消息。

NickServ 认证

连接后向 NickServ 注册身份：

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

连接时一次性注册（可选）：

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

昵称注册完成后，请禁用 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 失败：检查主机/端口及证书配置。