IRC | Docs | OpenClaw

Usa IRC quando vuoi OpenClaw nei canali classici (#room) e nei messaggi diretti. IRC e distribuito come plugin estensione, ma si configura nel config principale sotto channels.irc.

Setup rapido

Abilita la configurazione IRC in ~/.openclaw/openclaw.json.
Imposta almeno:

{
  "channels": {
    "irc": {
      "enabled": true,
      "host": "irc.libera.chat",
      "port": 6697,
      "tls": true,
      "nick": "openclaw-bot",
      "channels": ["#openclaw"]
    }
  }
}

Avvia/riavvia il gateway:

openclaw gateway run

Impostazioni di sicurezza predefinite

channels.irc.dmPolicy e "pairing" per impostazione predefinita.
channels.irc.groupPolicy e "allowlist" per impostazione predefinita.
Con groupPolicy="allowlist", imposta channels.irc.groups per definire i canali consentiti.
Usa TLS (channels.irc.tls=true) a meno che tu non accetti intenzionalmente il trasporto in chiaro.

Controllo degli accessi

Ci sono due “gate” separati per i canali IRC:

Accesso al canale (groupPolicy + groups): se il bot accetta messaggi da un canale.
Accesso del mittente (groupAllowFrom / per canale groups["#channel"].allowFrom): chi puo attivare il bot all’interno di quel canale.

Chiavi di configurazione:

Allowlist DM (accesso mittente DM): channels.irc.allowFrom
Allowlist mittenti gruppi (accesso mittente canale): channels.irc.groupAllowFrom
Controlli per canale (canale + mittente + regole menzione): channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" consente canali non configurati (comunque con gating menzione per impostazione predefinita)

Le voci dell’allowlist dovrebbero usare identita stabili del mittente (nick!user@host). Il matching per solo nick e mutabile e attivo solo quando channels.irc.dangerouslyAllowNameMatching: true.

Errore comune: `allowFrom` e per i DM, non per i canali

Se nei log vedi:

irc: drop group sender alice!ident@host (policy=allowlist)

…significa che il mittente non era autorizzato per i messaggi di gruppo/canale. Correggi tramite:

impostando channels.irc.groupAllowFrom (globale per tutti i canali), oppure
impostando allowlist mittenti per canale: channels.irc.groups["#channel"].allowFrom

Esempio (consenti a chiunque in #tuirc-dev di parlare con il bot):

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": { allowFrom: ["*"] },
      },
    },
  },
}

Attivazione risposte (menzioni)

Anche se un canale e consentito (tramite groupPolicy + groups) e il mittente e autorizzato, OpenClaw applica il gating menzione nei contesti di gruppo per impostazione predefinita.

Questo significa che potresti vedere nei log drop channel … (missing-mention) a meno che il messaggio non includa un pattern di menzione che corrisponda al bot.

Per far rispondere il bot in un canale IRC senza bisogno di una menzione, disabilita il gating menzione per quel canale:

{
  channels: {
    irc: {
      groupPolicy: "allowlist",
      groups: {
        "#tuirc-dev": {
          requireMention: false,
          allowFrom: ["*"],
        },
      },
    },
  },
}

Oppure per consentire tutti i canali IRC (senza allowlist per canale) rispondendo senza menzioni:

{
  channels: {
    irc: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: false, allowFrom: ["*"] },
      },
    },
  },
}

Nota sulla sicurezza (consigliata per canali pubblici)

Se consenti allowFrom: ["*"] in un canale pubblico, chiunque puo interrogare il bot. Per ridurre il rischio, limita gli strumenti per quel canale.

Stessi strumenti per tutti nel canale

{
  channels: {
    irc: {
      groups: {
        "#tuirc-dev": {
          allowFrom: ["*"],
          tools: {
            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
          },
        },
      },
    },
  },
}

Strumenti diversi per mittente (il proprietario ha piu permessi)

Usa toolsBySender per applicare una policy piu restrittiva a "*" e una piu permissiva al tuo nick:

{
  channels: {
    irc: {
      groups: {
        "#tuirc-dev": {
          allowFrom: ["*"],
          toolsBySender: {
            "*": {
              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
            },
            "id:eigen": {
              deny: ["gateway", "nodes", "cron"],
            },
          },
        },
      },
    },
  },
}

Note:

Le chiavi toolsBySender dovrebbero usare id: per i valori di identita del mittente IRC: id:eigen o id:[email protected] per un matching piu robusto.
Le chiavi legacy senza prefisso sono ancora accettate e corrispondono solo come id:.
La prima policy del mittente corrispondente vince; "*" e il fallback wildcard.

Per maggiori informazioni sull’accesso ai gruppi e il gating menzione (e come interagiscono), vedi: /channels/groups.

NickServ

Per identificarsi con NickServ dopo la connessione:

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

Registrazione opzionale una tantum alla connessione:

{
  "channels": {
    "irc": {
      "nickserv": {
        "register": true,
        "registerEmail": "[email protected]"
      }
    }
  }
}

Disabilita register dopo che il nick e registrato per evitare tentativi REGISTER ripetuti.

Variabili d’ambiente

L’account predefinito supporta:

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS (separati da virgola)
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

Risoluzione problemi

Se il bot si connette ma non risponde mai nei canali, verifica channels.irc.groups e se il gating menzione sta scartando i messaggi (missing-mention). Se vuoi che risponda senza ping, imposta requireMention:false per il canale.
Se il login fallisce, verifica la disponibilita del nick e la password del server.
Se il TLS fallisce su una rete personalizzata, verifica host/porta e configurazione del certificato.