IRC
IRC adapter(适配器)将 Kopi Agent 连接到任意 IRC 服务器,并在 IRC 频道(或私信)与 agent 之间转发消息。它通过 Python 标准库 asyncio 使用 IRC 协议通信——无需外部依赖、无需 SDK、无需守护进程。它适用于 Libera.Chat 等公共网络以及任何自托管的 ircd。
IRC 是纯文本协议:不支持语音、图片、文件、话题(thread)、表情回应(reaction)、输入状态提示或流式传输——回复以 nickserv_password 行发送,较长的消息会自动拆分以符合 IRC 行长度限制。
运行
kopi gateway setup并选择 IRC,即可获得引导式配置流程。
前提条件
- 一个可连接的 IRC 服务器(例如
irc.libera.chat) - 一个要加入的频道(例如
#kopi)——多个频道用逗号分隔 - bot 的昵称(默认:
kopi-bot) - 可选:如果你的网络要求身份验证,需提供已注册的昵称 + NickServ 密码
配置 Kopi Agent
你可以通过两种方式配置 IRC——环境变量(适合仅使用环境变量的快速配置)或 ~/.kopi/gateway-config.yaml 中的 gateway 配置块。
选项 A — gateway-config.yaml
gateway:
platforms:
irc:
enabled: true
extra:
server: irc.libera.chat
port: 6697
nickname: kopi-bot
channel: "#kopi"
use_tls: true
server_password: "" # optional server password
nickserv_password: "" # optional NickServ identification
allowed_users: [] # empty = allow all, or list of nicks
max_message_length: 450 # IRC line limit (safe default)
选项 B — 环境变量
| 变量 | 必填 | 说明 |
|---|---|---|
IRC_SERVER | ✅ | IRC 服务器主机名(例如 irc.libera.chat) |
IRC_CHANNEL | ✅ | 要加入的频道——多个频道用逗号分隔 |
IRC_NICKNAME | ✅ | Bot 昵称(默认:kopi-bot) |
IRC_PORT | — | 服务器端口(默认:启用 TLS 时为 6697,未启用时为 6667) |
IRC_USE_TLS | — | 是否使用 TLS(true/false;端口 6697 上默认为 true) |
IRC_SERVER_PASSWORD | — | PASS 命令使用的服务器密码 |
IRC_NICKSERV_PASSWORD | — | 连接时自动执行 IDENTIFY 所需的 NickServ 密码 |
IRC_ALLOWED_USERS | — | 允许与 bot 对话的昵称列表,以逗号分隔 |
IRC_ALLOW_ALL_USERS | — | 允许频道中的任何人与 bot 对话(仅用于开发) |
IRC_HOME_CHANNEL | — | 用于定时任务 / 通知投递的频道(默认为 IRC_CHANNEL) |
访问控制
默认情况下,只有列在 allowed_users(或 IRC_ALLOWED_USERS)中的昵称才能与 bot 对话。将列表留空并设置 IRC_ALLOW_ALL_USERS=true,即可让频道中的任何人与 Kopi Agent 聊天——这在测试时很有用,但不建议在公共网络上使用,因为除非网络强制要求 NickServ,否则 IRC 昵称未经身份验证。
如果你的网络支持注册昵称,请设置 IRC_NICKSERV_PASSWORD(或 nickserv_password),以便 bot 在连接时向 NickServ 完成身份验证,并保持其已注册的昵称。
频道与私信
- 在已加入频道中发送的消息被视为群组对话。
- 发送给 bot 的私信被视为直接消息(direct message)。
定时任务和通知会投递到主频道——如果设置了 IRC_HOME_CHANNEL 则使用该频道,否则使用 IRC_CHANNEL 中的第一个频道。
运行网关
kopi gateway start
使用 kopi gateway status 查看状态——IRC 连接状态会在其中报告,包括仅使用环境变量的配置。
注意事项
- 较长的 agent 回复会自动拆分为多条
PRIVMSG行,以符合 IRC 行长度限制(max_message_length,协议开销后默认为 450 字节)。 - 该 adapter 会为每个服务器+昵称组合获取限定作用域的凭据锁,因此两个 Kopi Agent 配置文件不会争夺同一个 IRC 身份。