Developer and self-hosted

IRC

Utilisez IRC lorsque vous voulez OpenClaw dans des canaux classiques (#room) et des messages directs. IRC est fourni comme Plugin intégré, mais il est configuré dans la configuration principale sous channels.irc.

Démarrage rapide

Activez la configuration IRC dans ~/.openclaw/openclaw.json.
Définissez au moins :

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

Préférez un serveur IRC privé pour la coordination des bots. Si vous utilisez volontairement un réseau IRC public, les choix courants incluent Libera.Chat, OFTC et Snoonet. Évitez les canaux publics prévisibles pour le trafic de bot ou de canal de coordination d’essaim.

Démarrez/redémarrez le Gateway :

openclaw gateway run

Paramètres de sécurité par défaut

IRC utilise des sockets TCP/TLS bruts en dehors du routage par proxy direct géré par l’opérateur OpenClaw. Dans les déploiements qui exigent que toute sortie passe par ce proxy direct, définissez channels.irc.enabled=false sauf si la sortie IRC directe est explicitement approuvée.
channels.irc.dmPolicy vaut par défaut "pairing".
channels.irc.groupPolicy vaut par défaut "allowlist".
Avec groupPolicy="allowlist", définissez channels.irc.groups pour définir les canaux autorisés.
Utilisez TLS (channels.irc.tls=true) sauf si vous acceptez volontairement le transport en texte clair.

Contrôle d’accès

Il existe deux « portes » distinctes pour les canaux IRC :

Accès au canal (groupPolicy + groups) : si le bot accepte ou non les messages d’un canal.
Accès de l’expéditeur (groupAllowFrom / groups["#channel"].allowFrom par canal) : qui est autorisé à déclencher le bot dans ce canal.

Clés de configuration :

Liste d’autorisation des DM (accès des expéditeurs DM) : channels.irc.allowFrom
Liste d’autorisation des expéditeurs de groupe (accès des expéditeurs du canal) : channels.irc.groupAllowFrom
Contrôles par canal (règles de canal, d’expéditeur et de mention) : channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" autorise les canaux non configurés (toujours soumis à une mention par défaut)

Les entrées de liste d’autorisation doivent utiliser des identités d’expéditeur stables (nick!user@host). La correspondance par simple pseudo est mutable et n’est activée que lorsque channels.irc.dangerouslyAllowNameMatching: true.

Piège courant : `allowFrom` concerne les DM, pas les canaux

Si vous voyez des journaux comme :

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

...cela signifie que l’expéditeur n’était pas autorisé pour les messages de groupe/canal. Corrigez-le soit en :

définissant channels.irc.groupAllowFrom (global pour tous les canaux), soit en
définissant des listes d’autorisation d’expéditeurs par canal : channels.irc.groups["#channel"].allowFrom

Exemple (autoriser toute personne dans #tuirc-dev à parler au bot) :

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

Déclenchement des réponses (mentions)

Même si un canal est autorisé (via groupPolicy + groups) et que l’expéditeur est autorisé, OpenClaw applique par défaut une porte par mention dans les contextes de groupe.

Cela signifie que vous pouvez voir des journaux comme drop channel … (missing-mention) sauf si le message inclut un motif de mention correspondant au bot.

Pour que le bot réponde dans un canal IRC sans nécessiter de mention, désactivez la porte par mention pour ce canal :

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

Ou, pour autoriser tous les canaux IRC (sans liste d’autorisation par canal) tout en répondant sans mentions :

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

Note de sécurité (recommandée pour les canaux publics)

Si vous autorisez allowFrom: ["*"] dans un canal public, n’importe qui peut envoyer une invite au bot. Pour réduire le risque, restreignez les outils pour ce canal.

Mêmes outils pour tout le monde dans le canal

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

Outils différents par expéditeur (le propriétaire obtient plus de pouvoir)

Utilisez toolsBySender pour appliquer une politique plus stricte à "*" et une plus souple à votre pseudo :

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

Remarques :

Les clés toolsBySender doivent utiliser id: pour les valeurs d’identité d’expéditeur IRC : id:eigen ou id:[email protected] pour une correspondance plus forte.
Les anciennes clés sans préfixe sont toujours acceptées et correspondent uniquement comme id:.
La première politique d’expéditeur correspondante l’emporte ; "*" est le repli générique.

Pour en savoir plus sur l’accès aux groupes par rapport à la porte par mention (et leur interaction), consultez : /channels/groups.

NickServ

Pour s’identifier auprès de NickServ après la connexion :

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

Inscription unique facultative à la connexion :

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

Désactivez register après l’enregistrement du pseudo afin d’éviter les tentatives REGISTER répétées.

Variables d’environnement

Le compte par défaut prend en charge :

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS (séparés par des virgules)
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

IRC_HOST ne peut pas être défini depuis un fichier .env d’espace de travail ; consultez Fichiers .env d’espace de travail.

Dépannage

Si le bot se connecte mais ne répond jamais dans les canaux, vérifiez channels.irc.groups et si la porte par mention supprime les messages (missing-mention). Si vous voulez qu’il réponde sans mentions, définissez requireMention:false pour le canal.
Si la connexion échoue, vérifiez la disponibilité du pseudo et le mot de passe du serveur.
Si TLS échoue sur un réseau personnalisé, vérifiez l’hôte/le port et la configuration du certificat.

Connexe

Vue d’ensemble des canaux — tous les canaux pris en charge
Appairage — authentification DM et flux d’appairage
Groupes — comportement des discussions de groupe et porte par mention
Routage des canaux — routage de session pour les messages
Sécurité — modèle d’accès et durcissement

# Démarrage rapide

# Paramètres de sécurité par défaut

# Contrôle d’accès

# Piège courant : allowFrom concerne les DM, pas les canaux

# Déclenchement des réponses (mentions)

# Note de sécurité (recommandée pour les canaux publics)

# Mêmes outils pour tout le monde dans le canal

# Outils différents par expéditeur (le propriétaire obtient plus de pouvoir)

# NickServ

# Variables d’environnement

# Dépannage

# Connexe