본문으로 건너뛰기

Feishu / Lark

anchor alias​

Feishu / Lark 설정

Hermes 에이전트는 Feishu 및 Lark와 통합되어 완전한 기능을 갖춘 봇으로 작동합니다. 연결되면, 에이전트와 1:1 대화나 그룹 채팅에서 대화할 수 있고, 홈 채팅에서 크론 작업 결과를 받으며, 일반 게이트웨이 흐름을 통해 텍스트, 이미지, 오디오 및 파일 첨부를 보낼 수 있습니다.

통합은 두 가지 연결 모드를 지원합니다:

  • websocket — 권장; Hermes가 아웃바운드 연결을 열며 공개 웹훅 엔드포인트가 필요 없습니다
  • webhook — Feishu/Lark가 HTTP를 통해 이벤트를 게이트웨이로 푸시하도록 할 때 유용합니다

Hermes 작동 방식​

문맥행동
직접 메시지에르메스는 모든 메시지에 응답합니다.
단체 채팅Hermes는 채팅에서 봇이 @언급될 때만 응답합니다.
공유 그룹 채팅기본적으로 세션 기록은 공유 채팅 안에서 사용자별로 격리됩니다.

이 공유 채팅 동작은 config.yaml에 의해 제어됩니다:

group_sessions_per_user: true

한 채팅당 하나의 공유 대화를 명시적으로 원할 때만 false으로 설정하세요.

1단계: Feishu / Lark 앱 만들기​

hermes gateway setup

Feishu / Lark를 선택하고 Feishu 또는 Lark 모바일 앱으로 QR 코드를 스캔하세요. Hermes가 올바른 권한을 가진 봇 애플리케이션을 자동으로 생성하고 자격 증명을 저장합니다.

대안: 수동 설정​

스캔하여 생성 기능을 사용할 수 없는 경우, 마법사는 수동 입력으로 대체됩니다:

  1. Feishu 또는 Lark 개발자 콘솔을 엽니다:
  2. 새 앱을 만드세요.
  3. 자격 증명 및 기본 정보에서 앱 ID와 앱 비밀 키를 복사합니다.
  4. 앱에 대한 봇 기능을 활성화하세요.
  5. hermes gateway setup를 실행하고, Feishu / Lark를 선택한 후, 요청될 때 자격 증명을 입력하세요.
경고

앱 비밀을 비공개로 유지하세요. 이를 가진 사람은 누구든지 사용자의 앱을 사칭할 수 있습니다.

2단계: 연결 모드 선택​

Hermes가 노트북, 워크스테이션 또는 개인 서버에서 실행될 때 WebSocket 모드를 사용하세요. 공개 URL은 필요하지 않습니다. 공식 Lark SDK는 지속적인 아웃바운드 WebSocket 연결을 열고 유지하며 자동 재연결을 제공합니다.

FEISHU_CONNECTION_MODE=websocket

요구 사항: websockets Python 패키지가 설치되어 있어야 합니다. SDK는 연결 수명 주기, 하트비트 및 자동 재연결을 내부적으로 처리합니다.

작동 방식: 어댑터는 Lark SDK의 WebSocket 클라이언트를 백그라운드 실행기 스레드에서 실행합니다. 수신 이벤트(메시지, 리액션, 카드 액션)는 메인 asyncio 루프로 전달됩니다. 연결이 끊기면 SDK는 자동으로 재연결을 시도합니다.

선택 사항: 웹후크 모드​

Hermes를 접근 가능한 HTTP 엔드포인트 뒤에서 이미 실행하고 있을 때만 웹훅 모드를 사용하세요.

FEISHU_CONNECTION_MODE=webhook

웹훅 모드에서 Hermes는 HTTP 서버(aiohttp을 통해)를 시작하고 다음에서 Feishu 엔드포인트를 제공합니다:

/feishu/webhook

요구 사항: aiohttp Python 패키지가 설치되어 있어야 합니다.

웹훅 서버 바인드 주소와 경로를 사용자 정의할 수 있습니다:

FEISHU_WEBHOOK_HOST=127.0.0.1   # default: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # default: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # default: /feishu/webhook

Feishu가 URL 인증 챌린지(type: url_verification)를 보낼 때, 웹훅은 자동으로 응답하여 Feishu 개발자 콘솔에서 구독 설정을 완료할 수 있습니다.

3단계: Hermes 구성​

옵션 A: 대화형 설정​

hermes gateway setup

Feishu / Lark를 선택하고 프롬프트를 입력하세요.

옵션 B: 수동 설정​

~/.hermes/.env에 다음을 추가하세요:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# Optional but strongly recommended
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx
``FEISHU_DOMAIN` 수락:

- `feishu` 페이슈 차이나용
- Lark 국제용 `lark`

## 단계 4: 게이트웨이 시작 \{#step-4-start-the-gateway}

```bash
hermes gateway

그런 다음 Feishu/Lark에서 봇에게 메시지를 보내 연결이 활성화되어 있는지 확인하세요.

홈 채팅​

Feishu/Lark 채팅에서 /set-home를 사용하여 크론 작업 결과 및 크로스 플랫폼 알림의 기본 채널로 표시하세요.

또한 미리 구성할 수도 있습니다:

FEISHU_HOME_CHANNEL=oc_xxx

보안​

사용자 허용 목록​

프로덕션 사용을 위해 Feishu 오픈 ID 허용 목록을 설정하세요:

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

허용 목록을 비워 두면 봇에 접근할 수 있는 누구나 이를 사용할 수 있을 수 있습니다. 그룹 채팅에서는 메시지가 처리되기 전에 허용 목록이 발신자의 open_id와 대조됩니다.

웹훅 암호화 키​

웹훅 모드로 실행할 때, 수신 웹훅 페이로드의 서명 검증을 활성화하려면 암호화 키를 설정하십시오:

FEISHU_ENCRYPT_KEY=your-encrypt-key

이 키는 Feishu 앱 설정의 이벤트 구독(Event Subscriptions) 섹션에서 찾을 수 있습니다. 설정되면, 어댑터는 다음 서명 알고리즘을 사용하여 모든 웹후크 요청을 검증합니다:

SHA256(timestamp + nonce + encrypt_key + body)

계산된 해시는 타이밍 안전 비교를 사용하여 x-lark-signature 헤더와 비교됩니다. 잘못되었거나 누락된 서명이 있는 요청은 HTTP 401로 거부됩니다.

팁

WebSocket 모드에서는 서명 검증이 SDK 자체에 의해 처리되므로 FEISHU_ENCRYPT_KEY는 선택 사항입니다. 웹훅 모드에서는 운영 환경에서 사용하는 것이 강력히 권장됩니다.

인증 토큰​

웹훅 페이로드 내의 token 필드를 확인하는 추가 인증 계층:

FEISHU_VERIFICATION_TOKEN=your-verification-token

이 토큰은 또한 Feishu 앱의 이벤트 구독(Event Subscriptions) 섹션에서도 찾을 수 있습니다. 설정 시 모든 수신 웹훅 페이로드에는 header 객체 내에 일치하는 token가 포함되어야 합니다. 토큰이 일치하지 않으면 HTTP 401로 거부됩니다.

FEISHU_ENCRYPT_KEY와 FEISHU_VERIFICATION_TOKEN는 심층 방어를 위해 함께 사용할 수 있습니다.

그룹 메시지 정책​

FEISHU_GROUP_POLICY 환경 변수는 Hermes가 그룹 채팅에서 어떻게 반응하는지를 제어합니다:

FEISHU_GROUP_POLICY=allowlist   # default
가치행동
openHermes는 모든 그룹의 모든 사용자의 @멘션에 응답합니다.
allowlistHermes는 FEISHU_ALLOWED_USERS에 나열된 사용자의 @멘션에만 응답합니다.
disabled에르메스는 모든 그룹 메시지를 완전히 무시한다.

모든 모드에서, 메시지가 처리되기 전에 봇은 그룹에서 명시적으로 @멘션(또는 @all)되어야 합니다. 다이렉트 메시지는 항상 이 단계를 우회합니다.

FEISHU_REQUIRE_MENTION=false를 설정하여 Hermes가 @멘션 없이도 모든 그룹 트래픽을 읽도록 합니다:

FEISHU_REQUIRE_MENTION=false

채팅별 제어를 위해, group_rules 항목에 require_mention을 설정하세요 — 아래 그룹별 접근 제어를 참조하십시오.

봇 정체성​

Hermes는 시작 시 봇의 open_id 및 표시 이름을 자동으로 감지합니다. Feishu API에 자동 감지가 도달할 수 없거나, 앱이 테넌트 범위 사용자 ID를 사용할 때에만 수동으로 설정하면 됩니다:

FEISHU_BOT_OPEN_ID=ou_xxx     # only when auto-detection fails
FEISHU_BOT_USER_ID=xxx        # required if your app uses sender_id_type=user_id
FEISHU_BOT_NAME=MyBot         # only when auto-detection fails

봇 간 메시징​

기본적으로 Hermes는 다른 봇이 보낸 메시지를 무시합니다. Hermes가 오케스트레이션에 참여하거나 동일한 그룹의 다른 봇으로부터 알림을 받도록 하려면 봇 간 메시징을 활성화하십시오.

FEISHU_ALLOW_BOTS=mentions   # default: none
가치행동
none다른 봇의 모든 메시지를 무시합니다 (기본값).
mentions피어 봇이 Hermes를 @멘션할 때만 수락하십시오.
all모든 피어 봇 메시지를 수락하세요.

또한 config.yaml에서 feishu.allow_bots으로 구성할 수 있습니다(둘 다 설정된 경우 환경 변수가 우선합니다).

동료 봇은 FEISHU_ALLOWED_USERS에 추가할 필요가 없습니다 — 이 허용 목록은 인간 발신자에게만 적용됩니다.

피어 봇 이름을 표시하려면 application:bot.basic_info:read 범위를 부여하십시오; 없으면 피어 봇은 여전히 올바르게 라우팅되지만 open_id으로 표시됩니다.

인터랙티브 카드 액션​

사용자가 버튼을 클릭하거나 봇이 보낸 대화형 카드와 상호작용할 때, 어댑터는 이를 합성 /card 명령 이벤트로 라우팅합니다:

  • 버튼 클릭이 다음이 됩니다: /card button {"key": "value",...}
  • 카드 정의에서 액션의 value 페이로드가 JSON으로 포함됩니다.
  • 카드 작업은 중복 처리를 방지하기 위해 15분 창으로 중복 제거됩니다.

게이트웨이 기반 업데이트 프롬프트는 일반 텍스트 응답으로 넘어가지 않고 네이티브 Feishu Yes / No 카드를 사용합니다. hermes update --gateway가 확인이 필요할 때, 어댑터는 선택된 답변을 Hermes의 .update_response 파일에 기록하고 카드를 해결된 상태로 인라인 대체합니다.

카드 액션 이벤트는 MessageType.COMMAND와 함께 전달되므로, 정상적인 명령 처리 파이프라인을 통해 흐릅니다.

이것이 명령 승인이 작동하는 방식이기도 합니다 — 에이전트가 위험한 명령을 실행해야 할 때, Allow Once / Session / Always / Deny 버튼이 있는 인터랙티브 카드를 보냅니다. 사용자가 버튼을 클릭하면, 카드 액션 콜백이 승인 결정을 에이전트에게 전달합니다.

필수 Feishu 앱 구성​

대화형 카드는 Feishu 개발자 콘솔에서 세 가지 구성 단계를 필요로 합니다. 이 중 하나라도 누락되면 사용자가 카드 버튼을 클릭할 때 오류 200340이 발생합니다.

  1. 카드 액션 이벤트 구독: 이벤트 구독에서, 구독한 이벤트에 card.action.trigger을 추가하세요.

  2. 인터랙티브 카드 기능 활성화: 앱 기능 > 봇에서 인터랙티브 카드 토글이 활성화되어 있는지 확인하세요. 이는 Feishu에 귀하의 앱이 카드 동작 콜백을 받을 수 있음을 알립니다.

  3. 카드 요청 URL 구성(웹훅 모드 전용): 앱 기능 > 봇 > 메시지 카드 요청 URL에서 URL을 이벤트 웹훅과 동일한 엔드포인트로 설정합니다(예: https://your-server:8765/feishu/webhook). WebSocket 모드에서는 SDK가 이를 자동으로 처리합니다.

경고

세 가지 단계가 모두 이루어지지 않으면, Feishu는 인터랙티브 카드를 성공적으로 보낼 수 있습니다 (전송은 im:message:send 권한만 필요함), 그러나 어떤 버튼을 클릭해도 오류 200340이 반환됩니다. 카드는 작동하는 것처럼 보이지만 — 사용자가 상호작용할 때만 오류가 나타납니다.

문서 주석 인텔리전트 답변​

채팅을 넘어, 어댑터는 Feishu/Lark 문서에 남겨진 @ 멘션에도 답할 수 있습니다. 사용자가 문서에 댓글을 달고(로컬 텍스트 선택 또는 전체 문서 댓글) 봇을 @-멘션하면, Hermes는 문서와 주변 댓글 스레드를 읽고 스레드 내에 LLM 답변을 게시합니다.

drive.notice.comment_add_v1 이벤트에 의해 구동되는 핸들러:

  • 문서 내용과 댓글 타임라인을 병렬로 가져옵니다(전체 문서 스레드는 20개 메시지, 로컬 선택 스레드는 12개 메시지).
  • 해당 단일 댓글 세션에 범위를 지정한 상태에서 feishu_doc + feishu_drive 도구 세트로 에이전트를 실행합니다.
  • 응답을 4000자 단위로 나누어 스레드 형식으로 다시 게시합니다.
  • 문서별 세션을 1시간 동안 캐시하며, 최대 50개의 메시지 제한이 있어 동일한 문서에 대한 후속 댓글이 맥락을 유지합니다.

3단계 접근 제어​

문서-댓글 답장은 명시적 부여만 가능하며 — 모든 허용 암묵적 모드는 없습니다. 권한은 다음 순서로 해석됩니다(첫 번째 일치 항목이 우선, 필드별):

  1. 정확한 문서 — 특정 문서 토큰에 범위가 지정된 규칙.
  2. 와일드카드 — 문서 패턴과 일치하는 규칙.
  3. 최상위 — 작업 공간의 기본 규칙.

규칙별로 두 가지 정책을 사용할 수 있습니다:

  • allowlist — 사용자 / 테넌트의 정적 목록.
  • pairing — 정적 목록 ∪ 런타임 승인 저장소. 관리자가 실시간으로 접근 권한을 부여할 수 있는 롤아웃에 유용합니다.

규칙은 ~/.hermes/feishu_comment_rules.json에 존재하며 (~/.hermes/feishu_comment_pairing.json에서 페어링 권한 부여) mtime 캐시된 핫 리로드와 함께 작동합니다 — 수정 사항은 게이트웨이를 재시작하지 않고 다음 댓글 이벤트에서 바로 적용됩니다.

CLI:

# Inspect current rules and pairing state
python -m gateway.platforms.feishu_comment_rules status

# Simulate an access check for a specific doc + user
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> &lt;user_open_id&gt;

# Manage pairing grants at runtime
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add &lt;user_open_id&gt;
python -m gateway.platforms.feishu_comment_rules pairing remove &lt;user_open_id&gt;

필수 Feishu 앱 구성​

이미 부여된 채팅/카드 권한 위에 드라이브 댓글 이벤트를 추가하세요:

  • 이벤트 구독에서 drive.notice.comment_add_v1을(를) 구독하세요.
  • 핸들러가 문서 내용을 읽을 수 있도록 docs:doc:readonly 및 drive:drive:readonly 범위를 부여하세요.

미디어 지원​

수입(수신)​

어댑터는 사용자로부터 다음 미디어 유형을 수신하고 캐시합니다:

유형확장 프로그램그것이 처리되는 방식
이미지.jpg,.jpeg,.png,.gif,.webp,.bmpFeishu API를 통해 다운로드되어 로컬에 캐시됨
오디오.ogg,.mp3,.wav,.m4a,.aac,.flac,.opus,.webm다운로드 및 캐시됨; 작은 텍스트 파일은 자동으로 추출됨
비디오.mp4,.mov,.avi,.mkv,.webm,.m4v,.3gp문서로 다운로드되어 캐시됨
파일.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx 등문서로 다운로드되어 캐시됨

인라인 이미지 및 파일 첨부를 포함한 리치 텍스트(게시물) 메시지의 미디어도 추출되어 캐시됩니다.

작은 텍스트 기반 문서(.txt,.md)의 경우, 파일 내용이 메시지 텍스트에 자동으로 삽입되어 에이전트가 도구를 사용할 필요 없이 직접 읽을 수 있습니다.

발신​

방법그것이 보내는 것
send텍스트 또는 리치 게시물 메시지(마크다운 내용을 기반으로 자동 감지됨)
send_image / send_image_file이미지를 Feishu에 업로드한 후, 네이티브 이미지 버블로 전송합니다 (선택적 캡션 포함 가능)
send_document파일을 Feishu API에 업로드한 후 파일 첨부로 전송합니다
send_voice오디오 파일을 Feishu 파일 첨부로 업로드합니다
send_video비디오를 업로드하고 네이티브 미디어 메시지로 보냅니다
send_animationGIF는 파일 첨부로 다운그레이드됩니다(Feishu에는 기본 GIF 버블이 없습니다)

파일 업로드 라우팅은 확장자를 기반으로 자동입니다:

  • .ogg, .opus → opus 오디오로 업로드됨
  • .mp4, .mov, .avi, .m4v → mp4 미디어로 업로드됨
  • .pdf, .doc(x), .xls(x), .ppt(x) → 해당 문서 종류와 함께 업로드됨
  • 나머지 모든 것 → 일반 스트림 파일로 업로드됨

마크다운 렌더링 및 게시물 대체​

발신 텍스트에 마크다운 형식(헤딩, 굵게, 목록, 코드 블록, 링크 등)이 포함되어 있는 경우, 어댑터는 이를 일반 텍스트로 보내는 대신 Feishu 게시물(post) 메시지로 md 태그를 포함하여 자동으로 전송합니다. 이는 Feishu 클라이언트에서 풍부한 렌더링을 가능하게 합니다.

Feishu API가 게시 페이로드를 거부하면(예: 지원되지 않는 마크다운 구문 때문에), 어댑터는 자동으로 마크다운이 제거된 일반 텍스트로 전송하도록 폴백됩니다. 이 두 단계 폴백은 메시지가 항상 전달되도록 보장합니다.

일반 텍스트 메시지(마크다운 미감지)는 단순한 text 메시지 유형으로 전송됩니다.

처리 상태 반응​

에이전트가 작업하는 동안, 봇은 당신의 메시지에 Typing 반응을 표시합니다. 답장이 도착하면 제거되거나, 처리에 실패하면 CrossMark로 대체됩니다.

끄려면 FEISHU_REACTIONS=false를 설정하세요.

폭발 방지 및 배치 처리​

어댑터에는 에이전트를 압도하지 않도록 빠른 메시지 연속 발생에 대한 디바운싱이 포함되어 있습니다:

텍스트 배치​

사용자가 여러 개의 문자 메시지를 빠르게 연달아 보내면, 전송되기 전에 하나의 이벤트로 합쳐집니다:

설정환경 변수기본값
조용한 기간HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS0.6s
배치당 최대 메시지HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES8
배치당 최대 문자 수HERMES_FEISHU_TEXT_BATCH_MAX_CHARS4000

미디어 배칭​

여러 개의 미디어 첨부 파일이 빠르게 연속으로 전송될 경우(예: 여러 이미지를 끌어다 놓는 경우), 하나의 이벤트로 합쳐집니다:

설정환경 변수기본값
조용한 기간HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS0.8s

채팅별 직렬화​

같은 채팅 내의 메시지는 대화의 일관성을 유지하기 위해 순차적으로(한 번에 하나씩) 처리됩니다. 각 채팅은 자체적인 잠금 장치를 가지므로, 다른 채팅의 메시지는 동시에 처리됩니다.

속도 제한 (웹훅 모드)​

웹훅 모드에서 어댑터는 남용을 방지하기 위해 IP별 속도 제한을 시행합니다:

  • 윈도우: 60초 슬라이딩 윈도우
  • 제한: (app_id, 경로, IP) 삼중조합 당 창(window)마다 120회 요청
  • 추적 한도: 최대 4096개의 고유 키 추적 (무제한 메모리 증가 방지)

한도를 초과하는 요청은 HTTP 429(요청이 너무 많음)를 받습니다.

웹훅 이상 추적​

어댑터는 IP 주소별로 연속적인 오류 응답을 추적합니다. 동일한 IP에서 6시간 동안 25회 연속 오류가 발생하면 경고가 기록됩니다. 이는 잘못 구성된 클라이언트나 탐색 시도를 감지하는 데 도움이 됩니다.

추가 웹훅 보호:

  • 본체 크기 제한: 최대 1 MB
  • 본문 읽기 시간 초과: 30초
  • Content-Type 강제 적용: application/json만 허용됩니다

웹소켓 조정​

websocket 모드를 사용할 때 재연결 및 핑 동작을 사용자화할 수 있습니다:

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # Seconds between reconnect attempts (default: 120)
      ws_ping_interval: 30         # Seconds between WebSocket pings (optional; SDK default if unset)
설정구성 키기본값설명
재연결 간격ws_reconnect_interval120s재접속 시도 간 기다려야 하는 시간
핑 간격ws_ping_interval(SDK 기본값)웹소켓 킵얼라이브 핑 빈도

그룹별 접근 제어​

글로벌 FEISHU_GROUP_POLICY를 넘어서, config.yaml의 group_rules를 사용하여 그룹 채팅별로 세밀한 규칙을 설정할 수 있습니다:

platforms:
  feishu:
    extra:
      default_group_policy: "open"     # Default for groups not in group_rules
      admins:                          # Users who can manage bot settings
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # 재정의s FEISHU_REQUIRE_MENTION for this chat
정책설명
open그 그룹에 있는 누구나 봇을 사용할 수 있습니다
allowlist그룹의 allowlist 내 사용자만 봇을 사용할 수 있습니다
blacklist그룹의 blacklist에 속한 사용자를 제외한 모든 사람이 봇을 사용할 수 있습니다
admin_only이 그룹에서 봇을 사용할 수 있는 사람은 전 세계 admins 목록에 있는 사용자만 가능합니다.
disabled봇은 이 그룹의 모든 메시지를 무시합니다

특정 채팅에 대해 @-멘션 요구 사항을 건너뛰려면 group_rules 항목에 require_mention: false을 설정하세요. 생략하면 채팅은 전역 FEISHU_REQUIRE_MENTION 값을 상속합니다.

group_rules에 나열되지 않은 그룹은 default_group_policy로 되돌아갑니다(FEISHU_GROUP_POLICY의 값으로 기본 설정됨).

중복 제거​

수신 메시지는 24시간 TTL을 가진 메시지 ID를 사용하여 중복 제거됩니다. 중복 상태는 재시작 시에도 ~/.hermes/feishu_seen_message_ids.json에 걸쳐 유지됩니다.

설정환경 변수기본값
캐시 크기HERMES_FEISHU_DEDUP_CACHE_SIZE2048개 항목

모든 환경 변수​

변수필수기본값설명
FEISHU_APP_ID✅—Feishu/Lark 앱 ID
FEISHU_APP_SECRET✅—Feishu/Lark 앱 비밀
FEISHU_DOMAIN—feishufeishu (중국) 또는 lark (국제)
FEISHU_CONNECTION_MODE—websocketwebsocket 또는 webhook
FEISHU_ALLOWED_USERS—(비어 있음)사용자 허용 목록을 위한 쉼표로 구분된 open_id 목록
FEISHU_ALLOW_BOTS—none다른 봇의 메시지 수락: none, mentions, 또는 all
FEISHU_REQUIRE_MENTION—true그룹 메시지가 봇을 @언급해야 하는지 여부
FEISHU_HOME_CHANNEL——크론/알림 출력용 채팅 ID
FEISHU_ENCRYPT_KEY—(비어 있음)웹훅 서명 검증을 위한 키 암호화
FEISHU_VERIFICATION_TOKEN—(비어 있음)웹훅 페이로드 인증을 위한 검증 토큰
FEISHU_GROUP_POLICY—allowlist그룹 메시지 정책: open, allowlist, disabled
FEISHU_BOT_OPEN_ID—(비어 있음)봇의 open_id (@멘션 감지를 위해)
FEISHU_BOT_USER_ID—(비어 있음)봇의 사용자 ID (@멘션 감지를 위해)
FEISHU_BOT_NAME—(비어 있음)봇의 표시 이름 (@멘션 감지를 위해)
FEISHU_WEBHOOK_HOST—127.0.0.1웹훅 서버 바인드 주소
FEISHU_WEBHOOK_PORT—8765웹훅 서버 포트
FEISHU_WEBHOOK_PATH—/feishu/webhook웹훅 엔드포인트 경로
HERMES_FEISHU_DEDUP_CACHE_SIZE—2048최대 중복 제거된 메시지 ID를 추적
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS—0.6텍스트 버스트 디바운스 조용한 기간
HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES—8텍스트 배치당 병합된 최대 메시지
HERMES_FEISHU_TEXT_BATCH_MAX_CHARS—4000텍스트 배치당 병합된 최대 문자 수
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS—0.8미디어 버스트 디바운스 조용한 기간

WebSocket 및 그룹별 ACL 설정은 platforms.feishu.extra 아래의 config.yaml을 통해 구성됩니다(위의 WebSocket 튜닝 및 그룹별 접근 제어 참조).

문제 해결​

문제고치다
lark-oapi not installedSDK 설치: pip install lark-oapi
websockets not installed; websocket mode unavailable웹소켓 설치: pip install websockets
aiohttp not installed; webhook mode unavailableaiohttp 설치: pip install aiohttp
FEISHU_APP_ID or FEISHU_APP_SECRET not set두 환경 변수를 모두 설정하거나 hermes gateway setup를 통해 구성하세요
Another local Hermes gateway is already using this Feishu app_id한 번에 하나의 Hermes 인스턴스만 동일한 app_id를 사용할 수 있습니다. 먼저 다른 게이트웨이를 중지하세요.
봇이 그룹에서 응답하지 않습니다봇이 @멘션되었는지 확인하고, FEISHU_GROUP_POLICY 을 확인하며, 정책이 allowlist 인 경우 발신자가 FEISHU_ALLOWED_USERS 에 있는지 확인하세요
Webhook rejected: invalid verification tokenFEISHU_VERIFICATION_TOKEN가 Feishu 앱의 이벤트 구독 설정에 있는 토큰과 일치하는지 확인하세요
Webhook rejected: invalid signatureFEISHU_ENCRYPT_KEY가 Feishu 앱 설정의 암호화 키와 일치하는지 확인하세요
게시물 메시지가 일반 텍스트로 표시됩니다Feishu API가 게시 페이로드를 거부했습니다. 이는 정상적인 대체 동작입니다. 자세한 내용은 로그를 확인하세요.
봇이 이미지를/파일을 받지 못했습니다Feishu 앱에 im:message 및 im:resource 권한 범위를 부여하세요
봇 아이덴티티가 자동으로 감지되지 않음보통 Feishu의 봇 정보 엔드포인트에 접근하는 일시적인 네트워크 문제입니다. 해결 방법으로 FEISHU_BOT_OPEN_ID과 FEISHU_BOT_NAME을 수동으로 설정하세요.
FEISHU_ALLOW_BOTS을 활성화한 후에도 동료 봇 메시지는 여전히 무시됩니다Hermes는 아직 자신을 식별할 수 없습니다 — FEISHU_BOT_OPEN_ID를 설정하세요 (앱이 sender_id_type=user_id를 사용하는 경우 FEISHU_BOT_USER_ID도 설정하세요).
동료 봇이 이름 대신 ou_xxxxxx로 표시됩니다application:bot.basic_info:read 범위를 허용합니다.
승인 버튼을 클릭할 때 오류 200340Feishu 개발자 콘솔에서 인터랙티브 카드 기능을 활성화하고 카드 요청 URL을 설정하세요. 자세한 내용은 위의 필수 Feishu 앱 구성을 참조하세요.
Webhook rate limit exceeded같은 IP에서 분당 120건 이상의 요청이 있습니다. 이는 보통 잘못된 구성이나 루프 때문입니다.

도구 세트​

Feishu / Lark은 Telegram 및 기타 게이트웨이 기반 메시징 플랫폼과 동일한 핵심 도구를 포함하는 hermes-feishu 플랫폼 프리셋을 사용합니다.