OpenClaw IRC 연동 가이드: 5분 만에 봇 설정하기

IRC를 사용하여 OpenClaw를 클래식 채널(#room)이나 다이렉트 메시지에서 활용해 보세요. IRC는 확장 플러그인으로 제공되지만, 메인 설정 파일의 channels.irc 항목에서 간편하게 관리할 수 있어요.

오래된 프로토콜인 IRC를 현대적인 AI 워크플로우에 연결하는 과정이 복잡하게 느껴질 수 있지만, OpenClaw를 사용하면 보안과 권한 관리를 체계적으로 구성할 수 있습니다. 지금부터 그 방법을 하나씩 설명해 드릴게요.

IRC

빠른 시작 (Quick start)

먼저 ~/.openclaw/openclaw.json에서 IRC 설정을 활성화해야 해요. 최소한 다음 항목들은 설정해 주세요.

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

설정을 마쳤다면 Gateway를 시작하거나 재시작하세요.

openclaw gateway run

보안 기본값 (Security defaults)

channels.irc.dmPolicy는 기본적으로 "pairing"으로 설정되어 있어요.
channels.irc.groupPolicy는 기본적으로 "allowlist"예요.
groupPolicy="allowlist"를 사용할 때는 channels.irc.groups를 통해 허용할 채널을 정의해야 해요.
일반 텍스트 전송을 의도적으로 허용하는 경우가 아니라면 TLS(channels.irc.tls=true)를 사용하는 것이 좋아요.

액세스 제어 (Access control)

IRC 채널에는 두 가지 별도의 ‘게이트’가 있어요.

채널 액세스 (groupPolicy + groups): 봇이 채널의 메시지를 수락할지 여부를 결정해요.
발신자 액세스 (groupAllowFrom / 채널별 groups["#channel"].allowFrom): 채널 내에서 누가 봇을 트리거할 수 있는지 결정해요.

설정 키 목록:

DM allowlist (DM 발신자 액세스): channels.irc.allowFrom
Group sender allowlist (채널 발신자 액세스): channels.irc.groupAllowFrom
채널별 제어 (채널 + 발신자 + 멘션 규칙): channels.irc.groups["#channel"]
channels.irc.groupPolicy="open"은 설정되지 않은 채널도 허용해요. (기본적으로 멘션 기반 필터링은 유지돼요)

Allowlist 항목에는 안정적인 발신자 식별 정보(nick!user@host)를 사용하는 것이 좋아요. 단순 닉네임 매칭은 변경될 위험이 있어서 channels.irc.dangerouslyAllowNameMatching: true일 때만 작동해요.

자주 겪는 실수: `allowFrom`은 채널이 아니라 DM용이에요

만약 로그에 다음과 같은 내용이 보인다면 주의가 필요해요.

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

이것은 발신자가 그룹/채널 메시지에 대해 허용되지 않았다는 뜻이에요. 다음 중 한 가지 방법으로 해결할 수 있어요.

channels.irc.groupAllowFrom 설정 (모든 채널에 전역 적용)
채널별 발신자 allowlist 설정: channels.irc.groups["#channel"].allowFrom

예시 (#tuirc-dev 채널의 모든 사용자가 봇과 대화할 수 있도록 허용):

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

답장 트리거 (멘션) (Reply triggering (mentions))

채널과 발신자가 모두 허용되었더라도, OpenClaw는 그룹 환경에서 기본적으로 멘션 기반 필터링을 수행해요.

즉, 메시지에 봇을 태그하는 패턴이 포함되지 않으면 drop channel … (missing-mention) 같은 로그가 남으면서 봇이 응답하지 않을 수 있어요.

IRC 채널에서 멘션 없이도 봇이 답장하게 하려면 해당 채널의 멘션 필터링을 비활성화하세요.

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

또는 모든 IRC 채널을 허용하면서(별도의 채널 allowlist 없이) 멘션 없이 답장하게 하려면 이렇게 설정하세요.

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

보안 유의 사항 (공개 채널 권장) (Security note (recommended for public channels))

공개 채널에서 allowFrom: ["*"]를 설정하면 누구나 봇에게 프롬프트를 보낼 수 있어요. 위험을 줄이기 위해 해당 채널에서 사용할 수 있는 도구를 제한하는 것이 좋습니다.

채널 내 모든 사용자에게 동일한 도구 제한 적용

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

발신자별로 다른 도구 권한 부여 (관리자에게 더 많은 권한 부여)

toolsBySender를 사용하면 일반 사용자("*")에게는 엄격한 정책을 적용하고, 본인의 닉네임에는 더 느슨한 정책을 적용할 수 있어요.

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

참고 사항:

toolsBySender 키에는 IRC 발신자 식별 값인 id: 접두사를 사용해야 해요. 더 강력한 매칭을 위해 id:eigen 또는 id:eigen!~eigen@174.127.248.171 형식을 사용하세요.
접두사가 없는 기존 키도 여전히 허용되며 id:와 동일하게 매칭돼요.
첫 번째로 매칭되는 발신자 정책이 적용되며, "*"는 매칭되는 것이 없을 때 사용하는 와일드카드예요.

그룹 액세스와 멘션 필터링의 상호작용에 대해 더 자세히 알고 싶다면 /channels/groups 문서를 확인해 보세요.

NickServ

연결 후 NickServ를 통해 인증하려면 다음 설정을 사용하세요.

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

연결 시 일회성 등록을 할 수도 있어요.

{
  channels: {
    irc: {
      nickserv: {
        register: true,
        registerEmail: "bot@example.com",
      },
    },
  },
}

닉네임 등록이 완료된 후에는 반복적인 등록 시도를 방지하기 위해 register 설정을 꺼주세요.

환경 변수 (Environment variables)

기본 계정 설정에서 다음 환경 변수들을 지원해요.

IRC_HOST
IRC_PORT
IRC_TLS
IRC_NICK
IRC_USERNAME
IRC_REALNAME
IRC_PASSWORD
IRC_CHANNELS (쉼표로 구분)
IRC_NICKSERV_PASSWORD
IRC_NICKSERV_REGISTER_EMAIL

문제 해결 (Troubleshooting)

봇이 연결은 되었는데 채널에서 답장하지 않는다면, channels.irc.groups 설정과 멘션 필터링으로 인해 메시지가 누락(missing-mention)되고 있지 않은지 확인해 보세요. 핑 없이 답장하길 원한다면 해당 채널에 requireMention:false를 설정해야 해요.
로그인에 실패한다면 닉네임 사용 가능 여부와 서버 비밀번호를 확인해 보세요.
커스텀 네트워크에서 TLS 실패가 발생한다면 호스트/포트 및 인증서 설정을 점검해 보세요.

Channels Overview — 지원되는 모든 채널 안내
Pairing — DM 인증 및 페어링 흐름
Groups — 그룹 채팅 동작 및 멘션 필터링
Channel Routing — 메시지 세션 라우팅
Security — 액세스 모델 및 보안 강화

AI Setup Assistant

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.