메인 콘텐츠로 건너뛰기
飞书频道为一个组织中的智能体提供了一条进入飞书群组的单一热线：出站通知、入站回复和交互式的批准/拒绝卡片（通过 feishu_gate hook）。 本指南介绍端到端的设置步骤。它假设 FIM One 可在稳定的 HTTPS 源访问 — 称之为 API_BASE_URL（例如 https://one.yourdomain.com）。

​
1. Feishu 앱 생성

  1. Feishu Open Platform으로 이동하여 Create custom app for enterprise를 클릭합니다.
  2. 앱의 이름, 아이콘, 간단한 설명을 입력합니다 — 조직의 최종 사용자가 카드에서 이를 볼 수 있습니다.
  3. Credentials & Basic Info 페이지에서 App ID와 App Secret을 복사합니다. 4단계에서 FIM One에 붙여넣을 것입니다.
App Secret을 비밀번호처럼 취급하세요. FIM One은 저장 시 암호화하지만, 평문 복사본을 가진 누구나 봇을 가장할 수 있습니다.

​
2. 권한 부여

Permissions & Scopes 아래에서 다음 범위를 활성화하고 권한 버전을 제출합니다:
Scope이유
im:message메시지 전송 (텍스트 + 카드)
im:message:send_as_bot봇 신원으로 게시
im:chat봇이 속한 그룹 채팅 나열 및 읽기
im:chat:readonly그룹 검색을 위한 최소 읽기 액세스
im:resource(선택사항) 카드에 표시된 이미지/파일 업로드

​
3. 이벤트 구독 활성화 (지금은 Request URL을 비워두세요)

Event Subscriptions를 열되, 아직 Request URL을 입력하지 마세요 — 5단계에서 FIM One에서 가져옵니다. 다음 이벤트를 구독하세요:
  • im.message.receive_v1 — 사용자로부터의 인바운드 메시지
  • card.action.trigger — 승인 / 거부 버튼 클릭
동일한 페이지에서 선택적으로 Verification Token과 Encrypt Key를 설정할 수 있습니다. FIM One은 두 모드를 모두 지원하며 제공된 것을 사용합니다.

​
4. FIM One에서 채널 추가

  1. 조직 소유자 또는 관리자로 로그인합니다.
  2. 조직 설정 → 채널 → 새 채널로 이동합니다.
  3. 유형으로 Feishu를 선택한 후 다음을 입력합니다:
    필드출처
    Name내부 레이블 (예: Ops team Feishu)
    App ID1단계에서 (cli_xxxxxxxxxxxxxxxx)
    App Secret1단계에서
    Verification Token(선택사항) 3단계에서
    Encrypt Key(선택사항) 3단계에서
  4. Browse chats를 클릭합니다 — FIM One이 당신의 자격증명으로 Feishu를 호출하고 봇이 현재 멤버인 모든 그룹을 나열합니다.
목록이 비어 있으면 봇이 아직 어떤 그룹에도 추가되지 않은 것입니다. Feishu를 열어 대상 그룹에 봇을 추가한 후 선택기를 다시 엽니다.
  1. 라우팅할 그룹 채팅을 선택하고 Save를 클릭합니다.

​
5. Feishu에 콜백 URL 등록

저장 후 FIM One은 채널 상세 패널에 다음과 같은 형태의 Callback URL을 표시합니다: 
{API_BASE_URL}/api/channels/{CHANNEL_ID}/callback
이를 복사하여 Feishu Event Subscriptions 페이지로 돌아가 Request URL에 붙여넣은 후 Verify를 클릭합니다. Feishu는 일회성 url_verification 챌린지를 POST로 전송하며, FIM One이 자동으로 응답합니다.

​
6. 테스트 메시지 전송

FIM One 채널 상세 패널로 돌아가서 Send test message를 클릭합니다. 짧은 평문 메시지(FIM One test message from <your email>)가 대상 그룹에 1초 이내에 나타나야 합니다. 나타나지 않으면:
  • 401 / 403 — App Secret을 다시 확인하고, 2단계에서 스코프를 다시 활성화한 후, 권한 버전을 다시 게시합니다.
  • Silent failure — 봇이 실제로 그룹에 있는지(4단계 선택기) 확인하고 채널 행의 is_active가 true인지 확인합니다.
  • 5단계에서 검증 실패 — API_BASE_URL이 HTTPS이고 공개적으로 접근 가능한지 확인합니다. Feishu는 비-HTTPS 요청 URL을 거부합니다.

​
7. 智能体 연결 (선택사항 — 승인)

도구 호출을 그룹 승인으로 제어하려면:
  1. 도구 / 커넥터 작업에서 Requires confirmation을 켭니다.
  2. 智能体에서 Hooks → Class hooks 아래에 feishu_gate를 추가합니다.
  3. 智能体의 조직이 정확히 하나의 활성 Feishu 채널을 가지고 있는지 확인합니다 — 훅이 자동으로 라우팅됩니다.
智能体가 제어된 도구를 실행하려고 할 때, Approve / Reject 버튼이 있는 대화형 카드가 그룹에 게시됩니다. 도구는 대기 상태(SSE 스트림 일시 중지)이며 멤버가 하나를 탭할 때까지 기다립니다. 결과가 스트림으로 돌아오고 智能体는 완료되거나 중단됩니다.

​
문제 해결

​
chat_id 선택기 없이 찾기

채팅 찾아보기 UI가 권장되는 흐름입니다. 원본 ID가 필요한 경우(예: 스크립팅에서 POST /api/channels 호출), 세 가지 대체 방법이 있습니다: a. Feishu에 대해 curl 실행 
APP_ID="cli_xxxxxxxxxxxxxxxx"
APP_SECRET="<your-app-secret>"

TOKEN=$(curl -s -X POST \
  "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")

curl -s "https://open.feishu.cn/open-apis/im/v1/chats?page_size=50" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
응답의 모든 items[].chat_id(oc_ 접두사 포함)가 후보입니다. b. Feishu API Explorer Feishu Open Platform 콘솔에서 Dev Tools → API Explorer를 열고, /open-apis/im/v1/chats를 찾은 다음, tenant_access_token 인증을 선택하고 Invoke를 클릭합니다. Feishu가 토큰을 생성해줍니다 — 셸이 필요하지 않습니다. c. Feishu 클라이언트에서 복사 Feishu 데스크톱 또는 모바일 클라이언트에서 그룹을 열고 → 그룹 설정 → 그룹 정보에서 일부 버전은 그룹 ID 복사 옵션을 제공합니다. 가용성은 클라이언트 버전 및 관리자 설정 권한에 따라 다르므로, 이것이 가장 신뢰성이 낮은 대체 방법입니다.

​
카드 클릭이 FIM One에 도달하지 않음 (오류 200340)

Approve 또는 Reject를 카드에서 클릭할 때 Feishu 클라이언트에서 出错了，请稍后重试 code: 200340이 표시되면 다음 목록을 확인하세요:
  1. card.action.trigger을 구독해야 함 (3단계). 구독하기 전에 승인 게이트를 활성화한 경우 Feishu 콘솔에서 Resubscribe를 클릭하세요.
  2. 콜백 URL을 다시 저장하세요. Feishu는 때때로 재시작 후에도 지속되는 오래된 구독 상태를 캐시합니다 — URL 검증 핸드셰이크가 여전히 통과하더라도 이벤트 라우팅이 조용히 중단될 수 있습니다. Feishu 오픈 플랫폼의 이벤트 구독 페이지를 열고 정확히 동일한 콜백 URL을 다시 입력한 후 Save / Verify를 다시 클릭하세요. URL이 한 번의 왕복으로 다시 검증되고 다음 버튼 클릭 시 라이브 버튼 클릭이 흐르기 시작합니다. 이것은 채널이 어제는 작동했지만 코드 변경 없이 오늘 중단된 경우 가장 일반적인 해결책입니다.
  3. Event Debugger 확인 Feishu 오픈 플랫폼에서 (事件与回调 → 事件调试). 각 버튼 클릭은 배달 상태(2xx / 4xx / 未投递)와 함께 표시되어야 합니다. 未投递가 표시되면 Feishu 자체가 전송하기 전에 이벤트를 거부하고 있습니다 — 일반적으로 누락된 범위 또는 비활성화된 구독입니다.
  4. 범위 확인. 权限管理에서 앱에 im:message와 테넌트에 필요한 모든 card 관련 범위가 있는지 확인하세요. 누락된 범위는 구독이 UI에서 녹색으로 표시되지만 배달 시 이벤트가 조용히 삭제되는 것으로 나타납니다.

​
승인/거부 버튼을 반복적으로 클릭할 수 있습니다

웹훅은 이제 첫 번째 결정에서 대체 카드를 반환합니다 — 버튼이 제거되고 카드 헤더가 녹색(승인됨) 또는 빨간색(거부됨)으로 바뀝니다. 첫 번째 클릭 후에도 클릭 가능한 버튼이 보이면 Feishu 클라이언트가 캐시된 복사본을 표시하고 있을 수 있습니다. 채팅을 다시 열면 결정된 카드가 렌더링됩니다.

​
하나의 조직, 두 개의 Feishu 채널

feishu_gate는 찾은 첫 번째 활성 채널을 선택합니다. 동일한 조직에서 여러 Feishu 엔드포인트가 필요한 경우(예: 스테이징 vs. 프로덕션 그룹), 하나를 제외한 모두를 비활성화하거나 에이전트 태그로 선택하는 커스텀 훅을 작성하세요.