ii-IRC: Event-Driven IRC for AI Agents
ii writes all channel activity to plain files. A watcher script monitors for mentions and triggers OpenClaw system events. Responses are sent by writing to a FIFO.
Architecture
CODEBLOCK0
Quick Setup
1. Install ii
ii is in most package managers. On Arch: pacman -S ii. On Debian/Ubuntu: apt install ii. Or build from suckless.org.
2. Create scripts
Run the bundled setup script (creates ~/irc/irc.sh and ~/irc/watch-daemon.sh):
CODEBLOCK1
Or create them manually — see scripts/irc.sh.template and scripts/watch-daemon.sh.template.
3. Create systemd user services (recommended)
For auto-start on boot:
CODEBLOCK2
Sending Messages
CODEBLOCK3
Important: ii splits long messages at byte boundaries, which can break mid-word or mid-UTF8 character. Keep messages under ~400 characters. For longer content, split into multiple messages with brief pauses between them.
Reading Context
CODEBLOCK4
Never read the entire out file — it grows indefinitely. Always use tail with a limit.
How Mention Detection Works
- 1.
watch-daemon.sh runs tail -F on the channel's out file - Each new line is checked (case-insensitive) for the bot's nick
- Own messages and join/part notices are skipped
- On match → INLINECODE11
- OpenClaw wakes and can respond via the
in FIFO
This is event-driven — zero polling, instant response, minimal resource usage.
Joining Multiple Channels
ii supports multiple channels on the same server. For each additional channel:
CODEBLOCK5
To watch multiple channels, either run separate watcher instances or modify watch-daemon.sh to monitor multiple out files.
Troubleshooting
- - Not connecting: Check
ii is running (pgrep -f "ii -s"), verify server/port - Not joining channel: The
in FIFO must exist; check ExecStartPost timing (increase sleep if needed) - Mentions not triggering: Verify watcher is running (
pgrep -f watch-daemon), check nick matches - Messages splitting weirdly: Shorten messages; ii has a ~512 byte IRC protocol limit
- Reconnection: systemd
Restart=always handles this; ii exits on disconnect, systemd restarts it
ii-IRC: 面向AI智能体的事件驱动IRC
ii将所有频道活动写入纯文本文件。一个监视器脚本监控提及并触发OpenClaw系统事件。通过写入FIFO来发送响应。
架构
~/irc/
├── irc.sh # 管理脚本（启动/停止/状态/发送）
├── watch-daemon.sh # 提及监视器 → openclaw系统事件
└── <服务器>/
└── <频道>/
├── in # FIFO - 在此写入以发送消息
└── out # 所有频道消息的追加日志
快速设置
1. 安装ii
ii在大多数包管理器中可用。在Arch上：pacman -S ii。在Debian/Ubuntu上：apt install ii。或者从suckless.org构建。
2. 创建脚本
运行捆绑的设置脚本（创建~/irc/irc.sh和~/irc/watch-daemon.sh）：
bash
bash scripts/setup.sh --server irc.example.org --port 6667 --nick MyBot --channel #mychannel
或者手动创建——参见scripts/irc.sh.template和scripts/watch-daemon.sh.template。
3. 创建systemd用户服务（推荐）
用于开机自启：
bash
mkdir -p ~/.config/systemd/user
IRC连接服务
cat > ~/.config/systemd/user/irc-bot.service << EOF
[Unit]
Description=IRC连接 (ii)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/ii -s 服务器 -p 端口 -n 昵称 -i %h/irc
ExecStartPost=/bin/bash -c sleep 3 && echo /j 频道 > %h/irc/服务器/in
Restart=always
RestartSec=10
[Install]
WantedBy=default.target
EOF
提及监视器服务
cat > ~/.config/systemd/user/irc-watcher.service << EOF
[Unit]
Description=IRC提及监视器
After=irc-bot.service
Wants=irc-bot.service
[Service]
Type=simple
ExecStart=%h/irc/watch-daemon.sh
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
EOF
替换服务文件中的服务器、端口、昵称、频道，然后：
systemctl --user daemon-reload
systemctl --user enable --now irc-bot.service irc-watcher.service
发送消息
bash
通过管理脚本
~/irc/irc.sh send 你好，世界！
或直接写入FIFO
echo 你好，世界！ > ~/irc/<服务器>/<频道>/in
重要提示： ii会在字节边界处分割长消息，这可能会在单词中间或UTF-8字符中间断开。保持消息在约400个字符以内。对于较长的内容，分割成多条消息并在它们之间短暂停顿。
读取上下文
bash
最后N条消息（节省token）
tail -n 20 ~/irc/<服务器>/<频道>/out
快速状态（最后5条消息）
~/irc/irc.sh status
永远不要读取整个out文件——它会无限增长。始终使用带限制的tail。
提及检测的工作原理
- 1. watch-daemon.sh在频道的out文件上运行tail -F
- 检查每条新行（不区分大小写）是否包含机器人的昵称
- 跳过自己的消息和加入/离开通知
- 匹配时 → openclaw system event --text IRC提及：<消息> --mode now
- OpenClaw被唤醒并可以通过in FIFO响应
这是事件驱动的——零轮询，即时响应，最小资源使用。
加入多个频道
ii支持同一服务器上的多个频道。对于每个额外频道：
bash
echo /j #其他频道 > ~/irc/<服务器>/in
要监视多个频道，可以运行单独的监视器实例或修改watch-daemon.sh以监视多个out文件。
故障排除
- - 无法连接： 检查ii是否在运行（pgrep -f ii -s），验证服务器/端口
- 无法加入频道： in FIFO必须存在；检查ExecStartPost的时机（如有需要增加sleep时间）
- 提及未触发： 验证监视器是否在运行（pgrep -f watch-daemon），检查昵称是否匹配
- 消息分割异常： 缩短消息；ii有约512字节的IRC协议限制
- 重新连接： systemd的Restart=always处理此问题；ii在断开连接时退出，systemd会重启它
