9.5. 채널-Squad 매핑¶

채널-Squad 매핑은 외부 채널(Telegram, Slack, Discord, WhatsApp)에서 오는 메시지를 특정 Squad 컨테이너 그룹에 연결합니다. 각 채팅 대화(JID)는 그룹 네임스페이스에 매핑되고, 메시지는 올바른 그룹의 컨테이너 세션으로 라우팅됩니다.

라우팅 방식¶

flowchart TD
    MSG["수신 메시지\n(chat_jid, sender, content)"]
    AL[발신자 허용 목록 확인]
    JID["그룹 네임스페이스 테이블에서\nchat_jid 조회"]
    GRP[대상 그룹]
    CONT["컨테이너 세션\n(group/session_dir)"]
    RESP[에이전트 응답]
    CHAN[채널을 통해 전송]

    MSG --> AL
    AL -- 허용 --> JID
    AL -- 차단 --> DROP[메시지 삭제]
    JID -- 발견 --> GRP
    JID -- 없음 --> DEFAULT[기본 그룹 사용 또는 무시]
    GRP --> CONT
    CONT --> RESP
    RESP --> CHAN

각 메시지는 채팅 JID를 사용하여 라우팅됩니다 — 채널 이름과 채팅 식별자를 결합한 고유 식별자(예: tg:123456789, slack:C01234567).

그룹 네임스페이스¶

그룹 네임스페이스는 다음과 같은 격리된 컨텍스트입니다:

고유한 세션 디렉터리 (DATA_DIR/sessions/{group}/)
그룹별 지침 (CLAUDE.md)
채팅 JID별 대화 기록 유지
하나 이상의 매핑된 채팅 JID에서 메시지 수신

그룹 네임스페이스 생성¶

설정 UI를 통해:

설정 > 컨테이너 > 그룹으로 이동합니다.
새 그룹을 클릭합니다.
이름을 입력합니다 (예: telegram-support, dev-alerts).
선택적으로 설명을 추가합니다.
생성을 클릭합니다.

Management API를 통해:

curl -X POST http://localhost:55765/api/v1/container/namespaces \
  -H "Content-Type: application/json" \
  -d '{"name": "telegram-support", "description": "Telegram을 통한 고객 지원"}'

메인 vs 일반 그룹¶

그룹은 메인(권한 있음) 또는 일반으로 지정될 수 있습니다:

기능	메인 그룹	일반 그룹
모든 채팅 JID로 메시지 전송	가능	자신의 채팅 JID만 가능
모든 그룹에 작업 생성	가능	자신의 그룹만 가능
전역 지침 읽기	가능	가능
그룹 지침 쓰기	가능	불가능

그룹 지침 설정¶

그룹별 지침은 해당 그룹의 모든 컨테이너 세션에 주입됩니다.

그룹 지침 설정¶

curl -X PUT http://localhost:55765/api/v1/container/namespaces/telegram-support/instructions \
  -H "Content-Type: application/json" \
  -d '{"instructions": "당신은 Acme Corp의 고객 지원 에이전트입니다. 항상 정중하고 간결하게 응답하세요."}'

전역 지침¶

전역 지침은 모든 그룹에 적용되며 그룹별 지침과 병합됩니다:

# 전역 지침 조회
curl http://localhost:55765/api/v1/container/namespaces/global/instructions

# 전역 지침 설정
curl -X PUT http://localhost:55765/api/v1/container/namespaces/global/instructions \
  -H "Content-Type: application/json" \
  -d '{"instructions": "항상 사용자와 같은 언어로 응답하세요. 도움이 되고 정확하게 응답하세요."}'

병합된 지침 미리보기¶

특정 그룹에 대해 전역 지침과 그룹 지침이 어떻게 결합되는지 확인하려면:

curl -X POST http://localhost:55765/api/v1/container/namespaces/merge-instructions \
  -H "Content-Type: application/json" \
  -d '{"groupName": "telegram-support"}'

예시: 멀티 그룹 설정¶

다양한 Telegram 채팅을 다른 그룹으로 라우팅하는 예시:

Telegram DM (tg:111)       → 그룹: personal-assistant
Telegram 그룹 (tg:222)    → 그룹: team-collaboration
Slack 채널 (slack:C01)    → 그룹: code-review
Discord DM (discord:333)   → 그룹: personal-assistant

하나의 그룹, 여러 채팅

단일 그룹 네임스페이스가 여러 채팅 JID를 처리할 수 있습니다. 이는 Telegram 채팅과 Slack 채널에서 오는 메시지를 동일한 에이전트 컨텍스트로 처리하고자 할 때 유용합니다.

문제 해결¶

메시지가 라우팅되지 않음¶

채널이 연결되어 있는지 확인: curl http://localhost:55765/api/v1/channels
발신자가 허용 목록에 의해 차단되었는지 확인: curl http://localhost:55765/api/v1/channels/sender-allowlist
라우팅 오류를 위한 컨테이너 감사 로그 검토: curl http://localhost:55765/api/v1/container/audit-log

IPC 통신 실패¶

IPC 디렉터리가 존재하는지 확인: 세션 디렉터리에 ipc/input/, ipc/messages/, ipc/tasks/가 있어야 합니다
실행 기록에서 컨테이너 로그 검토
컨테이너에 올바른 워크스페이스 마운트가 있는지 확인