Feishu 봇

Feishu (Lark) 는 기업에서 메시징과 협업을 위해 사용하는 팀 채팅 플랫폼입니다. 이 플러그인은 플랫폼의 WebSocket 이벤트 구독을 사용하여 OpenClaw 를 Feishu/Lark 봇에 연결하므로, 공개 webhook URL 을 노출하지 않고도 메시지를 수신할 수 있습니다.

필요한 플러그인

Feishu 플러그인을 설치합니다:

openclaw plugins install @openclaw/feishu

로컬 체크아웃 (git repo 에서 실행하는 경우):

openclaw plugins install ./extensions/feishu

빠른 시작

Feishu 채널을 추가하는 방법은 두 가지가 있습니다:

방법 1: 온보딩 마법사 (권장)

OpenClaw 를 방금 설치했다면 마법사를 실행합니다:

openclaw onboard

마법사는 다음 과정을 안내합니다:

Feishu 앱 생성 및 자격 증명 수집
OpenClaw 에 앱 자격 증명 구성
Gateway(게이트웨이) 시작

✅ 구성 후, Gateway 상태를 확인합니다:

openclaw gateway status
openclaw logs --follow

방법 2: CLI 설정

이미 초기 설치를 완료했다면 CLI 를 통해 채널을 추가합니다:

openclaw channels add

Feishu 를 선택한 다음 App ID 와 App Secret 을 입력합니다. ✅ 구성 후, Gateway 를 관리합니다:

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

1단계: Feishu 앱 생성

1. Feishu Open Platform 열기

Feishu Open Platform 에 접속하여 로그인합니다. Lark (글로벌) 테넌트는 https://open.larksuite.com/app 을 사용하고 Feishu 설정에서 domain: "lark" 를 설정해야 합니다.

2. 앱 생성

Create enterprise app 을 클릭합니다
앱 이름과 설명을 입력합니다
앱 아이콘을 선택합니다

3. 자격 증명 복사

Credentials & Basic Info 에서 다음을 복사합니다:

App ID (형식: cli_xxx)
앱 시크릿

❗ 중요: App Secret 은 반드시 비공개로 유지하십시오. Get credentials

4. 권한 구성

Permissions 에서 Batch import 를 클릭하고 다음을 붙여넣습니다:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

5. 봇 기능 활성화

App Capability > Bot 에서:

봇 기능을 활성화합니다
봇 이름을 설정합니다

6. 이벤트 구독 구성

⚠️ 중요: 이벤트 구독을 설정하기 전에 다음을 확인하십시오:

Feishu 용 openclaw channels add 를 이미 실행했습니다
Gateway 가 실행 중입니다 (openclaw gateway status)

Event Subscription 에서:

Use long connection to receive events (WebSocket) 를 선택합니다
이벤트를 추가합니다: im.message.receive_v1

⚠️ Gateway 가 실행 중이 아니면 long-connection 설정이 저장되지 않을 수 있습니다. Configure event subscription

7. 앱 게시

Version Management & Release 에서 버전을 생성합니다
심사를 제출하고 게시합니다
관리자 승인을 기다립니다 (엔터프라이즈 앱은 보통 자동 승인됩니다)

2단계: OpenClaw 구성

마법사로 구성 (권장)

openclaw channels add

Feishu 를 선택하고 App ID 와 App Secret 을 붙여넣습니다.

구성 파일로 설정

~/.openclaw/openclaw.json 를 편집합니다:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "My AI assistant",
        },
      },
    },
  },
}

환경 변수로 구성

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark (글로벌) 도메인

테넌트가 Lark (국제) 인 경우 도메인을 lark (또는 전체 도메인 문자열) 로 설정하십시오. 이는 channels.feishu.domain 또는 계정별 (channels.feishu.accounts.<id>.domain) 로 설정할 수 있습니다.

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

3단계: 시작 및 테스트

1. Gateway 시작

openclaw gateway

2. 테스트 메시지 전송

Feishu 에서 봇을 찾아 메시지를 전송합니다.

3. 페어링 승인

기본적으로 봇은 페어링 코드를 응답합니다. 이를 승인합니다:

openclaw pairing approve feishu <CODE>

승인 후 정상적으로 대화할 수 있습니다.

개요

Feishu 봇 채널: Gateway 가 관리하는 Feishu 봇
결정적 라우팅: 응답은 항상 Feishu 로 반환됩니다
세션 격리: 다이렉트 메시지 는 메인 세션을 공유하며, 그룹은 서로 격리됩니다
WebSocket 연결: Feishu SDK 를 통한 장기 연결, 공개 URL 불필요

접근 제어

다이렉트 메시지

기본값: dmPolicy: "pairing" (알 수 없는 사용자는 페어링 코드를 받음)

페어링 승인:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

허용 목록 모드: 허용된 Open ID 를 사용하여 channels.feishu.allowFrom 를 설정합니다

그룹 채팅

1. 그룹 정책 (channels.feishu.groupPolicy):

"open" = 그룹의 모든 사용자 허용 (기본값)
"allowlist" = groupAllowFrom 만 허용
"disabled" = 그룹 메시지 비활성화

2. 멘션 요구 사항 (channels.feishu.groups.<chat_id>.requireMention):

true = @멘션 필요 (기본값)
false = 멘션 없이 응답

그룹 구성 예시

모든 그룹 허용, @멘션 필요 (기본값)

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // Default requireMention: true
    },
  },
}

모든 그룹 허용, @멘션 불필요

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

그룹에서 특정 사용자만 허용

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

그룹/사용자 ID 가져오기

그룹 ID (chat_id)

그룹 ID 는 oc_xxx 와 같은 형태입니다. 방법 1 (권장)

Gateway 를 시작하고 그룹에서 봇을 @멘션합니다
openclaw logs --follow 를 실행하고 chat_id 를 찾습니다

방법 2 Feishu API 디버거를 사용하여 그룹 채팅 목록을 조회합니다.

사용자 ID (open_id)

사용자 ID 는 ou_xxx 과 같은 형태입니다. 방법 1 (권장)

Start the gateway and DM the bot
openclaw logs --follow 를 실행하고 open_id 를 찾습니다

방법 2 페어링 요청에서 사용자 Open ID 를 확인합니다:

openclaw pairing list feishu

공통 명령어

Command	Description
`/status`	봇 상태 표시
`/reset`	세션 초기화
`/model`	모델 표시/전환

참고: Feishu 는 아직 네이티브 명령 메뉴를 지원하지 않으므로, 명령은 텍스트로 전송해야 합니다.

Gateway 관리 명령어

Command	Description
`openclaw gateway status`	Gateway 상태 표시
`openclaw gateway install`	Gateway 서비스 설치/시작
`openclaw gateway stop`	Gateway 서비스 중지
`openclaw gateway restart`	Gateway 서비스 재시작
`openclaw logs --follow`	Gateway 로그 실시간 조회

문제 해결

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

봇이 그룹에 추가되어 있는지 확인합니다
봇을 @멘션했는지 확인합니다 (기본 동작)
groupPolicy 가 "disabled" 로 설정되어 있지 않은지 확인합니다
로그를 확인합니다: openclaw logs --follow

Bot does not receive messages

앱이 게시 및 승인되었는지 확인합니다
이벤트 구독에 im.message.receive_v1 이 포함되어 있는지 확인합니다
long connection 이 활성화되어 있는지 확인합니다
앱 권한이 완전한지 확인합니다
Gateway 가 실행 중인지 확인합니다: openclaw gateway status
로그를 확인합니다: openclaw logs --follow

App Secret 유출

Feishu Open Platform 에서 App Secret 을 재설정합니다
구성에서 App Secret 을 업데이트합니다
Gateway 를 재시작합니다

메시지 전송 실패

앱에 im:message:send_as_bot 권한이 있는지 확인합니다
Ensure the app is published
상세 오류를 위해 로그를 확인합니다

고급 구성

여러 계정

{
  channels: {
    feishu: {
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

메시지 제한

textChunkLimit: 발신 텍스트 청크 크기 (기본값: 2000자)
mediaMaxMb: 미디어 업로드/다운로드 제한 (기본값: 30MB)

스트리밍

Feishu 는 인터랙티브 카드를 통한 스트리밍 응답을 지원합니다. 활성화하면 봇이 텍스트를 생성하는 동안 카드를 업데이트합니다.

{
  channels: {
    feishu: {
      streaming: true, // enable streaming card output (default true)
      blockStreaming: true, // enable block-level streaming (default true)
    },
  },
}

전체 응답을 받은 후 전송하려면 streaming: false 를 설정합니다.

멀티 에이전트 라우팅

bindings 를 사용하여 Feishu 다이렉트 메시지 또는 그룹을 서로 다른 에이전트로 라우팅합니다.

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

라우팅 필드:

match.channel: "feishu"
match.peer.kind: "direct" or "group"
match.peer.id: 사용자 Open ID (ou_xxx) 또는 그룹 ID (oc_xxx)

조회 팁은 그룹/사용자 ID 가져오기 를 참고하십시오.

구성 참조

전체 구성: Gateway configuration 주요 옵션:

Setting	Description	Default
`channels.feishu.enabled`	채널 활성화/비활성화	`true`
`channels.feishu.domain`	API 도메인 (`feishu` 또는 `lark`)	`feishu`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	계정별 API 도메인 재정의	`feishu`
`channels.feishu.dmPolicy`	DM policy	`pairing`
`channels.feishu.allowFrom`	다이렉트 메시지 허용 목록 (open_id 목록)	-
`channels.feishu.groupPolicy`	그룹 정책	`open`
`channels.feishu.groupAllowFrom`	그룹 허용 목록	-
`channels.feishu.groups.<chat_id>.requireMention`	@멘션 필요	`true`
`channels.feishu.groups.<chat_id>.enabled`	그룹 활성화	`true`
`channels.feishu.textChunkLimit`	메시지 청크 크기	`2000`
`channels.feishu.mediaMaxMb`	미디어 크기 제한	`30`
`channels.feishu.streaming`	스트리밍 카드 출력 활성화	`true`
`channels.feishu.blockStreaming`	블록 스트리밍 활성화	`true`

dmPolicy 참조

Value	Behavior
`"pairing"`	기본값. 알 수 없는 사용자는 페어링 코드를 받으며 승인 필요
`"allowlist"`	`allowFrom` 에 있는 사용자만 대화 가능
`"open"`	모든 사용자 허용 (`"*"` 이 allowFrom 에 필요)
`"disabled"`	Disable DMs

지원되는 메시지 유형

수신

✅ 텍스트
✅ 리치 텍스트 (post)
✅ 이미지
✅ 파일
✅ 오디오
✅ 비디오
✅ 스티커

Send

✅ 텍스트
✅ 이미지
✅ 파일
✅ 오디오
⚠️ 리치 텍스트 (부분 지원)

​Feishu 봇

​필요한 플러그인

​빠른 시작

​방법 1: 온보딩 마법사 (권장)

​방법 2: CLI 설정

​1단계: Feishu 앱 생성

​1. Feishu Open Platform 열기

​2. 앱 생성

​3. 자격 증명 복사

​4. 권한 구성

​5. 봇 기능 활성화

​6. 이벤트 구독 구성

​7. 앱 게시

​2단계: OpenClaw 구성

​마법사로 구성 (권장)

​구성 파일로 설정

​환경 변수로 구성

​Lark (글로벌) 도메인

​3단계: 시작 및 테스트

​1. Gateway 시작

​2. 테스트 메시지 전송

​3. 페어링 승인

​개요

​접근 제어

​다이렉트 메시지

​그룹 채팅

​그룹 구성 예시

​모든 그룹 허용, @멘션 필요 (기본값)

​모든 그룹 허용, @멘션 불필요

​그룹에서 특정 사용자만 허용

​그룹/사용자 ID 가져오기

​그룹 ID (chat_id)

​사용자 ID (open_id)

​공통 명령어

​Gateway 관리 명령어

​문제 해결

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

​Bot does not receive messages

​App Secret 유출

​메시지 전송 실패

​고급 구성

​여러 계정

​메시지 제한

​스트리밍

​멀티 에이전트 라우팅

​구성 참조

​dmPolicy 참조

​지원되는 메시지 유형

​수신

​Send