페이슈(해외 버전은 Lark)는 바이트댄스가 출시한 기업 협업 플랫폼으로, 인스턴트 메시징, 문서 협업, 화상 회의 등의 기능을 통합하고 있습니다. OpenClaw은 플러그인 시스템을 통해 페이슈 채널을 지원하며, 페이슈에서 직접 AI 에이전트와 대화하여 스마트 고객 서비스, 지식 Q&A, 워크플로 자동화 등의 시나리오를 구현할 수 있습니다.
사전 준비
설정을 시작하기 전에 다음 항목을 준비해야 합니다:
- 배포가 완료되어 정상 실행 중인 OpenClaw 인스턴스
- 페이슈 오픈 플랫폼의 기업 자체 개발 애플리케이션 (관리자 권한으로 생성 필요)
- 애플리케이션의 App ID와 App Secret
- 이벤트 구독 콜백 주소 설정 (공인 IP에서 접근 가능한 URL 필요)
페이슈 자체 개발 애플리케이션 생성
먼저 페이슈 오픈 플랫폼(open.feishu.cn)에 로그인하여 개발자 콘솔로 이동합니다. "기업 자체 개발 애플리케이션 생성"을 클릭하고 애플리케이션 이름과 설명을 입력합니다. 생성이 완료되면 애플리케이션의 "자격 증명 및 기본 정보" 페이지에서 App ID와 App Secret을 확인할 수 있으며, 이 두 값은 이후 설정에 필요합니다.
다음으로 애플리케이션에 "봇" 기능을 추가해야 합니다. 애플리케이션의 "기능 추가" 메뉴에서 "봇"을 선택하면 페이슈 채팅에서 메시지를 주고받을 수 있게 됩니다.
권한 및 이벤트 구독 설정
애플리케이션의 "권한 관리" 페이지에서 다음 권한을 활성화해야 합니다:
im:message— 메시지 수신 및 전송im:message.group_at_msg— 그룹 채팅에서 @봇 메시지 수신im:message.p2p_msg— 1:1 채팅 메시지 수신im:resource— 메시지 내 리소스 파일 가져오기
"이벤트 구독" 페이지에서 요청 주소를 OpenClaw 인스턴스의 페이슈 webhook 엔드포인트로 설정합니다. OpenClaw의 페이슈 플러그인은 기본적으로 /webhooks/feishu 경로를 수신하므로, 전체 주소는 https://your-domain.com/webhooks/feishu와 같은 형태가 됩니다.
구독할 이벤트에 im.message.receive_v1(메시지 수신 이벤트)을 포함합니다. 설정이 완료되면 페이슈가 검증 요청을 보내며, OpenClaw 플러그인이 이 검증을 자동으로 처리합니다.
페이슈 플러그인 설치
OpenClaw의 페이슈 채널은 플러그인 시스템을 통해 제공됩니다. 먼저 플러그인을 설치합니다:
openclaw plugin install feishu
설치가 완료되면 대화형 명령으로 로그인 설정을 진행할 수 있습니다:
openclaw channels login feishu
시스템이 순서대로 App ID, App Secret 및 Verification Token(이벤트 구독 페이지에서 확인 가능)을 입력하도록 안내합니다. 이러한 자격 증명은 로컬 설정에 안전하게 저장됩니다.
openclaw.json 수동 설정
openclaw.json 설정 파일을 직접 편집하여 페이슈 채널을 설정할 수도 있습니다:
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxxxxxxxxx",
"appSecret": "your-app-secret",
"verificationToken": "your-verification-token",
"encryptKey": "your-encrypt-key"
}
}
}
여기서 encryptKey는 선택 사항으로, 페이슈 오픈 플랫폼에서 Encrypt Key를 설정한 경우에 입력이 필요합니다. 암호화를 활성화하면 데이터 전송의 보안성이 강화되므로 프로덕션 환경에서는 활성화를 권장합니다.
게시 및 테스트
설정이 완료되면 페이슈 오픈 플랫폼으로 돌아가 애플리케이션의 사용 가능 범위를 대상 사용자 또는 부서로 설정한 후, "버전 생성"을 클릭하고 게시 심사를 제출합니다. 기업 내부 사용의 경우 관리자가 직접 승인할 수 있습니다.
게시가 완료되면 페이슈의 채팅 목록에서 봇 이름을 검색하고 메시지를 보내 정상적으로 응답하는지 테스트합니다.
그룹 채팅에서 사용
봇을 페이슈 그룹 채팅에 추가하면 기본적으로 @멘션된 메시지에만 응답합니다. 설정에서 이 동작을 조정할 수 있습니다:
{
"channels": {
"feishu": {
"groupBehavior": "mention_only"
}
}
}
groupBehavior는 mention_only(@메시지에만 응답)와 all(모든 메시지에 응답) 두 가지 모드를 지원합니다. 인원이 많은 그룹 채팅에서는 불필요한 간섭을 피하기 위해 mention_only 모드를 권장합니다.
보안 설정
OpenClaw의 allowlist 기능을 통해 봇과 상호작용할 수 있는 사용자를 제한하는 것을 권장합니다:
{
"channels": {
"feishu": {
"allowlist": ["user_id_1", "user_id_2"]
}
}
}
OpenClaw의 DM 매칭 기능과 결합하여 사용자가 먼저 DM을 통해 신원 인증을 완료한 후에만 그룹 채팅에서 봇을 사용할 수 있도록 할 수도 있습니다.
다른 채널과의 공존
페이슈 채널은 OpenClaw이 지원하는 다른 채널과 동시에 운영할 수 있습니다. 모든 채널은 동일한 AI 모델 백엔드를 공유하며, 페이슈에서의 대화와 Telegram, Discord 등 다른 플랫폼에서의 대화는 서로 독립적이지만 동일한 지식 베이스와 도구 설정을 공유할 수 있습니다. 이를 통해 기업은 내부 직원(페이슈 사용)과 외부 고객(다른 플랫폼 사용)에게 동시에 AI 서비스를 제공할 수 있습니다.
자주 묻는 질문
봇이 메시지를 수신하지 못하는 경우, 이벤트 구독의 콜백 주소가 올바른지, 애플리케이션이 게시되었는지, 네트워크 방화벽이 페이슈 서버의 요청을 허용하고 있는지 확인하세요. 페이슈 오픈 플랫폼의 "이벤트 구독" 페이지에서 로그 기능을 통해 이벤트 전송 상태와 오류 정보를 확인할 수 있습니다.