OpenClaw 白皮书
当你希望在经典频道（#room）和私信中使用 OpenClaw 时，可以使用 IRC。 IRC 作为扩展插件提供，但在主配置文件的 channels.irc 下进行配置。

快速开始

  1. ✦在 ~/.openclaw/openclaw.json 中启用 IRC 配置。
  2. ✦至少设置以下内容：
json
{
  "channels": {
    "irc": {
      "enabled": true,
      "host": "irc.libera.chat",
      "port": 6697,
      "tls": true,
      "nick": "openclaw-bot",
      "channels": ["#openclaw"]
    }
  }
}
  1. ✦启动/重启 Gateway 网关：
bash
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 中的任何人与机器人对话）：
json5
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": { allowFrom: ["*"] },
      },
    },
  },
}

回复触发（提及）

即使频道被允许（通过 groupPolicy + groups）且发送者被允许，OpenClaw 在群组上下文中默认启用提及门控。
这意味着你可能会看到类似 drop channel … (missing-mention) 的日志，除非消息中包含与机器人匹配的提及模式。
要让机器人在 IRC 频道中无需提及即可回复，请为该频道禁用提及门控：
json5
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}
或者允许所有 IRC 频道（不使用每频道允许列表）且无需提及即可回复：
json5
{
  channels: {
    irc: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: false, allowFrom: ["*"] },
      },
    },
  },
}

安全说明（建议用于公共频道）

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

频道内所有人使用相同工具

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

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

使用 toolsBySender 对 "*" 应用更严格的策略，对你的昵称应用更宽松的策略：
json5
{
  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: 匹配。
  • ✦第一个匹配的发送者策略生效；"*" 是通配符回退。
关于群组访问与提及门控的更多信息（及其交互方式），请参阅：/channels/groups。

NickServ

连接后使用 NickServ 进行身份验证：
json
{
  "channels": {
    "irc": {
      "nickserv": {
        "enabled": true,
        "service": "NickServ",
        "password": "your-nickserv-password"
      }
    }
  }
}
连接时可选的一次性注册：
json
{
  "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）。如果希望它无需 ping 即可回复，请为该频道设置 requireMention:false。
  • ✦如果登录失败，请验证昵称可用性和服务器密码。
  • ✦如果 TLS 在自定义网络上失败，请验证主机/端口和证书设置。