왜 Feishu인가?
Feishu (飞书)는 국제적으로 Lark로 알려진 ByteDance의 기업 협업 플랫폼으로, 중국 기술 기업, 스타트업, 그리고 점점 더 동남아시아에서 널리 사용됩니다. OpenClaw v2026.2.2에서 Feishu는 플랫폼의 첫 번째 공식 지원 중국 채팅 클라이언트가 되었습니다.
- •공개 URL 불필요 — ngrok, 도메인, webhook 서버 필요 없음
- •방화벽 뒤에서 작동 — 연결이 여러분의 기기에서 아웃바운드로 이루어짐
- •저지연 — 실시간 양방향 메시징
- •풍부한 콘텐츠 지원 — 텍스트, 이미지, 파일, 오디오, 비디오, 스티커
사전 요구사항
- •OpenClaw v2026.2.2 이상
- •Feishu/Lark 기업 계정 (무료 티어 가능)
- •Feishu 오픈 플랫폼에서 앱을 생성하기 위한 관리자 접근 권한
1단계: Feishu 앱 생성
- 1.Feishu 오픈 플랫폼 (또는 국제 테넌트의 경우 Lark 개발자 콘솔)으로 이동하세요
- 2.커스텀 앱 만들기를 클릭하세요
- 3.앱 이름(예: "OpenClaw Agent")과 설명을 설정하세요
- 4.아이콘을 업로드하세요 (OpenClaw 랍스터 로고가 잘 어울립니다)
- 5.자격 증명 페이지에서 App ID (형식:
cli_xxx)와 App Secret을 복사하세요
2단계: 앱 권한 구성
앱의 권한 설정에서 다음 스코프를 활성화하세요:
| 권한 | 목적 |
|---|---|
im:message | 메시지 전송 및 수신 |
im:message.group_at_msg | 그룹 채팅에서 @멘션 수신 |
im:resource | 이미지 및 파일 접근 |
contact:user.id:readonly | 사용자 식별 |
권한을 추가한 후 게시를 클릭하여 검토를 위해 제출하세요. 대부분의 기업 테넌트에서 자체 구축 앱은 자동 승인됩니다.
3단계: 이벤트 구독 활성화
- 1.앱 설정에서 이벤트 구독으로 이동하세요
- 2.WebSocket 모드 (롱 커넥션)를 선택하세요 — 이것이 중요합니다. 공개 URL이 필요한 webhook 모드를 사용하지 마세요.
- 3.다음 이벤트를 구독하세요:
4단계: OpenClaw 구성
OpenClaw 구성에 Feishu 자격 증명을 추가하세요. ~/.openclaw/.env를 편집하세요:
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
또는 OpenClaw 구성 파일(~/.openclaw/config.yaml)을 사용하는 경우:
channels:
feishu:
enabled: true
appId: cli_xxxxxxxxxxxxx
appSecret: your_app_secret_here
OpenClaw를 재시작하세요:
openclaw restart
Feishu WebSocket 연결이 설정되었다는 로그 메시지가 표시되어야 합니다.
5단계: 연결 테스트
Feishu를 열고 채팅 목록에서 앱을 찾으세요 (1단계에서 설정한 앱 이름을 검색하세요). 메시지를 보내세요:
> 안녕하세요!
- •텍스트 메시지
- •이미지 (비전 기능이 있는 모델을 사용하면 에이전트가 분석할 수 있습니다)
- •파일 (에이전트가 문서를 읽을 수 있습니다)
- •음성 메시지 (텍스트로 변환되어 처리됩니다)
그룹 채팅 구성
OpenClaw는 세 가지 접근 모드로 Feishu 그룹 채팅을 지원합니다:
| 모드 | 동작 |
|---|---|
open (기본값) | @멘션 시 모든 그룹 멤버가 봇을 트리거할 수 있음 |
allowlist | @멘션해도 승인된 사용자만 상호작용 가능 |
disabled | 그룹 메시지를 완전히 무시 |
config.yaml에서 구성하세요:
channels:
feishu:
groupAccess: open # or "allowlist" or "disabled"
allowedUsers: # only used with "allowlist" mode
- user_id_1
- user_id_2
그룹 채팅에서 에이전트는 @멘션될 때만 응답하여 바쁜 채널에서의 노이즈를 방지합니다.
스트리밍 응답
OpenClaw는 인터랙티브 카드를 사용하여 Feishu에서 AI 응답 스트리밍을 지원합니다. 전체 응답을 기다리는 대신, 에이전트는 초기 카드를 보내고 AI가 텍스트를 생성함에 따라 실시간으로 업데이트합니다. 이것은 긴 응답에 대해 훨씬 더 나은 사용자 경험을 제공합니다.
스트리밍은 기본적으로 활성화되어 있습니다. 비활성화하려면:
channels:
feishu:
streaming: false
지원되는 메시지 유형
| 방향 | 지원 유형 |
|---|---|
| 인바운드 (사용자 → 에이전트) | 텍스트, 리치 텍스트 (post), 이미지, 파일, 오디오, 비디오, 스티커 |
| 아웃바운드 (에이전트 → 사용자) | 텍스트, 이미지, 파일, 오디오, 인터랙티브 카드 |
문제 해결
"App not found" 오류: 앱이 Feishu 테넌트에서 게시되고 승인되었는지 확인하세요. 기업 테넌트의 자체 구축 앱은 일반적으로 자동 승인되지만, 일부 조직은 관리자 승인이 필요합니다.
에이전트의 응답 없음: OpenClaw 로그(openclaw logs)에서 WebSocket 연결 오류를 확인하세요. App ID와 App Secret이 올바른지 확인하세요.
그룹 채팅에서 메시지가 도착하지 않는 경우: 봇이 그룹에 추가되어 있는지, 사용자가 봇을 올바르게 @멘션하고 있는지 확인하세요. groupAccess 설정을 확인하세요.
연결 끊김: WebSocket 연결은 자동으로 재연결됩니다. 끊김이 빈번하다면 네트워크 안정성이나 방화벽 설정을 확인하세요.
커뮤니티 브릿지 사용 (대안)
네이티브 통합을 넘어서는 기능이 필요하다면, AlexAnys가 관리하는 커뮤니티 feishu-openclaw 브릿지가 커스텀 메시지 포맷팅 및 고급 그룹 관리와 같은 추가 기능을 제공합니다. 설정에 약 5분이 걸리며 공개 서버가 필요하지 않습니다.
전체 문서는 공식 Feishu 채널 가이드를 참조하세요.