IRC | Docs | OpenClaw

Use IRC quando quiser o OpenClaw em canais clássicos (#sala) e mensagens diretas. O IRC funciona como plugin de extensão, mas é configurado no config principal em channels.irc.

Início rápido

Habilite a configuração IRC em ~/.openclaw/openclaw.json.
Defina ao menos:

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

Inicie/reinicie o gateway:

openclaw gateway run

Padrões de segurança

channels.irc.dmPolicy padrão é "pairing".
channels.irc.groupPolicy padrão é "allowlist".
Com groupPolicy="allowlist", defina channels.irc.groups para especificar canais permitidos.
Use TLS (channels.irc.tls=true) a menos que você aceite intencionalmente transporte em texto puro.

Controle de acesso

Existem duas “comportas” separadas para canais IRC:

Acesso ao canal (groupPolicy + groups): se o bot aceita mensagens de um canal.
Acesso de remetente (groupAllowFrom / groups["#canal"].allowFrom por canal): quem pode acionar o bot dentro daquele canal.

Chaves de configuração:

Allowlist de DM (acesso de remetente em DM): channels.irc.allowFrom
Allowlist de remetentes de grupo (acesso de remetente em canal): channels.irc.groupAllowFrom
Controles por canal (canal + remetente + regras de menção): channels.irc.groups["#canal"]
channels.irc.groupPolicy="open" permite canais não configurados (ainda com gating de menção por padrão)

As entradas da allowlist devem usar identidades de remetente estáveis (nick!user@host). A correspondência por nick simples é mutável e só é habilitada quando channels.irc.dangerouslyAllowNameMatching: true.

Armadilha comum: `allowFrom` é para DMs, não para canais

Se aparecer nos logs algo como:

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

…significa que o remetente não foi autorizado para mensagens de grupo/canal. Corrija definindo:

channels.irc.groupAllowFrom (global para todos os canais), ou
allowlists de remetente por canal: channels.irc.groups["#canal"].allowFrom

Exemplo (permitir qualquer pessoa em #tuirc-dev falar com o bot):

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

Acionamento de resposta (menções)

Mesmo que um canal seja permitido (via groupPolicy + groups) e o remetente seja autorizado, o OpenClaw usa gating de menção por padrão em contextos de grupo.

Isso significa que mensagens podem aparecer como drop channel … (missing-mention) nos logs, a menos que contenham um padrão de menção que corresponda ao bot.

Para fazer o bot responder em um canal IRC sem exigir menção, desabilite o gating de menção para aquele canal:

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

Ou para permitir todos os canais IRC (sem allowlist por canal) e responder sem menções:

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

Nota de segurança (recomendado para canais públicos)

Se você usar allowFrom: ["*"] em um canal público, qualquer pessoa pode enviar prompts ao bot. Para reduzir riscos, restrinja as ferramentas para aquele canal.

Mesmas ferramentas para todos no canal

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

Ferramentas diferentes por remetente (dono tem mais poder)

Use toolsBySender para aplicar uma política mais restritiva para "*" e uma mais permissiva para seu nick:

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

Observações:

Chaves de toolsBySender devem usar id: para valores de identidade de remetente IRC: id:eigen ou id:[email protected] para correspondência mais forte.
Chaves legadas sem prefixo ainda são aceitas e correspondem apenas como id:.
A primeira política de remetente correspondente vence; "*" é o fallback curinga.

Para mais detalhes sobre acesso a grupo vs gating de menção (e como interagem), veja: /channels/groups.

NickServ

Para identificar com NickServ após a conexão:

{
  "channels": {
    "irc": {
      "nickserv": {
        "enabled": true,
        "service": "NickServ",
        "password": "sua-senha-do-nickserv"
      }
    }
  }
}

Registro único opcional na conexão:

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

Desabilite register após o nick ser registrado para evitar tentativas repetidas de REGISTER.

Variáveis de ambiente

A conta padrão suporta:

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS (separados por vírgula)
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

Resolução de problemas

Se o bot conecta mas nunca responde em canais, verifique channels.irc.groups e se o gating de menção está descartando mensagens (missing-mention). Se quiser que ele responda sem pings, defina requireMention:false para o canal.
Se o login falhar, verifique a disponibilidade do nick e a senha do servidor.
Se TLS falhar em uma rede customizada, verifique host/porta e configuração de certificado.