Mattermost
이 문서에서는 Mattermost를 Agentic Engine에 연동하는 방법을 설명합니다. 현재 채널은 Mattermost REST API v4를 통해 메시지를 보내고 편집하며, WebSocket을 통해 메시지를 받습니다. 사용자 신원은 OAuth 권한 부여 또는 일회용 연동 코드를 지원합니다.
1. 사전 조건
- Mattermost 시스템 관리자 권한이 있어 Bot Account를 생성할 수 있어야 합니다. OAuth를 사용하려면 OAuth 2.0 Application도 생성해야 합니다.
- Agentic Engine의 시스템 관리 → 채널 관리 권한이 있어야 합니다.
- Bot이 사용할 Team과 Channel을 준비합니다.
- Agentic Engine 서버 측에서 Mattermost Site URL,
/api/v4/**,/api/v4/websocket에 접근할 수 있어야 합니다. - OAuth 연동이 필요하면 사용자 브라우저에서 접근할 수 있는 Agentic Engine 주소를 준비합니다. 운영 환경에서는 HTTPS를 사용하는 것을 권장합니다.
지원 범위: Mattermost Cloud와 자체 구축 배포 모두 사용할 수 있습니다. Site URL에는 배포 하위 경로를 포함할 수 있습니다.
2. Mattermost Bot 생성 및 자격 증명 획득
Mattermost 시스템 관리자 계정으로 다음 단계에 따라 진행합니다:
- System Console → Integrations → Bot Accounts로 이동하여 Enable Bot Account Creation을 true로 설정합니다.
- Product menu → Integrations → Bot Accounts를 열고 Add Bot Account를 클릭합니다.
- Bot Username, Display Name, Description을 입력합니다. 운영 환경에서는 일반 Member 권한을 유지하고 최소 권한 원칙에 따라 권한을 부여하는 것을 권장합니다.
- Create Bot Account를 클릭하고 생성된 Access Token을 즉시 복사합니다.
- 사용할 Team과 Channel에 Bot을 추가합니다.
Bot Token은 한 번만 표시됩니다. 즉시 통제된 비밀번호 관리 시스템에 저장하고, 코드 저장소, 티켓, 채팅 기록에 남기지 마십시오. Token이 유출되면 Mattermost에서 폐기하고 다시 생성하십시오.
Bot에는 최소한 다음 기능이 필요합니다:
| 기능 | 용도 |
|---|---|
| 대상 Channel 읽기 | 다이렉트 메시지, 채널, 비공개 채널, 그룹 채팅의 메시지를 받습니다. |
| Post 생성 | 일반 답변과 최종 결과를 보냅니다. |
| 직접 생성한 Post 편집 | 같은 Post에서 스트리밍 답변을 표시합니다. |
| 파일 읽기 및 업로드 | 사용자 첨부 파일을 처리하고, Agent가 생성한 파일을 원래 채널과 원래 thread로 다시 보냅니다. |
Mattermost Site URL 기록
현재 Mattermost 사이트 주소를 기록합니다. 예:
https://chat.example.com
사이트가 하위 경로에 배포된 경우 다음과 같이 입력할 수 있습니다:
https://example.com/mattermost
/api/v4, 쿼리 파라미터, fragment를 덧붙이거나 URL에 사용자 이름과 비밀번호를 포함하지 마십시오.
3. OAuth 2.0 앱 생성(선택 사항)
OAuth는 봇이 메시지를 주고받는 데 필수 항목이 아닙니다. OAuth를 꺼도 사용자는 6자리 일회용 연동 코드로 연동을 완료할 수 있습니다. 사용자가 진입점을 클릭한 후 바로 권한을 부여하여 연동하도록 하려면 다음 설정을 계속합니다:
- System Console → Integrations → Integration Management로 이동하여 Enable OAuth 2.0 Service Provider를 true로 설정합니다.
- Product menu → Integrations → OAuth 2.0 Applications로 이동하여 Add OAuth 2.0 Application을 클릭합니다.
- Is Public Client를 No로 설정하여 Confidential Client를 생성합니다.
- 사용자가 처음 연동할 때 권한 부여를 명시적으로 확인하도록 Is Trusted는 No로 유지하는 것을 권장합니다.
- Callback URL을 입력하고 저장한 후 Client ID와 Client Secret을 기록합니다.
Callback URL은 Agentic Engine의 실제 접속 주소와 완전히 일치해야 합니다:
https://your-domain/agent/api/mattermost-oauth/callback
OAuth 앱은 Mattermost 인스턴스별로 등록됩니다. Client ID, Client Secret, Server URL은 같은 Mattermost 인스턴스에 속해야 하며 인스턴스 간에 재사용할 수 없습니다.
4. Agentic Engine에서 Mattermost 채널 추가
관리자가 Agentic Engine에 로그인하여 시스템 관리 → 채널 관리로 이동합니다:
- 새 채널을 클릭하고 채널 타입으로 Mattermost를 선택합니다.
- 다음 구성 항목을 입력합니다.
| 구성 항목 | 필수 여부 | 설명 |
|---|---|---|
| 채널 이름 | 필수 | 표시 이름(예: Mattermost 봇). |
Server URL | 필수 | Mattermost Site URL입니다. 배포 하위 경로를 포함할 수 있지만 /api/v4는 포함하지 마십시오. |
Bot Token | 필수 | Bot Account를 생성한 후 생성된 Access Token입니다. |
| OAuth 연결 활성화 | 선택 | 켜면 사용자는 우선 브라우저에서 권한을 부여합니다. 꺼도 일회용 연동 코드를 사용할 수 있습니다. |
OAuth Client ID | 조건부 필수 | OAuth를 활성화하면 반드시 입력해야 합니다. |
OAuth Client Secret | 조건부 필수 | OAuth를 활성화하면 반드시 입력해야 합니다. |
| 기본 모델 | 선택 | 선택하지 않으면 시스템 전역 기본 모델을 사용합니다. |
| 시스템 프롬프트 | 선택 | 이 채널의 Agent 대화에만 적용됩니다. |
- 저장을 클릭한 다음 채널의 활성화 스위치를 켭니다.
- 채널 상태가 정상인지 확인합니다. 활성화하면 시스템은
/api/v4/users/me를 호출하여 Bot Token과 Bot 신원을 검증한 다음<Site URL>/api/v4/websocket에 연결합니다.
Secret 편집: 기존 채널을 편집할 때 Bot Token 또는 OAuth Client Secret을 비워 두면 원래 값이 유지됩니다. 시스템은 저장된 Secret을 다시 표시하지 않습니다.
5. 사용자 Mattermost 계정 연동
방법 1: OAuth 권한 부여 연동
- 사용자가 Agentic Engine에 로그인하여 왼쪽 하단의 개인 메뉴를 클릭하고 Mattermost를 선택합니다.
- 브라우저에서 현재 Mattermost 인스턴스의 권한 부여 페이지가 열립니다.
- 사용자가 로그인하고 권한 부여를 확인하면 창이 닫히고 메뉴의 상태가 연동됨으로 바뀝니다.
OAuth access token은 콜백 과정에서만 잠시 사용되며, 데이터베이스에 저장되지 않고 채널 설정의 Bot Token을 대체하지도 않습니다.
방법 2: 일회용 연동 코드
OAuth가 활성화되지 않았거나, 시스템이 권한 부여 주소를 가져오지 못했거나, 권한 부여 주소가 유효하지 않거나, 브라우저가 권한 부여 창을 차단한 경우에는 자동으로 연동 코드를 사용합니다:
- 왼쪽 하단 개인 메뉴에서 Mattermost를 클릭합니다.
- 팝업 창에 표시된 연동 명령을 복사합니다.
- Mattermost에서 Bot에게 다이렉트 메시지로 해당 명령을 보냅니다.
- Bot이 연동 성공을 답장하면 Agentic Engine이 연동 상태를 자동으로 새로고침합니다.
+bind ABC234
연동 코드는 기본적으로 10분 동안 유효하며 한 번만 사용할 수 있습니다. 유출을 막기 위해 시스템은 채널이나 그룹 채팅에서 보낸 연동 명령을 받지 않습니다. 하나의 Mattermost 계정을 여러 Agentic Engine 사용자에게 동시에 연동할 수 없습니다.
연결 해제
- 왼쪽 하단 개인 메뉴를 클릭하고 Mattermost 행에서 연결 해제를 클릭합니다.
- 확인하면 상태가 연동되지 않음으로 바뀝니다. Agentic Engine 계정을 변경하려면 먼저 원래 계정의 연결을 해제하십시오.
6. 사용 방법
| 시나리오 | 작업 설명 |
|---|---|
| 다이렉트 메시지 | Bot에게 바로 질문을 보냅니다. |
| 공개/비공개 채널 및 그룹 채팅 | @Bot用户名 问题内容를 사용합니다. Bot을 @멘션하지 않은 일반 메시지는 무시됩니다. |
| 스레드 | 기존 thread에서 질문하면 답변도 해당 thread에 계속 남습니다. 채널의 루트 메시지에서 질문하면 Bot이 해당 메시지를 root로 하여 thread를 만들어 답변합니다. |
| 사용자 답변을 기다리는 중 | 답변 입력을 클릭하여 Dialog를 열거나 Bot의 안내에 따라 텍스트로 바로 답장합니다. 최대 회차에 도달하면 계속 실행을 클릭하거나 계속이라고 답장할 수 있습니다. |
| Agent에게 첨부 파일 보내기 | 다이렉트 메시지에서는 첨부 파일을 바로 보낼 수 있습니다. 채널에서는 첨부 파일 메시지 본문에서 Bot을 @멘션해야 합니다. |
| Agent 파일 받기 | Agent가 생성한 파일은 새 Post로 원래 채널과 원래 thread에 다시 전송됩니다. |
| 작업 알림 | Agent Team 즉시 작업과 예약 작업에서 Mattermost를 선택할 수 있습니다. 결과는 작업 생성자가 연동한 계정의 다이렉트 메시지로 전송됩니다. |
자주 쓰는 명령
| 명령 | 설명 | 예시 |
|---|---|---|
+bind <CODE> | 일회용 연동 코드로 계정을 연동합니다. | +bind ABC234 |
+new | 새 대화를 시작합니다. | +new |
+agent <Agent名称> <问题> | 지정한 Agent에게 메시지를 보냅니다. | +agent rhea 帮我分析数据 |
채널에서 명령을 사용할 때도 먼저 @Bot用户名을 입력해야 합니다.
7. 문제 해결
저장 시 설정이 유효하지 않다는 메시지가 표시됨
- Server URL은 완전한
http://또는https://URL이어야 합니다. /api/v4를 입력하지 말고, query, fragment 또는 URL에 포함된 자격 증명도 넣지 마십시오.- 새 채널을 만들 때 Bot Token은 비워 둘 수 없습니다. 편집할 때만 비워 두면 기존 Token이 유지됩니다.
채널 활성화 후 오프라인 상태이거나 재연결이 반복됨
- 같은 Bot Token으로
GET <Site URL>/api/v4/users/me를 요청하여 Bot 사용자가 반환되는지 확인합니다. - Agentic Engine에서 Mattermost로의 DNS, TLS, 네트워크 연결을 확인합니다.
- 리버스 프록시가
/api/v4/websocket의 WebSocket Upgrade를 허용하는지 확인합니다. - Bot이 삭제되거나 비활성화되지 않았는지, Token이 폐기되거나 다시 생성되지 않았는지 확인합니다.
Bot이 채널 메시지를 받지 못함
- Bot이 대상 Team과 Channel에 추가되었는지 확인합니다.
- 공개 채널, 비공개 채널, 그룹 채팅에서는 반드시
@Bot用户名을 올바르게 입력해야 합니다. - 채널이 활성화되어 정상 상태인지 확인합니다.
메시지는 받지만 답장할 수 없음
- Bot에 대상 Channel에서 Post를 생성할 권한이 있는지 확인합니다.
- 스트리밍 답변을 하려면 Bot이 직접 생성한 Post를 편집할 수 있어야 합니다.
- 고급 권한 스킴을 사용하는 경우 멤버가 직접 생성한 Post를 편집하는 것이 금지되어 있지 않은지 확인합니다.
첨부 파일을 다운로드하거나 업로드할 수 없음
- Bot이 대상 Channel의 멤버이며 파일 읽기 및 업로드 권한이 있는지 확인합니다.
channel.mattermost.fileUploads.enabled가 켜져 있는지, 그리고 크기, 개수, 시간 초과 제한을 확인합니다.- 기본적으로 메시지당 최대 5개의 첨부 파일을 처리하며, 각 파일은 2 MiB를 넘을 수 없습니다. 확장자, MIME, 실제 파일 내용이 일치하지 않으면 거부될 수 있습니다.
연동 코드가 유효하지 않음
- 연동 코드를 다시 생성하고 10분 이내에 사용합니다.
- 현재 테넌트에 설정된 Mattermost Bot에게 명령을 보냈는지 확인합니다.
- 연동 명령은 Bot과의 다이렉트 메시지로만 보낼 수 있습니다.
OAuth 권한 부여 실패
- Mattermost에서 OAuth 2.0 Service Provider가 활성화되어 있고 OAuth Application이 Confidential Client를 사용하는지 확인합니다.
- Client ID, Client Secret, Server URL이 같은 Mattermost 인스턴스에 속하는지 확인합니다.
- Callback URL은 Agentic Engine 관리 화면에 안내된 주소와 완전히 일치해야 하며 실제 basePath를 포함해야 합니다.
- Agentic Engine Origin을
ALLOWED_ORIGINS에 추가합니다. 운영 환경에서는 HTTPS를 사용하고 Cookie 보안 설정이 프로토콜과 일치하는지 확인합니다. - 로컬에서 접근할 때는
http://localhost:3000과 같은 실제 브라우저 Origin을 사용하고,0.0.0.0을 OAuth Callback URL에 입력하지 마십시오.
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.