OpenClaw Feishu/Lark 통합 가이드: 앱 생성부터 메시지 송수신까지

Feishu와 Lark: 두 플랫폼, 하나의 통합 방식

Feishu와 Lark는 ByteDance에서 만든 기업용 메시징 플랫폼입니다. Feishu는 중국 본토 시장을, Lark는 해외 시장을 대상으로 합니다. 두 플랫폼은 동일한 아키텍처 기반이므로 통합 과정이 거의 같습니다.

OpenClaw는 Feishu/Lark와 두 가지 방법으로 연결할 수 있습니다:

이 가이드에서는 대부분의 사용 사례(약 90%)를 처리할 수 있는 내장 플러그인을 중심으로 설명합니다. 문서 읽기, 캘린더 관리, 태스크 생성 등 전체 워크스페이스 통합이 필요하다면 하단의 공식 Feishu 플러그인 섹션을 참고하십시오.

OpenClaw Feishu 설정 전 준비 사항

시작하기 전에 다음 항목을 확인하십시오:

• OpenClaw가 설치되어 실행 중이어야 합니다 (버전 ≥ 2026.2). 아직 설치하지 않았다면 설치 가이드를 참고하십시오.
• Feishu 개발자 계정이 필요합니다. open.feishu.cn (Feishu) 또는 open.larksuite.com (Lark)에서 생성할 수 있습니다.
• 게이트웨이가 접근 가능한 상태인지 다음 명령어로 확인하십시오:

openclaw gateway status

공인 IP나 도메인이 필요하지 않습니다. 내장 플러그인은 기본적으로 WebSocket 모드를 사용하며, Feishu 서버로 아웃바운드 연결을 수립합니다. NAT, 방화벽, 대부분의 기업 네트워크 환경에서 별도의 포트 포워딩 없이 작동합니다.

1단계: Feishu/Lark 봇 앱 생성

개발자 콘솔 접속

사용 중인 플랫폼에 맞는 개발자 포털에 접속합니다:

• Feishu (중국): open.feishu.cn → Developer Console
• Lark (해외): open.larksuite.com → Developer Console

애플리케이션 생성

1. Create Custom App (또는 "기업 자체 구축 애플리케이션")을 클릭합니다
2. 앱 이름을 입력합니다 — "OpenClaw Assistant"처럼 알기 쉬운 이름을 권장합니다
3. 선택적으로 아이콘과 설명을 추가합니다 (사용자가 봇 목록에서 보게 되는 정보입니다)

인증 정보 복사

1. 왼쪽 사이드바에서 Credentials & Basic Info로 이동합니다
2. App ID를 복사합니다 (예: cli_a5xxxxxxxxxxxxx)
3. App Secret을 복사합니다

⚠️ App Secret은 안전하게 보관하십시오. 버전 관리 시스템에 커밋하거나, 채팅에 붙여넣거나, 스크린샷에 포함하지 마십시오. 유출된 경우 즉시 개발자 콘솔에서 재발급하십시오.

2단계: Feishu 봇 권한 설정

앱이 메시지를 송수신하려면 특정 권한(scope)이 필요합니다. 두 가지 방법으로 설정할 수 있습니다.

방법 A: 일괄 가져오기 (권장)

JSON 블록을 붙여넣으면 모든 권한이 한 번에 활성화되므로 가장 빠른 방법입니다.

1. 앱 설정에서 Development Settings → Permission Management로 이동합니다
2. Batch Enable (또는 "Batch Import Scopes")을 클릭합니다
3. 다음 JSON을 붙여넣습니다:

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage", "application:bot.menu:write",
      "cardkit:card:write",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly", "event:ip_list"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

4. Confirm을 클릭하여 적용합니다

방법 B: 수동 선택

콘솔 버전에 따라 일괄 가져오기가 지원되지 않을 수 있습니다. 이 경우 Permission Management에서 다음 권한을 개별적으로 활성화하십시오:

• im:message — 메시지 송수신
• im:message:send_as_bot — 봇으로 메시지 발송
• im:message.p2p_msg:readonly — 1:1 메시지 읽기
• im:message.group_at_msg:readonly — 그룹 @멘션 메시지 읽기
• im:message.group_msg — 모든 그룹 메시지 읽기
• im:resource — 메시지 리소스 (이미지, 파일) 접근
• im:chat — 채팅 메타데이터 접근
• im:chat.members:bot_access — 봇의 채팅 멤버십 확인
• contact:user.employee_id:readonly — 사용자 ID 읽기
• docs:document.content:read — 문서 내용 읽기 (선택 사항, 문서 요약용)
• sheets:spreadsheet — 스프레드시트 접근 (선택 사항)
• wiki:wiki:readonly — 위키 페이지 읽기 (선택 사항)

문서, 스프레드시트, 위키 권한은 선택 사항입니다. 봇이 채팅에서 공유된 문서를 읽고 요약할 수 있도록 하려는 경우에만 활성화하십시오.

3단계: Feishu 봇 기능 및 이벤트 구독 활성화

봇 기능 활성화

1. 왼쪽 사이드바에서 App Capabilities → Bot으로 이동합니다
2. 봇 기능을 활성화합니다
3. 선택적으로 봇 설명과 도움말 텍스트를 설정합니다

이벤트 구독 설정

Feishu가 메시지를 OpenClaw 인스턴스로 전달하도록 하는 핵심 단계입니다.

1. Events & Callbacks → Event Subscriptions로 이동합니다
2. 연결 방식으로 **Long Connection (WebSocket)**을 선택합니다
3. 다음 이벤트를 추가합니다:

im.message.receive_v1 이벤트만 반드시 필요합니다. 이 이벤트가 없으면 봇이 어떤 메시지도 수신할 수 없습니다. 반응 이벤트는 이모지 응답에 기반한 동작을 트리거하려는 경우(예: 확인 시 좋아요 누르기)에 유용합니다.

⚠️ 이벤트 구독이 없으면 사용자가 봇과의 대화에서 입력창을 볼 수 없습니다. 사용자가 봇 프로필은 보이지만 메시지를 입력할 수 없다면 이 설정이 누락된 것이 거의 확실합니다.

⚠️ "app has not established a long connection" 오류의 가장 흔한 원인입니다. 로그에 이 오류가 나타나면 im.message.receive_v1 이벤트가 추가되어 있는지, Long Connection 모드가 선택되어 있는지 다시 확인하십시오.

4단계: Feishu 앱 배포

앱을 배포하기 전에는 사용자에게 표시되지 않습니다.

1. 왼쪽 사이드바에서 Version Management로 이동합니다
2. Create Version을 클릭합니다
3. 버전 번호(예: 1.0.0)와 릴리스 노트를 입력합니다
4. Submit for Review를 클릭합니다

테넌트 관리자가 생성한 기업 내부 앱의 경우 승인이 일반적으로 자동 처리됩니다. 일반 개발자의 경우 조직의 검토 프로세스에 따라 관리자 승인이 필요할 수 있습니다.

배포 완료 후:

1. Feishu (또는 Lark) 데스크톱이나 모바일 앱을 엽니다
2. 앱 디렉터리 또는 검색창으로 이동합니다
3. 앱 이름을 검색합니다
4. 봇이 목록에 표시되어야 합니다 — 하지만 아직 메시지를 보내지 마십시오. OpenClaw 설정을 먼저 완료해야 합니다.

5단계: OpenClaw Feishu 채널 설정

CLI를 이용한 빠른 설정

가장 빠르게 연결하는 방법입니다:

openclaw channels add    # "Feishu"를 선택한 후 App ID와 Secret을 입력합니다
openclaw gateway restart

CLI가 필수 설정 항목을 대화형으로 안내합니다.

수동 설정

더 세밀한 제어가 필요한 경우 ~/.openclaw/openclaw.json을 직접 편집합니다:

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Lark 해외 버전의 경우 "lark"를 사용합니다
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_a5xxxxxxxxxxxxx",
          appSecret: "your-app-secret",
          botName: "AI Assistant"
        }
      }
    }
  }
}

설정 옵션 참조

Feishu와 Lark의 차이: 설정에서 유일한 차이점은 domain 필드입니다. Feishu (중국)를 사용하는 조직은 "feishu"로, Lark (해외)를 사용하는 경우 "lark"로 설정하십시오. 인증 정보, 권한, 이벤트 등 나머지는 모두 동일합니다.

6단계: OpenClaw 게이트웨이 시작 및 Feishu 연결

게이트웨이 실행

openclaw gateway           # 게이트웨이를 시작합니다 (포그라운드)

별도의 터미널에서 로그를 확인합니다:

openclaw logs --follow     # 실시간 로그 스트리밍

다음과 같은 출력이 표시되어야 합니다:

[feishu] WebSocket connected to wss://open.feishu.cn/...
[feishu] Bot "AI Assistant" is online

계정 페어링

기본 DM 정책은 pairing으로, 새 사용자가 봇과 대화하기 전에 승인이 필요합니다. 이를 통해 무단 접근을 방지합니다.

1. Feishu (또는 Lark)를 열고 봇을 찾습니다
2. 아무 메시지나 보냅니다 — "hello"면 충분합니다
3. 터미널을 확인합니다. 코드가 포함된 페어링 요청이 표시됩니다:

[feishu] New pairing request from user_xxxxx (Code: ABC123)

4. 페어링을 승인합니다:

openclaw pairing approve feishu ABC123

5. Feishu/Lark로 돌아가서 다시 메시지를 보냅니다
6. AI가 응답해야 합니다

연결 상태 확인

openclaw gateway status

예상 출력:

Feishu: connected (websocket)
  Account: main
  Bot: AI Assistant
  Paired users: 1
  Active groups: 0

상태가 disconnected로 표시되면 하단의 문제 해결 섹션을 참고하십시오.

Feishu 그룹 채팅 설정

기본적으로 groupPolicy: "open" 설정은 봇이 추가된 모든 그룹에 참여할 수 있게 합니다. 더 엄격한 제어가 필요한 경우 허용 목록을 사용합니다:

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      requireMention: true,
      groups: {
        "oc_xxxxxxxxx": {           // Feishu 채팅 ID
          agentId: "main",
          requireMention: false      // 오버라이드: 이 그룹에서는 모든 메시지에 응답
        },
        "oc_yyyyyyyyy": {
          agentId: "support",        // 다른 에이전트로 라우팅
          requireMention: true
        }
      }
    }
  }
}

그룹의 채팅 ID를 확인하려면 봇을 그룹에 추가한 후 로그를 확인하십시오. 봇이 참여할 때 ID가 출력됩니다.

팁: requireMention: true를 전역으로 설정하고 그룹별로 오버라이드하십시오. 이렇게 하면 대규모 채널에서 봇이 불필요하게 반응하는 것을 방지하면서, 전용 AI 그룹에서는 자유롭게 대화할 수 있습니다.

Feishu Webhook 모드 설정

WebSocket이 권장 연결 방식이지만, 일부 기업 네트워크에서 지속적인 아웃바운드 WebSocket 연결을 차단하는 경우가 있습니다. 이 경우 webhook 모드로 전환합니다:

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "from-feishu-console",
      encryptKey: "from-feishu-console",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

검증 토큰과 암호화 키를 얻으려면:

1. Feishu 앱 설정에서 Events & Callbacks → Encryption Strategy로 이동합니다
2. Verification Token과 Encrypt Key를 복사합니다

그런 다음 Feishu 콘솔에서 요청 URL을 설정합니다:

1. Events & Callbacks → Event Subscriptions에서 Push to URL로 전환합니다
2. URL을 https://your-domain.com/feishu/events로 설정합니다
3. Verify를 클릭합니다 — Feishu가 챌린지 요청을 보내고 OpenClaw가 자동으로 응답합니다

⚠️ Webhook 모드는 공개적으로 접근 가능한 URL이 필요합니다. 도메인, TLS 인증서, 적절한 방화벽 규칙이 필요합니다. 대부분의 환경에서는 WebSocket이 훨씬 간편합니다.

Feishu 멀티 에이전트 라우팅

여러 AI 에이전트를 운영하는 경우 대화별로 다른 에이전트로 라우팅할 수 있습니다:

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "support", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxxxx" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxxxxxxxx" } } }
  ]
}

기본적으로 DM은 main 에이전트로 라우팅됩니다. 특정 사용자나 그룹은 별도의 에이전트로 라우팅할 수 있습니다. 이 기능은 범용 어시스턴트, 고객 지원 에이전트, 개발 도구 에이전트를 각각 다른 모델과 프롬프트로 운영하면서 동일한 Feishu 봇을 통해 제공하고자 하는 조직에 유용합니다.

OpenClaw 공식 Feishu 플러그인

공식 Feishu 플러그인은 ByteDance의 Feishu/Lark 팀에서 관리합니다. 봇으로 동작하는 내장 플러그인과 달리 OAuth를 사용하여 사용자를 대신하여 작업합니다. 이를 통해 문서, 캘린더, 태스크, 스프레드시트, 위키 등 전체 워크스페이스에 접근할 수 있습니다.

요구 사항

• OpenClaw ≥ 2026.2.26 (Linux/macOS) 또는 ≥ 2026.3.2 (Windows)
• Node.js ≥ 22
• npm이 PATH에 포함되어 있어야 합니다

설치

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

feishu-plugin-onboard install 명령어는 대화형 설정 마법사를 실행합니다. 다음 단계를 수행합니다:

1. Feishu App ID와 App Secret 입력 요청
2. OAuth 인증을 위한 브라우저 창 열기
3. ~/.openclaw/plugins/feishu/config.json에 설정 파일 생성
4. OpenClaw 인스턴스에 플러그인 등록

설치 후 확인

설치 후 플러그인이 로드되었는지 확인합니다:

openclaw plugins list

출력에 feishu-official이 표시되어야 합니다. 봇에 워크스페이스 작업을 요청하여 테스트합니다:

@Bot "Engineering" 위키 스페이스의 최신 문서를 요약해 주세요

진단

플러그인이 작동하지 않는 경우:

feishu-plugin-onboard doctor           # 일반적인 문제 확인
feishu-plugin-onboard doctor --fix     # 발견된 문제 자동 수정
feishu-plugin-onboard info --all       # 플러그인 상세 정보 보기

⚠️ 보안 관련 주의사항: 공식 플러그인은 개인 OAuth 토큰을 통해 워크스페이스 데이터에 접근합니다. 즉, 봇이 본인이 접근 권한을 가진 모든 문서, 캘린더 이벤트, 태스크를 읽을 수 있습니다. 공유 봇이나 공용 머신에서는 공식 플러그인을 사용하지 마십시오 — 개인용으로 보안이 확보된 인스턴스에서만 사용하십시오.

두 플러그인 동시 사용

내장 플러그인과 공식 플러그인을 동시에 실행할 수 있습니다. 내장 플러그인은 메시징을, 공식 플러그인은 워크스페이스 작업을 처리합니다. OpenClaw가 요청을 적절한 플러그인으로 자동 라우팅합니다.

공식 플러그인을 제거하지 않고 비활성화하려면:

feishu-plugin-onboard disable

OpenClaw Feishu 통합 문제 해결

"입력창이 없음" — 사용자가 봇에 메시지를 입력할 수 없는 경우

원인: 이벤트 구독이 누락되었거나 앱이 배포되지 않았습니다.

해결 방법:

1. Events & Callbacks에서 im.message.receive_v1이 추가되어 있는지 확인합니다
2. 연결 방식이 Long Connection으로 설정되어 있는지 확인합니다
3. 앱이 배포되었는지 확인합니다 (Version Management → 활성 버전 확인)
4. 게이트웨이를 재시작합니다: openclaw gateway restart

"App has not established a long connection" 오류

원인: Feishu 이벤트 구독이 WebSocket 연결을 기대하지만 OpenClaw가 아직 연결하지 않았습니다.

해결 방법:

1. 설정에서 connectionMode가 "websocket"인지 확인합니다
2. 게이트웨이를 재시작합니다: openclaw gateway restart
3. 로그를 확인합니다: openclaw logs --follow — WebSocket 연결 메시지를 찾습니다
4. 엄격한 프록시 환경에서는 아웃바운드 WebSocket 연결이 차단되지 않았는지 확인합니다

OpenClaw 봇이 온라인이지만 메시지에 응답하지 않는 경우

원인: 일반적으로 페어링 문제 또는 DM 정책 설정 오류입니다.

해결 방법:

1. 사용자가 페어링되었는지 확인합니다: openclaw pairing list feishu
2. pairing 모드를 사용 중이라면 사용자를 승인합니다: openclaw pairing approve feishu <CODE>
3. 페어링 없이 누구나 대화할 수 있게 하려면 dmPolicy: "open"으로 설정합니다
4. 로그에서 오류를 확인합니다: openclaw logs --follow

Feishu 봇이 그룹 채팅에서 응답하지 않는 경우

원인: 봇이 @멘션을 요구하지만 멘션되지 않았거나, 그룹 정책이 해당 그룹을 차단하고 있습니다.

해결 방법:

1. groupPolicy가 "open"이거나 해당 그룹이 허용 목록에 있는지 확인합니다
2. requireMention이 true이면 사용자가 봇을 @멘션해야 합니다
3. 봇이 실제로 그룹의 멤버인지 확인합니다
4. im:message.group_msg 권한이 활성화되어 있는지 확인합니다

"Message send failed" 또는 "send_as_bot" 오류

원인: im:message:send_as_bot 권한이 누락되었거나, 권한 추가 후 앱이 재배포되지 않았습니다.

해결 방법:

1. 개발자 콘솔에서 해당 권한이 활성화되어 있는지 확인합니다
2. 새 버전을 만들어 배포합니다 — 권한 변경 사항은 새 릴리스가 필요합니다
3. 게이트웨이를 재시작합니다

내장 플러그인과 공식 플러그인의 충돌

원인: 두 플러그인이 동일한 이벤트를 처리하려고 합니다.

해결 방법:

1. 일반적으로 문제가 되지 않습니다 — OpenClaw가 이벤트를 중복 제거합니다. 이중 응답이 발생하면 하나를 비활성화합니다:

feishu-plugin-onboard disable    # 공식 플러그인 비활성화
# 또는
openclaw channels disable feishu  # 내장 플러그인 비활성화

2. 실제로 필요한 플러그인이 어느 쪽인지 확인합니다 — 대부분의 사용자는 내장 플러그인만 있으면 충분합니다

Windows: 공식 플러그인 설치 시 ENOENT 오류

원인: npm이 다운로드된 .tgz 파일을 찾지 못하는 경로 문제입니다.

해결 방법:

1. 전체 절대 경로를 사용합니다:

npm install C:\Users\YourName\Downloads\feishu-plugin.tgz -g

2. 터미널을 관리자 권한으로 실행하고 있는지 확인합니다
3. Node.js ≥ 22인지 확인합니다: node --version

OpenClaw Feishu 명령어 참조

FAQ

공인 IP나 도메인이 필요합니까?

아닙니다. WebSocket 모드(기본값)는 사용자의 머신에서 Feishu 서버로 아웃바운드 연결을 수립합니다. 인바운드 트래픽, 포트 포워딩, DNS 레코드가 필요하지 않습니다. 유일한 예외는 webhook 모드로, 공개적으로 접근 가능한 URL이 필요합니다.

Feishu와 Lark의 차이점은 무엇입니까?

Feishu는 중국 본토용이고 Lark는 해외용입니다. 별도의 인프라에서 운영되지만 기능과 API는 동일합니다. 설정에서 유일한 차이는 domain 필드입니다. "feishu" 또는 "lark"로 설정하면 됩니다. App ID와 Secret은 생성한 플랫폼에서만 작동합니다.

내장 플러그인과 공식 플러그인 중 어느 것을 사용해야 합니까?

메시징(메시지 송수신, 채팅에서 공유된 콘텐츠 읽기)에는 내장 플러그인으로 충분합니다. 워크스페이스 작업(문서 읽기, 캘린더 관리, 태스크 생성, 스프레드시트 조회)에는 공식 플러그인을 사용하십시오. 두 플러그인을 동시에 실행할 수도 있습니다.

Feishu를 다른 채널과 함께 사용할 수 있습니까?

가능합니다. OpenClaw는 여러 채널을 동시에 지원합니다. Feishu, Telegram, Discord, WhatsApp 등을 동시에 운영할 수 있으며, 각각 같은 에이전트 또는 다른 에이전트에 연결할 수 있습니다. openclaw channels add로 추가하십시오.

응답이 느린 경우 어떻게 개선할 수 있습니까?

1. 스트리밍 활성화 (streaming: true) — 응답이 생성되는 대로 부분적으로 표시되어 사용자가 즉시 텍스트를 볼 수 있습니다
2. 모델 확인 — 대형 모델은 더 느립니다. 일상적인 질의에는 빠른 모델을 시도하십시오
3. 네트워크 지연 확인 — OpenClaw 인스턴스가 Feishu 서버와 멀리 떨어져 있으면 응답이 느리게 느껴집니다
4. 프롬프트 검토 — 긴 시스템 프롬프트는 처리 시간을 증가시킵니다

App Secret이 유출된 경우 어떻게 해야 합니까?

1. 즉시 Feishu 개발자 콘솔로 이동합니다
2. Credentials & Basic Info로 이동합니다
3. App Secret 옆의 Reset을 클릭합니다
4. 새로운 시크릿을 복사합니다
5. ~/.openclaw/openclaw.json의 값을 업데이트합니다
6. 게이트웨이를 재시작합니다: openclaw gateway restart
7. 이전 시크릿은 즉시 무효화됩니다 — 개별 세션을 취소할 필요가 없습니다

Feishu 설정 완료 후 다음 단계

Feishu/Lark 통합이 완료되었으면 OpenClaw의 다른 기능도 살펴보십시오:

• 50개 이상의 지원 채널 둘러보기 — 추가 플랫폼 연결
• Skills 디렉터리 — AI 어시스턴트가 할 수 있는 작업 확인
• 문제 해결 가이드 — 모든 채널의 일반적인 문제 해결
• OpenClaw 완전 초보 가이드 — OpenClaw 기초부터 학습
• Telegram 통합 — Telegram을 추가 채널로 설정
• Discord 통합 — Gateway Intents로 Discord 설정