트리거 규칙 및 보안

이 페이지에서는 Channel 시스템의 트리거 규칙 설정과 보안 파이프라인 메커니즘을 자세히 설명합니다. 트리거 규칙은 Agent가 언제 답변할지를 결정하고, 보안 파이프라인은 메시지가 Agent에 도달할 수 있는지 여부를 결정합니다.

트리거 규칙

트리거 규칙은 ChannelTriggerConfig를 통해 설정하며, 각 Channel 인스턴스별로 독립적으로 구성할 수 있습니다.

:::info 다이렉트 메시지는 항상 트리거됩니다 트리거 규칙 설정에 관계없이, **다이렉트 메시지(DM)**는 항상 Agent 답변을 트리거합니다. 트리거 규칙은 그룹 채팅의 메시지에만 적용됩니다. :::

all 모드 — 모든 메시지에 답변

Agent가 그룹의 모든 메시지에 대해 답변을 생성합니다.

{
  "mode": "all"
}

적합한 사용 사례:

개인 전용 봇
테스트 환경
참여자가 적은 소규모 그룹

참고: 활발한 다인 그룹에서 이 모드를 사용하면 API 호출이 대량으로 발생합니다. 속도 제한과 함께 사용하는 것이 권장됩니다.

mention 모드 — @멘션 시 답변

Agent가 메시지에서 @멘션될 때만 답변합니다. 트리거되지 않은 메시지는 컨텍스트로 캐시(최대 50개)되어 트리거 메시지와 함께 Agent에 전송되어 그룹 대화 배경을 이해할 수 있습니다.

{
  "mode": "mention",
  "mentionName": "Clawia"
}

적합한 사용 사례:

공유 Discord/Slack 서버
다인 작업 그룹
봇이 너무 자주 답변하지 않기를 원하는 경우

mentionName 필드: 플랫폼에서 봇의 사용자 이름으로 설정하세요. 시스템은 메시지 내용에 @Clawia(대소문자 구분)가 포함되어 있는지 확인하여 트리거 여부를 결정합니다.

keyword 모드 — 키워드 매칭

지정된 키워드가 메시지에 포함될 때 Agent가 답변합니다. 키워드 매칭은 대소문자를 구분하지 않습니다.

{
  "mode": "keyword",
  "keywords": ["help", "assist", "Clawia"]
}

적합한 사용 사례:

사용자가 "help"를 입력할 때 봇을 트리거하는 고객 서비스 시나리오
특정 주제 채널

매칭 규칙: 메시지 내용에 키워드 중 하나라도 포함되면 트리거됩니다. 예를 들어 Please help me look into this 메시지는 키워드 help와 매칭됩니다.

dm_only 모드 — 다이렉트 메시지만

Agent가 다이렉트 메시지에만 답변하며 그룹 메시지는 완전히 무시합니다(캐시 없음, 답변 없음).

{
  "mode": "dm_only"
}

적합한 사용 사례:

공개 서버에 봇을 배포하되 일대일 대화만 수락하는 경우
개인 정보에 민감한 시나리오

공통 옵션

다음 옵션들은 모든 트리거 모드와 조합하여 사용할 수 있습니다:

ignoreBot — 봇 자신의 메시지 무시

{
  "mode": "all",
  "ignoreBot": true
}

true로 설정하면 봇 자신이 보낸 메시지는 답변을 트리거하지 않아 자기 대화 루프를 방지합니다.

allowFrom — 발신자 허용 목록

{
  "mode": "all",
  "allowFrom": ["123456789", "987654321"]
}

허용 목록에 있는 사용자만 Agent 답변을 트리거할 수 있도록 제한합니다. allowFrom에는 플랫폼 사용자 ID(예: Discord 사용자 ID)를 입력합니다.

빈 배열 또는 ["*"]는 모든 사용자를 허용합니다
ID 매칭은 대소문자를 구분하지 않습니다
이 검사는 트리거 모드보다 우선합니다: 허용 목록에 없는 사용자는 봇을 @멘션해도 답변이 트리거되지 않습니다

메시지 캐싱 메커니즘

mention 및 keyword 모드에서 트리거되지 않은 메시지는 버려지지 않고 슬라이딩 윈도우에 캐시됩니다:

각 "Channel 인스턴스 + 채팅 세션"은 독립적인 메시지 버퍼를 유지합니다
버퍼는 최대 50개의 최근 메시지를 저장합니다(FIFO)
트리거 조건이 충족되면 버퍼의 모든 메시지가 트리거 메시지와 함께 Agent에 전송됩니다
그룹 메시지는 발신자, 타임스탬프 등 컨텍스트 정보를 포함한 XML 형식으로 래핑됩니다

이를 통해 Agent는 @멘션 시 단일 메시지만 보는 것이 아니라 그룹 대화의 배경을 이해할 수 있습니다.

보안 파이프라인

외부 플랫폼에서 들어오는 모든 메시지는 Agent에 도달하기 전에 순차적으로 5개의 보안 레이어를 통과합니다. 어느 레이어에서든 메시지가 차단되면 이후 레이어는 실행되지 않습니다.

메시지 진입
  │
  ├── [1] RateLimiter ─── 속도 초과? → 조용히 버림
  │
  ├── [2] InputSanitizer ─── 제어 문자 포함? → 제거 후 계속
  │
  ├── [3] PromptGuardian ─── 주입 공격 감지? → 차단 + 우회 메시지로 답변
  │
  ├── [4] UserPermissionService ─── 사용자 역할 금지? → 차단
  │
  ├── [5] ChannelPermissionGate ─── 권한 확인 답변? → 메시지 소비
  │
  └── 트리거 규칙 매칭 → Agent로 라우팅

레이어 1: RateLimiter — 속도 제한

슬라이딩 윈도우 속도 제한기로, 메모리에서 구현되며 영속성이 필요하지 않습니다.

설정	기본값	설명
`enabled`	`false`	속도 제한 활성화 여부
`maxPerMinute`	`20`	사용자당 분당 최대 메시지 수
`maxPerHour`	`200`	사용자당 시간당 최대 메시지 수
`globalMaxPerMinute`	`60`	모든 사용자 합산 분당 최대 메시지 수

동작: 제한을 초과하는 메시지는 조용히 버려집니다(답변 없음, 발신자에게 알림 없음).

속도 제한 키: channelId + senderId로 추적하며, 동일한 Channel 인스턴스에서 동일한 사용자의 메시지는 할당량을 공유합니다.

팁

속도 제한은 기본적으로 비활성화되어 있습니다. 악의적인 스팸으로 인한 API 비용 급증을 방지하기 위해 공개 대상 봇에서는 활성화하는 것이 권장됩니다.

레이어 2: InputSanitizer — 입력 정제

메시지에서 보이지 않는 Unicode 제어 문자를 제거하여 인코딩 악용 및 난독화 공격을 방지합니다.

설정	기본값	설명
`enabled`	`true`	입력 정제 활성화 여부
`stripControlChars`	`true`	제어 문자 제거 여부

제거되는 문자 유형:

널 바이트 (\x00)
제로 너비 공백 (-‏)
Unicode 양방향 제어 문자 ( -‮)
BOM 마커 ()
기타 C0/C1 제어 문자 (줄 바꿈, 탭 같은 일반 공백 문자는 유지)

동작: 정제된 메시지는 다음 레이어로 계속 전달됩니다. 원본 메시지에서 제거된 문자 수가 로그에 기록됩니다. 메시지는 차단되지 않습니다.

레이어 3: PromptGuardian — 프롬프트 주입 감지

AI(LLM)를 사용하여 메시지에 대한 시맨틱 수준의 보안 검토를 수행하며, 프롬프트 주입(prompt injection), 탈옥(jailbreak) 및 적대적 조작을 감지합니다.

설정	옵션	설명
`mode`	`off` / `monitor` / `block`	작동 모드

모드 설명:

모드	동작
`off`	완전히 비활성화, 오버헤드 없음 (기본값)
`monitor`	감지 및 로깅하지만 메시지를 차단하지 않음. 오탐지율 평가에 활용
`block`	주입이 감지되면 메시지를 차단하고 발신자에게 유머러스한 우회 메시지로 답변

설계 원칙:

fail-open: LLM 검토가 타임아웃(10초)되거나 오류가 발생하면 메시지가 자동으로 통과되어 보안 레이어 장애로 인해 정상 통신이 차단되지 않습니다
짧은 메시지(10자 미만)는 검토를 건너뜁니다
안전한 메시지 결과는 캐시(SHA-256 해시 키)되어 중복 검토를 방지합니다

레이어 4: UserPermissionService — 사용자 권한

역할 기반 접근 제어 시스템입니다. 첫 메시지를 보내는 외부 사용자는 자동으로 guest 역할로 등록됩니다.

역할 계층

역할을 높은 순서대로 나열하면:

역할	채팅	도구 실행	확인 필요	사용자 관리	설정 관리
owner	허용	허용	아니오	허용	허용
admin	허용	허용	아니오	허용	아니오
trusted	허용	허용	아니오	아니오	아니오
member	허용	허용	예	아니오	아니오
guest	허용	아니오	—	아니오	아니오
blocked	아니오	아니오	—	아니오	아니오

필드 설명:

채팅: 메시지가 Agent에 도달할 수 있는지 여부 (canChat)
도구 실행: 파일 읽기/쓰기, 셸 명령 같은 도구 호출을 트리거할 수 있는지 여부 (canUseTool)
확인 필요: 민감한 도구(셸, 파일 쓰기)를 실행하기 전에 발신자가 Channel에서 확인해야 하는지 여부 (requireConfirmation)
사용자 관리: 낮은 역할의 사용자를 관리할 수 있는지 여부 (canManageUsers)
설정 관리: Agent 및 보안 관련 설정을 수정할 수 있는지 여부 (canManageSettings)

기본 동작:

신규 사용자는 자동으로 guest로 등록되며, 채팅은 가능하지만 도구는 트리거할 수 없습니다
blocked 사용자의 메시지는 조용히 버려지며 해당 사용자에게 차단 알림이 전송됩니다
관리자는 Elftia 인터페이스를 통해 사용자 역할을 변경할 수 있습니다

레이어 5: ChannelPermissionGate — 작업 확인

member 역할의 사용자가 민감한 도구(셸 명령, 파일 쓰기 등)를 트리거하면 시스템이 직접 실행하지 않고 Channel에서 확인 요청을 보냅니다:

⚠️ Permission Required

Clawia wants to execute: **Shell Command**
> npm test

Reply: **y** (approve) / **n** (deny) / **always** (always allow this tool)
⏱ Auto-denied in 5 minutes. [confirm-xxx]

확인 답변 옵션:

답변	효과
`y` / `yes` / `ok` / `confirm`	이번 실행 승인
`n` / `no` / `cancel` / `deny`	이번 실행 거부
`always` / `always allow`	승인하고 이 도구 + 인자 조합을 기억. 이후 호출 자동 승인

주요 세부 사항:

확인 요청은 5분 후 응답이 없으면 자동으로 거부됩니다
Channel + 채팅 세션당 최대 5개의 대기 중인 확인 요청
always의 범위는 도구 + 인자 조합 단위로 정확하게 적용됩니다 (예: "항상 Bash: npm test 허용"이라고 해서 "Bash: rm -rf /"가 자동 승인되지는 않습니다)
owner, admin, trusted 역할은 확인이 필요 없으며 도구가 직접 실행됩니다
guest 역할은 도구를 전혀 트리거할 수 없으며 확인 단계에 도달하지 않습니다

보안 설정 권고 사항

개인 사용

{
  "rateLimiter": { "enabled": false },
  "sanitizer": { "enabled": true },
  "promptGuardian": { "mode": "off" }
}

개인 사용에는 엄격한 보안이 필요하지 않습니다. 입력 정제를 활성화 상태로 유지하는 것으로 충분합니다.

소규모 팀

{
  "rateLimiter": { "enabled": true, "maxPerMinute": 30, "maxPerHour": 300 },
  "sanitizer": { "enabled": true },
  "promptGuardian": { "mode": "monitor" }
}

실수로 인한 스팸을 방지하기 위해 속도 제한을 활성화하세요. PromptGuardian은 먼저 monitor 모드에서 오탐지율을 평가하세요.

공개 대상

{
  "rateLimiter": { "enabled": true, "maxPerMinute": 10, "maxPerHour": 100 },
  "sanitizer": { "enabled": true },
  "promptGuardian": { "mode": "block" }
}

전체 보안 파이프라인을 활성화하세요. 엄격한 속도 제한 + 프롬프트 주입 차단. allowFrom 허용 목록 또는 mention 트리거 모드와 함께 사용하는 것이 권장됩니다.