IRC Channel

Classic IRC protocol with TLS support

The IRC channel connects NullClaw to IRC servers using the classic IRC protocol with optional TLS encryption.

Features

• TLS/SSL support for secure connections
• SASL PLAIN authentication
• NickServ identification
• Multi-channel support
• Nick collision handling
• Allowlist-based access control
• Plain text output (no markdown)
• Channel and DM support

Configuration

Add IRC to your config.json:

{
  "channels": {
    "irc": {
      "accounts": {
        "main": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "nullclaw_bot",
          "username": "nullclaw",
          "channels": ["#bots", "#nullclaw"],
          "allow_from": ["alice", "bob"],
          "tls": true,
          "server_password": null,
          "nickserv_password": null,
          "sasl_password": null
        }
      }
    }
  }
}

Configuration Options

host · string · required

IRC server hostname (e.g., irc.libera.chat, irc.oftc.net)

port · integer · required

IRC server port. Common values:

• 6697 — TLS/SSL (recommended)
• 6667 — Plain text
• 7000 — Alternative TLS port

nick · string · required

Bot’s nickname. If taken, NullClaw appends _ automatically.

username · string · default: "nick"

IRC username (ident). Defaults to nickname if not specified.

channels · string[] · required

List of channels to join (e.g., ["#bots", "#general"]). Must include # prefix.

allow_from · string[] · default: "[]"

List of allowed IRC nicks. Empty list = deny all. Use "*" to allow everyone (not recommended).

Case-insensitive matching.

tls · boolean · default: "true"

Enable TLS/SSL encryption. Highly recommended for security.

server_password · string · default: "null"

Server password (sent with PASS command). Required by some servers.

nickserv_password · string · default: "null"

NickServ identification password. Used to authenticate registered nicks.

sasl_password · string · default: "null"

SASL PLAIN authentication password. More secure than NickServ for supported servers.

account_id · string · default: "default"

Account identifier for multi-account setups

Setup Guide

1. Choose an IRC Server

   Popular IRC networks:

   • Libera.Chat (irc.libera.chat:6697) — FOSS projects
   • OFTC (irc.oftc.net:6697) — Community support
   • EFnet (irc.efnet.org:6697) — Original IRC network
   • Rizon (irc.rizon.net:6697) — Anime/gaming communities
2. Register Your Nickname (Optional)

   Connect with an IRC client and register:

   /msg NickServ REGISTER <password> <email>
   /msg NickServ VERIFY REGISTER <nick> <code>
   

   This prevents others from using your bot’s nick.

3. Configure NullClaw

   Add IRC to ~/.nullclaw/config.json:

   {
     "channels": {
       "irc": {
         "accounts": {
           "main": {
             "host": "irc.libera.chat",
             "port": 6697,
             "nick": "nullclaw_bot",
             "channels": ["#bots"],
             "allow_from": ["your_nick"],
             "tls": true,
             "nickserv_password": "your_password"
           }
         }
       }
     }
   }
   
4. Join Test Channels

   Start with low-traffic channels:

   • #bots — Test bots here first
   • ##test — General testing
   • Your own channel: /join #nullclaw_test
5. Start NullClaw

   Run nullclaw and the bot will:

   1. Connect to the IRC server
   2. Authenticate (if configured)
   3. Join specified channels
   4. Respond to messages from allowed nicks

Authentication Methods

SASL PLAIN (Recommended)

{
  "host": "irc.libera.chat",
  "port": 6697,
  "nick": "nullclaw_bot",
  "sasl_password": "your_password",
  "tls": true
}

SASL authenticates before joining channels, preventing impersonation.

NickServ Identification

{
  "host": "irc.libera.chat",
  "port": 6697,
  "nick": "nullclaw_bot",
  "nickserv_password": "your_password",
  "tls": true
}

Bot identifies after connecting via:

/msg NickServ IDENTIFY <password>

Server Password

{
  "host": "irc.example.com",
  "port": 6667,
  "server_password": "server_pass"
}

Some servers require a password on connection.

TLS Configuration

Secure Connection (Recommended)

{
  "host": "irc.libera.chat",
  "port": 6697,
  "tls": true
}

Use port 6697 for TLS.

Plain Text Connection

{
  "host": "irc.example.com",
  "port": 6667,
  "tls": false
}

Not recommended unless necessary.

Message Format

IRC output is plain text only (no markdown, no code fences):

• No triple backticks
• No tables
• No HTML/XML tags
• Single blank line separates blocks
• Short lines, concise responses

The channel automatically injects this context for the LLM:

[context: you are responding over IRC. Plain text only. No markdown, 
no tables, no XML/HTML tags. Never use triple backtick code fences. 
Use a single blank line to separate blocks instead. Be terse and concise. 
Use short lines. Avoid walls of text.]

Message Limits

IRC enforces a 512 byte limit per message (including protocol overhead). NullClaw:

• Reserves 64 bytes for sender prefix (:nick!user@host)
• Splits at ~448 bytes safe boundary
• Respects UTF-8 character boundaries

Nick Collision Handling

If the nickname is already in use:

1. NullClaw appends _: nullclaw_bot → nullclaw_bot_
2. Retries up to 5 times: nullclaw_bot__, nullclaw_bot___, etc.
3. Fails after 5 attempts

To avoid collisions, register your nick with NickServ.

Channel vs DM Behavior

Channel Messages

Bot replies in the channel:

<alice> @nullclaw_bot hello
<nullclaw_bot> Hi alice! How can I help?

Direct Messages

Bot replies via DM:

/msg nullclaw_bot hello
<nullclaw_bot> Hi! How can I help?

Multiple Servers

Connect to multiple IRC networks:

{
  "channels": {
    "irc": {
      "accounts": {
        "libera": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "nullclaw",
          "channels": ["#bots"]
        },
        "oftc": {
          "host": "irc.oftc.net",
          "port": 6697,
          "nick": "nullclaw",
          "channels": ["#test"]
        }
      }
    }
  }
}

Service Bot Filtering

NullClaw automatically ignores messages from IRC service bots:

• NickServ
• ChanServ
• BotServ
• MemoServ

Troubleshooting

Connection Refused

1. Verify host and port are correct
2. Check firewall/proxy settings
3. Try alternative ports: 6697, 6667, 7000
4. Test with standard IRC client first

Nickname Already in Use

1. Choose a unique nickname
2. Register your nick with NickServ
3. Configure nickserv_password or sasl_password
4. Kill ghost sessions: /msg NickServ GHOST <nick> <password>

Authentication Failed

1. Verify password is correct
2. Check that nick is registered
3. For SASL: ensure server supports SASL PLAIN
4. For NickServ: wait for NickServ IDENTIFY confirmation
5. Check logs: nullclaw --log-level debug

Bot Not Responding

1. Verify sender nick is in allow_from
2. Check bot has joined the channel: /whois nullclaw_bot
3. Ensure channel allows bots (check channel modes)
4. Test with DM first to isolate channel issues

TLS Handshake Failed

1. Verify server supports TLS on the specified port
2. Try a different TLS port (6697, 7000)
3. Check for certificate issues
4. Fallback to plain text temporarily for debugging:
   {
     "port": 6667,
     "tls": false
   }
   

Message Truncation

1. This is normal — IRC has a 512 byte limit
2. NullClaw automatically splits messages
3. Adjust agent prompt to be more concise for IRC

Source Code

Implementation: src/channels/irc.zig