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 channels status --probe

配置更改遵循热重载。如果 Gateway 离线，请使用 openclaw gateway run 启动它。

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

入站持久性¶

OpenClaw 会在常规策略检查和代理分发之前，将每条已接受的 IRC PRIVMSG 写入其持久入站队列。待处理或可重试的消息会在 Gateway 重启后保留，并按频道或直接消息对端保持串行化。

IRC 不提供可重放的投递 ID，也不会重发被断开连接的客户端错过的消息。因此，OpenClaw 会分配一个仅在当前 TCP 连接内稳定的本地 ID。该队列保护从本地接受到分发的窗口；它无法恢复从未到达 OpenClaw 的消息，也无法跨连接对服务器重发进行去重。

连接设置¶

键	默认值	说明
`host`	无（必填）	IRC 服务器主机名
`port`	使用 TLS 时为 `6697`，明文为 `6667`	1-65535
`tls`	`true`	仅在有意使用明文时设置为 `false`
`nick`	无（必填）	机器人昵称
`username`	nick，否则为 `openclaw`	IRC 用户名
`realname`	`OpenClaw`	Realname/GECOS 字段
`password` / `passwordFile`	无	服务器密码；文件必须是常规文件
`channels`	无	要加入的频道（`["#openclaw"]`）
`replyToMode`	`all`	回复引用模式：`off`、`first`、`all` 或 `batched`
`accounts` / `defaultAccount`	无	多账户设置；环境变量仅填充默认账户

命名账户继承频道范围的回复模式；使用 channels.irc.accounts.<id>.replyToMode 覆盖它。

在默认 hybrid 重载模式下，添加或编辑非默认命名账户只会重启该 IRC 账户。其他账户连接和 Gateway 保持运行，手动停止的账户保持停止。共享 IRC 设置、 accounts.default 和账户删除会重启整个 IRC 频道，因为它们可能影响继承或账户选择。

账户重启会在关闭其入站队列之前完成已接受消息的准入；替换监视器会从同一队列中恢复待处理的频道消息。断开连接期间错过的消息无法恢复，并且来自先前连接的待处理直接消息会被丢弃，因为 IRC 昵称可能更改所有者。

出站文本¶

IRC 以纯文本发送 Markdown，保留代码内容和链接目标。长回复在拆分为 IRC 消息之前先渲染，因此代码围栏和内联格式在分块边界处保持一致。textChunkLimit 和 streaming.chunkMode 控制文本拆分；套接字还会强制 IRC 的行大小限制。

如果非空文本在格式化或 IRC 清理期间变为空，则发送失败，而不是报告已投递。回复引用不计为消息内容。

使用 message CLI 直接发送到频道或昵称：

openclaw message send --channel irc --target '#openclaw' --message 'Hello from OpenClaw'

安全默认值¶

IRC 使用 OpenClaw 操作员管理的前向代理路由之外的原始 TCP/TLS 套接字。在要求所有出站流量都经过该前向代理的部署中，除非明确批准直接 IRC 出站，否则设置 channels.irc.enabled=false。
channels.irc.dmPolicy 默认为 "pairing"：未知直接消息发送者会获得一个配对码，你使用 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）：谁被允许在该频道内触发机器人。

配置键：

直接消息允许列表（直接消息发送者访问）：channels.irc.allowFrom
群组发送者允许列表（频道发送者访问）：channels.irc.groupAllowFrom
按频道控制（频道 + 发送者 + 提及规则）：channels.irc.groups["#channel"]，包含 requireMention、allowFrom、enabled、tools、toolsBySender、skills 和 systemPrompt
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

示例（允许 #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 对 "*" 应用更严格的策略，并对你的昵称应用更宽松的策略：

{
  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:alice!~alice@203.0.113.7，以实现更强的匹配。
旧版无前缀键仍会被接受，但仅按 id: 匹配，并会发出弃用警告。
第一个匹配的发送者策略生效；"*" 是通配符回退。

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

NickServ¶

连接后向 NickServ 进行身份验证：

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

只要设置了密码，NickServ 身份验证默认就会运行（enabled 只需设为 false 即可退出）。service 默认为 NickServ；passwordFile 是内联 password 的替代方式。

连接时可选的一次性注册（register: true 需要 registerEmail）：

{
  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

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

故障排除¶

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

频道概览 — 所有支持的频道
配对 — 私聊身份验证和配对流程
群组 — 群聊行为和提及门控
频道路由 — 消息的会话路由
安全 — 访问模型和加固

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

IRC