11.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를 통해:

1. 설정 > 컨테이너 > 그룹으로 이동합니다.

2. 새 그룹을 클릭합니다.

3. 이름을 입력합니다 (예: telegram-support, dev-alerts).

4. 필요하면 설명을 추가합니다.

5. 생성을 클릭합니다.

Management API를 통해:

curl -X POST http://localhost:55765/api/v1/container/namespaces \
  -H "Content-Type: application/json" \
  -d '{"name": "telegram-support", "description": "Customer support via Telegram"}'

그룹 네임스페이스 목록 조회¶

curl http://localhost:55765/api/v1/container/namespaces

응답:

[
  {
    "id": "a1b2c3d4-...",
    "name": "telegram-support",
    "description": "Customer support via Telegram",
    "createdAt": "2026-03-15T10:00:00Z",
    "updatedAt": "2026-03-15T10:00:00Z"
  }
]

채팅 JID를 그룹에 매핑¶

컨테이너 세션이 어느 그룹에 속하는지는 IPC 권한 모델이 결정합니다. 컨테이너 세션은 세션 디렉터리 이름에서 그룹을 물려받는데, 이 이름은 IPC로 세션을 생성할 때 정해집니다.

메인 vs 일반 그룹¶

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

메인 그룹은 한 번에 하나만 둘 수 있고, 관리 작업과 브로드캐스트에 쓰입니다.

IPC 디렉터리¶

컨테이너 세션이 시작되면 IPC 디렉터리가 생성됩니다:

curl -X POST http://localhost:55765/api/v1/container/ipc/directories \
  -H "Content-Type: application/json" \
  -d '{"group": "telegram-support", "sessionId": "session-abc123"}'

이 호출은 다음 구조를 만듭니다:

DATA_DIR/sessions/telegram-support/session-abc123/ipc/
├── input/     # host -> container messages
├── messages/  # container -> host send requests
└── tasks/     # container -> host task requests

Squad 처리용 메시지 형식¶

메시지가 Squad 그룹으로 라우팅되면 에이전트가 받을 수 있도록 XML 형식으로 변환됩니다:

<external_message>
  <channel>telegram</channel>
  <chat_jid>tg:123456789</chat_jid>
  <sender>user_42</sender>
  <sender_name>Alice</sender_name>
  <content>Can you help me analyze this dataset?</content>
  <timestamp>1741968000</timestamp>
</external_message>

에이전트는 이 메시지를 처리해 응답을 만들고, 응답에서 내부 XML 태그를 제거한 뒤 메시지가 들어온 채널로 돌려보냅니다.

그룹 지침 설정¶

그룹별 지침(CLAUDE.md 파일에 해당)은 해당 그룹의 모든 컨테이너 세션에 주입되므로, 채널이나 용도에 따라 에이전트 동작을 다르게 맞출 수 있습니다.

그룹 지침 설정¶

curl -X PUT http://localhost:55765/api/v1/container/namespaces/telegram-support/instructions \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are a customer support agent for Acme Corp. Always be polite and concise. If you cannot resolve an issue, escalate to a human agent by saying [ESCALATE]."}'

그룹 지침 조회¶

curl http://localhost:55765/api/v1/container/namespaces/telegram-support/instructions

전역 지침¶

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

# 전역 지침 조회
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": "Always respond in the same language as the user. Be helpful and accurate."}'

병합된 지침 미리보기¶

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

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)    → group: personal-assistant
Telegram Group (tg:222) → group: team-collaboration
Slack Channel (slack:C01) → group: code-review
Discord DM (discord:333) → group: personal-assistant

설정 단계¶

1. 각 그룹 네임스페이스를 생성합니다.

2. 네임스페이스마다 그룹별 지침을 설정합니다.

3. 그룹마다 Squad 컨테이너 에이전트를 실행합니다 (그룹별로 고유한 세션이 만들어집니다).

4. 각 채팅 JID에서 오는 메시지는 해당 그룹의 컨테이너 세션으로 자동 라우팅됩니다.

문제 해결¶

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

• 채널이 연결되어 있는지 확인: 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/가 있어야 합니다
• 실행 기록에서 컨테이너 로그 검토
• 컨테이너에 올바른 워크스페이스 마운트가 있는지 확인