Slack
1. Slack App 설정
-
Slack API에 접속합니다
-
새 앱을 생성합니다(또는 기존 앱을 사용합니다)
- 빈 앱에서 시작("Blank app")을 선택합니다
- App Name을 입력하고 Workspace를 선택합니다
-
앱 자격 증명을 가져옵니다:
- Client ID(Basic Information → App Credentials에 있음)
- Client Secret(Basic Information → App Credentials에 있음)
2. App-Level Tokens 설정
- Basic Information → App-Level Tokens에서 "Generate Token and Scopes"를 클릭합니다
- Token 이름을 입력합니다(예:
connection_token) connections:write,authorizations:read,app_configurations:writescopes를 추가합니다- "Generate"를 클릭합니다
- 생성된
xapp-...형식의 Token을 복사합니다
3. OAuth & Permissions 설정
Slack은 HTTPS만 허용합니다. HTTPS가 없으면 이 설정을 건너뛰고 방법 1로 연동하여 사용하십시오
Slack App 관리 페이지 → OAuth & Permissions에서:
3.1 Redirect URLs 추가
https://your-domain:port/agent/api/slack-oauth/callback
예시:
- 로컬 개발: http://localhost:3000/api/slack-oauth/callback
- 테스트 환경: https://your-test-domain.com/agent/api/slack-oauth/callback
- 운영 환경: https://your-domain.com/agent/api/slack-oauth/callback
주의:
- 프로토콜이 일치해야 합니다(HTTPS)
- 기본 포트(80/443)가 아니면 포트 번호를 포함해야 합니다
- 콜백 주소를 여러 개(개발/테스트/운영) 설정할 수 있습니다
3.2 User Token Scopes 설정
OAuth & Permissions → Scopes → User Token Scopes에 다음을 추가합니다:
identity.basic- 사용자 기본 정보 가져오기(필수)identity.email- 사용자 이메일 가져오기(선택)
참고: Scopes를 추가하거나 수정한 후에는 앱을 Workspace에 다시 설치해야 합니다.
3.3 Bot Token Scopes 설정
OAuth & Permissions → Scopes → Bot Token Scopes에 다음을 추가합니다:
chat:write- 메시지 보내기app_mentions:read- @ 멘션 읽기channels:history- 채널 이전 메시지 읽기channels:read- 채널 정보 읽기groups:history- 비공개 채널 이전 메시지 읽기im:history- 다이렉트 메시지 이전 메시지 읽기im:read- 다이렉트 메시지 정보 읽기files:write- 파일 업로드, 편집 및 삭제files:read- 공유된 파일 보기
4. App Home 및 봇 설정
- App Home → Show Tabs에서 다음을 활성화합니다:
- Home Tab - 사용자가 Home에서 Bot과 상호 작용할 수 있습니다
- Message Tab - Bot의 다이렉트 메시지 대화 화면
Allow users to send Slash commands and messages from the messages tab을 체크합니다
- Interactivity & Shortcuts에서 Interactivity를 활성화합니다
- Socket Mode에서 Socket Mode를 활성화합니다(WebSocket 연결을 사용하는 경우)
5. Event Subscriptions 추가
- Event Subscriptions에서 Enable Events를 활성화합니다.
- Subscribe to bot events에
app_mention을 추가합니다. 공개 또는 비공개 채널에서 @App으로 시작한 새 작업을 받는 데 사용합니다. message.channels와message.groups를 추가합니다. 공개/비공개 채널 thread에서 답변 대기 및 계속 실행에 대한 회신을 받는 데 사용합니다.message.im은 다이렉트 메시지를 받는 데 사용하므로 유지합니다. 그룹 다이렉트 메시지도 필요하면message.mpim을 추가하고 해당 이전 메시지 권한을 부여합니다.
Socket Mode, 이벤트 및 인터랙션 확인:
- App-Level Token에는 최소한
connections:write를 부여하고 Enable Socket Mode를 켭니다. - Bot Token Scopes에는 최소한
chat:write,app_mentions:read,channels:history,groups:history,im:history,files:read,files:write가 포함되어야 합니다. - Interactivity는 반드시 켜야 합니다. Socket Mode에서는 공용 네트워크 Request URL이 필요하지 않지만, 메시지 양식, Modal 제출, 계속 실행은 여전히 Interactivity에 의존합니다.
- OAuth Scopes나 Bot Events를 수정한 후에는 반드시 App을 Workspace에 다시 설치해야 합니다. App-Level Token을 다시 생성한 후에는 채널 설정의 App Token도 함께 업데이트해야 합니다.
6. Workspace에 앱 설치
OAuth & Permissions 페이지에서 "Install to Workspace" 버튼을 클릭하여 앱이 Workspace에 접근하도록 권한을 부여합니다.
사용 절차
방법 1: 연동 코드 모드(권장)
Slack은 그룹 채팅에서 연동 코드로 계정을 연동하는 방식을 지원하며, 팀 내부에 보급하여 사용하기에 적합합니다.
사용자 연동 절차
- 사용자가 시스템에 로그인합니다
- 왼쪽 하단의 사용자 아바타를 클릭하여 메뉴를 엽니다
- Slack 행을 찾아 연동 코드 받기 버튼을 클릭합니다
- 시스템이 6자리 연동 코드(예:
FRT12H)를 생성하며, 유효 기간은 10분입니다 - 사용자가 Slack에서 봇에게 다이렉트 메시지를 보냅니다:
+bind FRT12H - 연동에 성공하면 Slack에 연동 성공 안내가 표시됩니다
연동 해제 절차
- 왼쪽 하단의 사용자 아바타를 클릭하여 메뉴를 엽니다
- Slack 행을 찾아 연결 해제 버튼을 클릭합니다
- 연결 해제 작업을 확인합니다
- 연결 해제에 성공하면 메뉴에 연동되지 않음 상태가 표시됩니다
방법 2: OAuth 인증 모드
브라우저에서 권한을 부여하여 연동을 완료합니다.
사용자 연동 절차
- 사용자가 시스템에 로그인합니다
- 왼쪽 하단의 사용자 아바타를 클릭하여 메뉴를 엽니다
- Slack 행을 찾아 연동 버튼을 클릭합니다
- Slack 권한 부여 페이지로 이동합니다
- 사용자가 권한 부여를 확인합니다(Workspace 선택)
- 시스템으로 자동으로 돌아와 연동 성공이 표시됩니다
- 인증 창을 닫으면 원래 페이지가 자동으로 새로 고쳐지고, 메뉴에 연동됨 상태가 표시됩니다
사용자 연동 해제 절차
- 왼쪽 하단의 사용자 아바타를 클릭하여 메뉴를 엽니다
- Slack 행을 찾아 연결 해제 버튼을 클릭합니다
- 연결 해제 작업을 확인합니다
- 연결 해제에 성공하면 메뉴에 연동되지 않음 상태가 표시됩니다
사용자 지정 명령
Slack 봇은 다음 명령을 지원합니다(모든 명령은 +로 시작합니다):
| 명령 | 설명 | 예시 |
|---|---|---|
+bind <CODE> | 연동 코드로 계정 연동(영문 대문자+숫자 6자리) | +bind FRT12H |
+new | 새 대화를 시작하고 현재 대화 기록을 지웁니다 | +new 보내기 |
+agent <名称> <消息> | 지정한 이름의 Agent에게 메시지를 보냅니다 | +agent rhea 你好 |
+agent <消息> | 시스템 기본 Agent에게 메시지를 보냅니다 | +agent 你好 |
설명:
+로 시작하지 않는 메시지는 시스템 기본 Agent에게 바로 전송됩니다+bind명령은 연동 코드 모드에서 사용하며, 연동하지 않은 사용자는 먼저 연동해야 다른 기능을 사용할 수 있습니다+new명령은 현재 대화를 지우고 새로 시작합니다- Agent 이름은 사용자에게 접근 권한이 있는 Agent여야 합니다
- 명령 파라미터는 대소문자를 구분합니다
- 연동 코드 문자 집합에서는 혼동하기 쉬운 문자(I/O/0/1)를 제외합니다
그룹 채팅 메시지 분배
그룹 채팅 메시지 분배를 사용하면 하나의 Slack App이 규칙에 따라 서로 다른 질문을 서로 다른 Agent 또는 Team에 전달할 수 있습니다. 하나의 채팅 공간은 현재 Workspace에 대응하며, 설정은 해당 Workspace에서 이 App이 설치된 채널에 적용됩니다. Agentic Engine 계정을 연동하고 채널에서 App을 명시적으로 @멘션한 멤버만 작업을 시작할 수 있습니다.
관리자 설정
- Socket Mode, Event Subscriptions, Interactivity가 활성화되어 있는지 확인합니다. Bot Events에는 최소한
app_mention,message.channels,message.groups,message.im이 포함되어야 하며, scopes를 수정한 후에는 App을 Workspace에 다시 설치합니다. - 사용할 공개 채널 또는 비공개 채널에 App을 초대합니다. 비공개 채널에서 App이 멤버가 아니면 설정이 올바르더라도 메시지를 받을 수 없습니다.
- 시스템 관리 → 채널 관리로 이동하여 해당 Slack 채널에서 메시지 분배를 열고, Workspace를 선택한 다음 기본 Agent/Team을 설정합니다.
- 필요에 따라 규칙을 최대 19개까지 추가합니다. 규칙마다 Agent/Team을 하나 선택하고 필수 항목인 호출 명령을 입력하며, 키워드도 최대 10개까지 입력할 수 있습니다. 그런 다음 활성화 스위치를 켜고 저장합니다.
- 채널에서
@App +help를 보내 설정을 검수하고, 기능 목록과 스레드 답변이 모두 정상인지 확인합니다.
| 구성 항목 | 규칙 |
|---|---|
| 기본 Agent/Team | 활성화하기 전에 반드시 설정해야 합니다. 호출 명령을 지정하지 않았고 키워드도 일치하지 않을 때 사용됩니다. |
| 호출 명령 | 필수, 1~32자. 영문자, 숫자, -, _를 사용할 수 있으며 시스템 예약 명령은 사용할 수 없습니다. 대소문자 및 전각/반각 차이는 서로 다른 명령으로 취급하지 않습니다. |
| 키워드 | 선택 사항. 규칙마다 최대 10개, 각 2~32자. 여러 키워드가 동시에 일치하면 더 긴 키워드를 우선하며, 길이가 같아 하나로 판단할 수 없으면 기본 Agent/Team을 사용합니다. |
| 선택 가능 범위 | 활성화되어 있고 실행 가능한 시스템/기업 에이전트와 현재 기업의 Team을 선택할 수 있습니다. 개인 에이전트는 그룹 채팅 분배 후보에 표시되지 않습니다. |
채널에서 사용하는 방법
| 용도 | 예시 | 설명 |
|---|---|---|
| 사용 가능한 기능 보기 | @App +help@App 能力清单 | 기본 항목, 호출 명령, 키워드를 나열합니다. 권한이 없거나 현재 실행할 수 없는 기능은 표시되지 않습니다. |
| Agent/Team 지정 | @App +analysis 分析本周数据 | analysis는 관리자가 설정한 호출 명령입니다. @App @analysis 分析本周数据를 보낼 수도 있습니다. |
| 키워드로 분배 | @App 帮我检查埋点方案 | 본문이 키워드와 일치하면 해당 Agent/Team에 전달하고, 일치하지 않으면 기본 항목을 사용합니다. |
| 작업 취소 | @App +cancel | 메시지 전체를 정확히 이 내용으로 보내야 합니다. 이미 출력된 본문은 유지되며, 취소 확인 메시지가 별도로 전송됩니다. |
| 이전 방식 호환 | @App +agent analysis 分析本周数据 | 계속 사용할 수 있지만, +analysis를 직접 사용하는 것을 권장합니다. |
스레드 답변: 일반적인 새 작업은 먼저 App을 @멘션해야 합니다. 작업이 이미 어떤 thread에서 답변을 기다리는 중이면 안내에 따라 해당 thread에 바로 답변할 수 있으며 다시 @멘션할 필요가 없습니다. 대기 중인 작업이 없는 일반 채널 메시지는 무시됩니다.
명령 범위: 그룹 채팅 분배는 +new를 지원하지 않습니다. 다이렉트 메시지에서는 여전히 +new, +agent, +cancel을 지원합니다.
공개 컨텍스트와 개인 데이터: 시스템은 최근에 App을 명시적으로 @멘션하여 실제로 처리된 공개 채널 회차만 참고로 사용합니다. App을 @멘션하지 않은 일반 메시지, 다른 채널, 다이렉트 메시지, 사용자 메모리는 섞이지 않습니다. 이전 내용은 신뢰할 수 없는 참고 자료로만 사용되며, 현재 메시지만이 이번 회차의 지시입니다.
자주 묻는 질문
1. 사용자 메뉴에 Slack 연동 옵션이 표시되지 않음
사유:
- Slack 채널이 구성되지 않았거나 비활성입니다
- Channel 테이블에 type='slack'인 레코드가 없습니다
- config 필드에 clientId 또는 clientSecret이 없습니다
해결 방법:
- 채널 관리에 Slack 채널이 있는지 확인합니다
- 채널이 활성화되어 있는지 확인합니다
- config 필드에 clientId와 clientSecret이 포함되어 있는지 확인합니다
2. 연동을 클릭한 후 이동 실패
오류 메시지: 인증 URL을 가져오지 못했습니다
해결 방법:
- Slack App의 Client ID와 Client Secret이 올바른지 확인합니다
- Slack App이 Workspace에 설치되어 있는지 확인합니다
- 백엔드 로그에서 구체적인 오류 정보를 확인합니다
3. 권한 부여 후 콜백 실패
오류 메시지: 콜백 주소 검증 실패 또는 state 검증 실패
해결 방법:
- Slack App에 설정한 Redirect URLs에 현재 접속 중인 콜백 주소가 포함되어 있는지 확인합니다
- 프로토콜(HTTP/HTTPS)과 포트가 일치하는지 확인합니다
- 교차 출처(CORS) 문제가 없는지 확인합니다
4. 연동 실패
오류 메시지: 이 Slack 계정은 다른 사용자에 연결되어 있습니다
해결 방법:
- 하나의 Slack 계정은 하나의 시스템 사용자에만 연동할 수 있습니다
- 연동을 변경하려면 먼저 원래 계정에서 연결을 해제하십시오
5. 운영 환경 화이트리스트 검증 실패
오류 메시지: 운영 환경에서는 ALLOWED_ORIGINS를 설정해야 합니다 또는 허용되지 않은 출처입니다
해결 방법:
ALLOWED_ORIGINS환경 변수를 설정합니다- origin이 화이트리스트에 있는지 확인합니다
- 여러 도메인은 쉼표로 구분합니다
관련 문서
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.