IRC

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

빠른 시작

1. ~/.openclaw/openclaw.json에서 IRC 설정을 활성화합니다.
2. 최소한 다음을 설정합니다.

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

3. Gateway를 시작/재시작합니다.

openclaw gateway run

​

보안 기본값

• IRC는 OpenClaw 운영자 관리형 포워드 프록시 라우팅 외부에서 원시 TCP/TLS 소켓을 사용합니다. 모든 이그레스가 해당 포워드 프록시를 거쳐야 하는 배포에서는 직접 IRC 이그레스가 명시적으로 승인되지 않은 한 channels.irc.enabled=false를 설정하세요.
• channels.irc.dmPolicy의 기본값은 "pairing"입니다.
• channels.irc.groupPolicy의 기본값은 "allowlist"입니다.
• groupPolicy="allowlist"를 사용하는 경우, 허용된 채널을 정의하려면 channels.irc.groups를 설정하세요.
• 평문 전송을 의도적으로 허용하는 경우가 아니라면 TLS(channels.irc.tls=true)를 사용하세요.

​

접근 제어

1. 채널 접근(groupPolicy + groups): 봇이 해당 채널의 메시지를 아예 수락할지 여부입니다.
2. 보낸 사람 접근(groupAllowFrom / 채널별 groups["#channel"].allowFrom): 해당 채널 안에서 누가 봇을 트리거할 수 있는지입니다.

• DM 허용 목록(DM 보낸 사람 접근): channels.irc.allowFrom
• 그룹 보낸 사람 허용 목록(채널 보낸 사람 접근): channels.irc.groupAllowFrom
• 채널별 제어(채널 + 보낸 사람 + 멘션 규칙): channels.irc.groups["#channel"]
• channels.irc.groupPolicy="open"은 구성되지 않은 채널을 허용합니다(그래도 기본적으로 멘션 게이트가 적용됨).

​

흔한 함정: allowFrom은 채널이 아니라 DM용입니다

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

• channels.irc.groupAllowFrom 설정(모든 채널에 전역 적용) 또는
• 채널별 보낸 사람 허용 목록 설정: channels.irc.groups["#channel"].allowFrom

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

​

응답 트리거(멘션)

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

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

​

보안 참고 사항(공개 채널 권장)

​

채널의 모든 사람에게 동일한 도구 적용

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

​

보낸 사람별로 다른 도구 적용(소유자에게 더 많은 권한 부여)

{
  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:를 사용해야 합니다. 더 강한 매칭을 위해 id:eigen 또는 id:eigen!~eigen@174.127.248.171를 사용할 수 있습니다.
• 레거시 접두사 없는 키도 여전히 허용되며, id:로만 매칭됩니다.
• 처음 매칭되는 보낸 사람 정책이 적용됩니다. "*"는 와일드카드 폴백입니다.

​

NickServ

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

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

​

환경 변수

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

​

문제 해결

• 봇이 연결되지만 채널에서 전혀 응답하지 않는 경우, channels.irc.groups 및 멘션 게이트가 메시지를 드롭하고 있는지(missing-mention) 확인하세요. 핑 없이 응답하게 하려면 해당 채널에 requireMention:false를 설정하세요.
• 로그인이 실패하면 닉네임 사용 가능 여부와 서버 비밀번호를 확인하세요.
• 사용자 지정 네트워크에서 TLS가 실패하면 호스트/포트와 인증서 설정을 확인하세요.

​

관련 문서

• 채널 개요 — 지원되는 모든 채널
• 페어링 — DM 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이트
• 채널 라우팅 — 메시지의 세션 라우팅
• 보안 — 접근 모델 및 강화