> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IRC

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

## 快速开始

1. 安装插件：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/irc
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      enabled: true,
      host: "irc.example.com",
      port: 6697,
      tls: true,
      nick: "openclaw-bot",
      channels: ["#openclaw"],
    },
  },
}
```

3. 启动/重启网关：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 频道有两个独立的“门禁”：

1. **频道访问**（`groupPolicy` + `groups`）：决定机器人是否接受来自某个频道的消息。
2. **发送者访问**（`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` 中的任何人和机器人对话）：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#openclaw": { allowFrom: ["*"] },
      },
    },
  },
}
```

## 回复触发（提及）

即使某个频道是允许的（通过 `groupPolicy` + `groups`），并且发送者也是允许的，OpenClaw 在群组上下文中默认仍会启用**提及门控**。当消息包含已连接机器人的昵称，或匹配你配置的提及模式时，机器人就会被视为已被提及。

这意味着你可能会看到类似 `drop channel … (missing-mention)` 的日志，除非消息中包含与机器人匹配的提及模式。

如果你想让机器人在 IRC 频道中**无需提及**也能回复，请为该频道关闭提及门控：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#openclaw": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: false, allowFrom: ["*"] },
      },
    },
  },
}
```

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      groups: {
        "#openclaw": {
          allowFrom: ["*"],
          tools: {
            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
          },
        },
      },
    },
  },
}
```

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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](/channels/groups)。

## NickServ

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "your-nickserv-password",
      },
    },
  },
}
```

当设置了密码时，NickServ identify 默认会运行（只需将 `enabled` 设为 `false` 即可选择退出）。`service` 默认值为 `NickServ`；`passwordFile` 是内联 `password` 的替代方案。

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    irc: {
      nickserv: {
        register: true,
        registerEmail: "bot@example.com",
      },
    },
  },
}
```

在 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` 文件](/gateway/security)。

## 故障排查

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

## 相关内容

* [频道概览](/channels) — 所有受支持的频道
* [配对](/channels/pairing) — DM 身份验证和配对流程
* [组](/channels/groups) — 群聊行为和提及门控
* [频道路由](/channels/channel-routing) — 消息的会话路由
* [安全性](/gateway/security) — 访问模型和加固