Lark Bot 연동
Multica 에이전트를 Lark(飞书) 봇에 바인딩하면, Lark에서 직접 대화할 수 있습니다 — 개인 메시지나 그룹에서 @로 멘션하거나, 자연스럽게 대화하거나, /issue를 입력해 Lark를 벗어나지 않고 Multica 이슈를 생성하세요.
아무 에이전트나 Lark(飞书) 봇에 바인딩하면, 팀이 Lark 안에서 바로 그 에이전트를 사용할 수 있습니다 — 봇에게 개인 메시지를 보내거나, 그룹에서 @로 멘션하거나, /issue를 입력해 앱을 열지 않고도 Multica 이슈를 생성하세요. 에이전트의 답변은 실시간 카드로 채팅에 돌아오며, 작업이 진행되는 동안 계속 업데이트됩니다.
각 봇은 하나의 Multica 에이전트와 일대일로 바인딩됩니다. 두 번째 에이전트를 바인딩하면 두 번째 봇이 생성되며, 하나의 에이전트가 두 개의 봇을 갖는 일은 없습니다.
연동이 하는 일
| 위치 | 동작 |
|---|---|
| 에이전트 → Integrations | 에이전트 상세 페이지에 Integrations 탭이 있습니다(왼쪽 사이드바에도 대응하는 섹션이 있습니다). owner와 admin에게는 여기에 Bind to Lark가 보이며, 바인딩되면 Connected to Lark 배지와 Manage in Lark 링크로 바뀝니다. |
| 봇에게 개인 메시지 | 워크스페이스 멤버가 Lark에서 봇에게 직접 메시지를 보냅니다. 각 대화는 그 에이전트와의 Multica chat 세션이 되며, 에이전트는 해당 스레드에서 답변합니다. |
그룹에서 @ 멘션 | 봇을 Lark 그룹에 추가하고 @로 멘션하세요. 멘션한 메시지만 읽으며, 봇이 그룹 전체를 듣지는 않습니다. |
/issue 명령 | /issue <제목>(본문 추가 가능)을 입력하면 워크스페이스에 새 Multica 이슈가 생성되고, 당신 이름으로 귀속됩니다. |
| 실시간 답변 카드 | 봇은 인터랙티브 카드를 게시하고 에이전트가 실행되는 동안 계속 갱신합니다 — 진행 상황, 최종 답변, 또는 오류. |
에이전트 바인딩하기 (owner / admin)
바인딩은 스캔하여 설치하는 방식입니다 — 복사할 앱 시크릿도, 개발자 콘솔 작업도 없습니다.
- Agents → 당신의 에이전트에서 에이전트를 엽니다.
- Integrations 탭으로 이동하거나(또는 왼쪽 사이드바의 Integrations 섹션 사용) Bind to Lark를 클릭합니다.
- QR 코드가 나타납니다. 휴대폰에서 Lark → 스캔을 열고, 새로 생긴 PersonalAgent 봇을 인증하세요.
- 스캔이 완료되면 대화상자가 닫히고 에이전트에 Connected to Lark가 표시됩니다. 당신의 Lark 신원이 자동으로 Multica 계정에 바인딩되므로, 곧바로 봇과 대화를 시작할 수 있습니다.
QR 코드는 일회용이며 짧은 시간 후에 만료됩니다. 인증하기 전에 만료되면 Scan again을 클릭해 새 코드를 받으세요.
에이전트가 연결되면 Bind to Lark 버튼이 Manage in Lark 링크로 바뀝니다. 권한 범위를 조정하거나, 이름을 바꾸거나, 추가 권한을 요청해야 할 때 이 링크로 Lark에서 봇의 앱 페이지를 여세요 — 기존 봇이 고아가 되지 않도록 재스캔은 의도적으로 비활성화되어 있습니다.
봇 사용하기 (멤버)
첫 메시지: Lark 신원 바인딩하기
봇에게 처음 메시지를 보내면, Lark 신원을 바인딩하라는 카드로 답합니다. 링크를 탭하고 Multica에 로그인하면, 당신의 Lark 계정이 Multica 멤버십에 연결됩니다. 바로 이 단계가 에이전트로 하여금 당신을 대신해 행동하게 합니다 — 예를 들어 /issue는 이슈를 당신 이름으로 생성합니다.
워크스페이스 멤버만 봇을 사용할 수 있습니다. 멤버가 아니거나 신원 바인딩을 건너뛰면 봇은 응답하지 않으며, 메시지는 폐기됩니다(감사 목적으로 기록되며, 내용은 저장하지 않습니다).
대화와 /issue
- 무엇이든 에이전트에게 물어보기 — 봇에게 개인 메시지를 보내거나 그룹에서
@로 멘션하세요. 이 대화는 일반적인 에이전트 chat 세션이며, 에이전트는 카드에서 답변합니다. - 이슈 생성 —
/issue 로그인 리디렉션 수정을 보내면 Multica가 워크스페이스에 그 이슈를 생성하며, 새 이슈가 으레 할당되는 방식 그대로 처리됩니다. 제목 뒤에 줄을 더 추가하면 설명이 됩니다. - 작업 지켜보기 — 답변 카드는 에이전트가 실행되는 동안 스스로 갱신되므로, 진행 상황과 결과를 그 자리에서 볼 수 있습니다.
에이전트가 오프라인(런타임이 연결되지 않음)이거나 보관됨 상태라면, 봇은 메시지를 조용히 폐기하는 대신 짧은 상태 안내로 답합니다.
관리 및 연결 해제
워크스페이스 전체 관리는 설정 → Integrations에 있습니다.
- Connected bots는 워크스페이스 내 모든 봇과 각 봇이 바인딩된 에이전트를 나열합니다. 이 목록은 모든 멤버에게 보입니다.
- Disconnect는 owner / admin 전용입니다. 연결을 해제하면 봇이 Lark 메시지 수신을 멈추고 연결이 해체됩니다. 설치 기록은 감사용으로 유지되며, 이후 같은 에이전트를 다시 바인딩할 수 있습니다.
권한
- 바인딩 / 연결 해제에는 워크스페이스 owner 또는 admin이 필요합니다. 멤버에게는 connected-bots 목록은 보이지만 바인딩이나 연결 해제 컨트롤은 보이지 않습니다.
- 봇과 대화하기에는 Lark 신원이 바인딩된 워크스페이스 멤버여야 합니다. 그 외의 사람은 모두 폐기됩니다.
- 연동은 폐기된 메시지의 본문을 절대 저장하지 않으며 — 감사용 폐기 사유만 기록합니다.
자체 호스팅 설정
Multica Cloud에서는 연동이 이미 사용 가능합니다 — 이 섹션은 건너뛰세요.
자체 호스팅의 경우, at-rest 암호화 키를 설정하기 전까지 Lark는 꺼져 있습니다. 이 키는 각 봇의 앱 시크릿이 데이터베이스에 닿기 전에 암호화합니다.
-
32바이트 키를 생성해 API 서버에 설정합니다.
MULTICA_LARK_SECRET_KEY=<base64-encoded 32-byte key> -
API를 재시작하세요. 키가 설정되기 전까지 설정 → Integrations에는 "Lark integration not enabled" 안내가 표시되고, Bind to Lark 진입점은 숨겨진 채로 유지됩니다.
Feishu와 Lark 국제판을 동시에 지원. 각 Bot이 어느 클라우드(중국 본토 Feishu = open.feishu.cn, 국제판 Lark = open.larksuite.com)에 속하는지는 QR 코드를 스캔할 때 자동으로 감지되어 해당 설치에 저장되고, 그 Bot에 대한 모든 호출에 사용됩니다. 하나의 배포로 둘을 동시에 제공하므로, 어느 테넌트의 팀이든 추가 설정 없이 바인딩할 수 있습니다.
MULTICA_LARK_HTTP_BASE_URL / MULTICA_LARK_CALLBACK_BASE_URL는 배포 전체를 덮어쓰는 선택적 오버라이드(프록시나 mock용)로만 남아 있습니다. 일반 운영에서는 설정하지 않은 채로 두어 각 설치가 자기 클라우드에 도달하도록 하세요.
단일 클라우드 구성에서 업그레이드하나요? 이 변수들을 https://open.larksuite.com으로 설정해 국제판 Lark를 운영했다면, 업그레이드 후 첫 부팅 시 서버가 기존 설치를 Lark 리전으로 다시 표시하므로 이후에는 오버라이드를 지울 수 있습니다. 중국 본토 Feishu 배포에서는 별도 작업이 필요 없습니다.