IRC | Docs | OpenClaw

Verwende IRC, wenn du OpenClaw in klassischen Kanälen (#room) und Direktnachrichten nutzen möchtest. IRC wird als Erweiterungs-Plugin geliefert, aber in der Hauptkonfiguration unter channels.irc konfiguriert.

Schnellstart

Aktiviere die IRC-Konfiguration in ~/.openclaw/openclaw.json.
Setze mindestens:

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

Starte das Gateway (neu):

openclaw gateway run

Sicherheitsstandards

channels.irc.dmPolicy ist standardmäßig "pairing".
channels.irc.groupPolicy ist standardmäßig "allowlist".
Bei groupPolicy="allowlist" setze channels.irc.groups, um erlaubte Kanäle zu definieren.
Verwende TLS (channels.irc.tls=true), es sei denn, du akzeptierst bewusst Klartexttransport.

Zugriffssteuerung

Es gibt zwei separate „Gates” für IRC-Kanäle:

Kanalzugriff (groupPolicy + groups): ob der Bot überhaupt Nachrichten aus einem Kanal akzeptiert.
Absenderzugriff (groupAllowFrom / pro-Kanal groups["#channel"].allowFrom): wer den Bot innerhalb dieses Kanals auslösen darf.

Konfigurationsschlüssel:

DM-Allowlist (DM-Absenderzugriff): channels.irc.allowFrom
Gruppen-Absender-Allowlist (Kanal-Absenderzugriff): channels.irc.groupAllowFrom
Pro-Kanal-Steuerung (Kanal + Absender + Mention-Regeln): channels.irc.groups["#channel"]
channels.irc.groupPolicy="open" erlaubt unkonfigurierte Kanäle (standardmäßig weiterhin mention-gated)

Allowlist-Einträge sollten stabile Absenderidentitäten verwenden (nick!user@host). Einfaches Nick-Matching ist veränderlich und nur aktiviert wenn channels.irc.dangerouslyAllowNameMatching: true.

Häufiger Fehler: `allowFrom` ist für DMs, nicht für Kanäle

Wenn du Logs wie diese siehst:

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

…bedeutet das, dass der Absender für Gruppen-/Kanal-Nachrichten nicht erlaubt war. Behebe es durch:

Setzen von channels.irc.groupAllowFrom (global für alle Kanäle), oder
Setzen von pro-Kanal-Absender-Allowlists: channels.irc.groups["#channel"].allowFrom

Beispiel (erlaube jedem in #tuirc-dev, mit dem Bot zu sprechen):

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

Antwortauslösung (Mentions)

Selbst wenn ein Kanal erlaubt ist (via groupPolicy + groups) und der Absender erlaubt ist, nutzt OpenClaw standardmäßig Mention-Gating in Gruppenkontexten.

Das bedeutet, du siehst möglicherweise Logs wie drop channel … (missing-mention), es sei denn, die Nachricht enthält ein Mention-Muster, das zum Bot passt.

Um den Bot in einem IRC-Kanal ohne Mention antworten zu lassen, deaktiviere das Mention-Gating für diesen Kanal:

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

Oder um alle IRC-Kanäle zu erlauben (keine pro-Kanal-Allowlist) und dennoch ohne Mentions zu antworten:

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

Sicherheitshinweis (empfohlen für öffentliche Kanäle)

Wenn du allowFrom: ["*"] in einem öffentlichen Kanal erlaubst, kann jeder den Bot prompten. Um das Risiko zu reduzieren, beschränke die Tools für diesen Kanal.

Gleiche Tools für alle im Kanal

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

Verschiedene Tools pro Absender (Besitzer bekommt mehr Rechte)

Verwende toolsBySender, um eine strengere Richtlinie für "*" und eine lockerere für deinen Nick anzuwenden:

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

Hinweise:

toolsBySender-Schlüssel sollten id: für IRC-Absenderidentitätswerte verwenden: id:eigen oder id:[email protected] für stärkeres Matching.
Legacy-Schlüssel ohne Präfix werden weiterhin akzeptiert und nur als id: gematcht.
Die erste passende Absenderrichtlinie gewinnt; "*" ist der Wildcard-Fallback.

Mehr zu Gruppenzugriff vs. Mention-Gating (und wie sie interagieren): /channels/groups.

NickServ

Um sich nach dem Verbinden bei NickServ zu identifizieren:

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

Optionale einmalige Registrierung beim Verbinden:

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

Deaktiviere register nach der Nick-Registrierung, um wiederholte REGISTER-Versuche zu vermeiden.

Umgebungsvariablen

Standardkonto unterstützt:

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS (kommagetrennt)
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

Fehlerbehebung

Wenn der Bot sich verbindet, aber nie in Kanälen antwortet, überprüfe channels.irc.groups und ob Mention-Gating Nachrichten verwirft (missing-mention). Wenn er ohne Pings antworten soll, setze requireMention:false für den Kanal.
Wenn der Login fehlschlägt, überprüfe die Nick-Verfügbarkeit und das Server-Passwort.
Wenn TLS in einem benutzerdefinierten Netzwerk fehlschlägt, überprüfe Host/Port und die Zertifikatkonfiguration.