Feishu 봇을 OpenClaw에 연결하는 가장 쉬운 방법

Feishu 봇

Feishu(Lark)는 협업과 메시징을 위해 기업에서 사용하는 팀 채팅 플랫폼이에요. 이 플러그인은 WebSocket 이벤트 구독을 사용해 OpenClaw를 Feishu/Lark 봇에 연결해 줘요. 덕분에 퍼블릭 Webhook URL을 노출하지 않고도 메시지를 받을 수 있죠.

내장 플러그인

Feishu는 최신 OpenClaw 릴리스에 내장되어 있어서 별도로 플러그인을 설치할 필요가 없어요.

만약 구버전이나 Feishu가 포함되지 않은 커스텀 설치 버전을 사용 중이라면, 직접 설치해 주세요:

openclaw plugins install @openclaw/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 오픈 플랫폼 열기

Feishu Open Platform에 접속해서 로그인하세요.

Lark(글로벌) 테넌트 사용자는 https://open.larksuite.com/app를 사용하고, Feishu 설정에서 domain: "lark"를 지정해야 해요.

2. 앱 생성하기

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

Create enterprise app

3. 자격 증명 복사하기

Credentials & Basic Info에서 다음 항목을 복사하세요:

App ID (cli_xxx 형식)
App Secret

❗ 중요: 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",
      "cardkit:card:read",
      "cardkit:card: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"]
  }
}

Configure permissions

5. 봇 기능 활성화하기

App Capability > Bot에서:

봇 기능 활성화
봇 이름 설정

Enable bot capability

6. 이벤트 구독 설정하기

⚠️ 중요: 이벤트 구독을 설정하기 전에 다음 사항을 확인하세요:

Feishu에 대해 openclaw channels add를 이미 실행했는지
Gateway가 실행 중인지 (openclaw gateway status)

Event Subscription에서:

Use long connection to receive events (WebSocket) 선택
im.message.receive_v1 이벤트 추가
(선택 사항) Drive 댓글 워크플로우를 사용하려면 drive.notice.comment_add_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",
          name: "My AI assistant",
        },
      },
    },
  },
}

만약 connectionMode: "webhook"을 사용한다면, verificationToken과 encryptKey를 모두 설정해야 해요. Feishu Webhook 서버는 기본적으로 127.0.0.1에 바인딩되므로, 의도적으로 다른 바인드 주소가 필요한 경우에만 webhookHost를 설정하세요.

Verification Token 및 Encrypt Key (webhook 모드)

Webhook 모드를 사용할 때는 설정 파일에 channels.feishu.verificationToken과 channels.feishu.encryptKey를 모두 입력하세요. 값을 확인하는 방법은 다음과 같아요:

Feishu 오픈 플랫폼에서 앱 열기
Development → Events & Callbacks (开发配置 → 事件与回调) 이동
Encryption (加密策略) 탭 열기
Verification Token과 Encrypt Key 복사

아래 스크린샷은 Verification Token의 위치를 보여줘요. Encrypt Key도 같은 Encryption 섹션에서 확인할 수 있어요.

Verification Token location

환경 변수로 설정하기

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",
        },
      },
    },
  },
}

할당량 최적화 플래그

두 가지 옵션 플래그를 사용해 Feishu API 사용량을 줄일 수 있어요:

typingIndicator (기본값 true): false로 설정하면 입력 중 반응(typing reaction) 호출을 건너뛰어요.
resolveSenderNames (기본값 true): false로 설정하면 발신자 프로필 조회 호출을 건너뛰어요.

상위 레벨이나 개별 계정별로 설정할 수 있어요:

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

Step 3: 시작 및 테스트

1. Gateway 시작하기

openclaw gateway

2. 테스트 메시지 보내기

Feishu에서 생성한 봇을 찾아 메시지를 보내보세요.

3. 페어링 승인하기

기본적으로 봇은 페어링 코드를 답장으로 보내요. 아래 명령어로 승인해 주세요:

openclaw pairing approve feishu <CODE>

승인이 완료되면 평소처럼 채팅할 수 있어요.

개요

Feishu bot channel: Gateway가 관리하는 Feishu 봇이에요.
Deterministic routing: 답변은 항상 메시지가 시작된 Feishu로 돌아가요.
Session isolation: DM은 메인 세션을 공유하지만, 그룹 채팅은 각각 격리돼요.
WebSocket connection: Feishu SDK를 통한 long connection 방식을 사용해서 퍼블릭 URL이 없어도 연결할 수 있어요.

액세스 제어

Direct messages

기본값: dmPolicy: "pairing" (모르는 사용자가 메시지를 보내면 페어링 코드를 받게 돼요)

페어링 승인:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Allowlist 모드: channels.feishu.allowFrom에 허용할 Open ID 목록을 설정하세요.

그룹 채팅

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

"open" = 그룹 내 모든 사용자 허용
"allowlist" = groupAllowFrom에 지정된 그룹만 허용
"disabled" = 그룹 메시지 비활성화

기본값: allowlist

2. 멘션 요구 사항 (channels.feishu.requireMention, channels.feishu.groups.<chat_id>.requireMention으로 개별 설정 가능):

true로 설정 = 반드시 @멘션이 필요해요.
false로 설정 = 멘션 없이도 응답해요.
설정하지 않았을 때 groupPolicy: "open"인 경우 = 기본값은 false예요.
설정하지 않았을 때 groupPolicy가 "open"이 아닌 경우 = 기본값은 true예요.

그룹 설정 예시

모든 그룹 허용, @mention 불필요 (open 그룹 기본값)

{
  channels: {
    feishu: {
      groupPolicy: "open",
    },
  },
}

모든 그룹 허용, 하지만 @mention 필요

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

특정 그룹만 허용

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

그룹 내 메시지 전송자 제한 (sender allowlist)

그룹 자체를 허용하는 것 외에도, 해당 그룹의 모든 메시지를 전송자의 open_id로 필터링할 수 있어요. groups.<chat_id>.allowFrom에 나열된 사용자의 메시지만 처리되고 다른 멤버의 메시지는 무시돼요. (이 설정은 /reset이나 /new 같은 제어 명령어뿐만 아니라 모든 메시지에 적용되는 강력한 제한이에요)

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu user ID (open_id) 형식: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

그룹/사용자 ID 가져오기

그룹 ID (chat_id)

그룹 ID는 oc_xxx와 같은 형태예요.

방법 1 (권장)

Gateway를 시작하고 그룹에서 봇을 @멘션하세요.
openclaw logs --follow를 실행하고 chat_id를 찾으세요.

방법 2

Feishu API debugger를 사용해 그룹 채팅 목록을 확인하세요.

사용자 ID (open_id)

사용자 ID는 ou_xxx와 같은 형태예요.

방법 1 (권장)

Gateway를 시작하고 봇에게 DM을 보내세요.
openclaw logs --follow를 실행하고 open_id를 찾으세요.

방법 2

페어링 요청에서 사용자 Open ID를 확인하세요:

openclaw pairing list feishu

공통 명령어

명령어	설명
`/status`	봇 상태 표시
`/reset`	세션 초기화
`/model`	모델 표시/변경

참고: Feishu는 아직 네이티브 명령어 메뉴를 지원하지 않기 때문에, 명령어는 반드시 텍스트로 보내야 해요.

Gateway 관리 명령어

Gateway를 관리할 때 사용하는 주요 명령어들이에요. 터미널에서 바로 실행해서 상태를 확인하거나 서비스를 제어할 수 있어요.

명령어	설명
`openclaw gateway status`	Gateway 상태 표시
`openclaw gateway install`	Gateway 서비스 설치 및 시작
`openclaw gateway stop`	Gateway 서비스 중지
`openclaw gateway restart`	Gateway 서비스 재시작
`openclaw logs --follow`	Gateway 로그 실시간 확인

문제 해결하기

그룹 채팅에서 봇이 응답하지 않아요

봇이 해당 그룹에 정상적으로 추가되었는지 확인하세요.
봇을 @mention 했는지 확인하세요. (기본적으로 멘션이 필요해요)
groupPolicy 설정이 "disabled"로 되어 있지 않은지 확인하세요.
로그를 확인해 보세요: openclaw logs --follow

봇이 메시지를 받지 못해요

앱이 게시(publish)되었고 승인(approve)된 상태인지 확인하세요.
이벤트 구독(event subscription) 항목에 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 권한이 있는지 확인하세요.
앱이 현재 게시된 상태인지 확인하세요.
로그를 통해 구체적인 에러 원인을 파악해 보세요.

고급 설정

여러 계정 사용하기

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

defaultAccount는 아웃바운드 API에서 accountId를 명시적으로 지정하지 않았을 때 어떤 Feishu 계정을 사용할지 결정해요.

메시지 제한

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로 설정하세요.

ACP 세션

Feishu는 다음 항목에서 ACP를 지원해요:

DM (1:1 채팅)
그룹 토픽 대화

Feishu ACP는 텍스트 명령어로 작동해요. 네이티브 슬래시 커맨드 메뉴가 따로 없으니, 대화창에서 직접 /acp ... 메시지를 입력해서 사용하면 돼요.

영구 ACP 바인딩

최상위 타입의 ACP 바인딩을 사용하면 Feishu DM이나 토픽 대화를 특정 영구 ACP 세션에 고정할 수 있어요.

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

채팅에서 스레드 기반 ACP 생성

Feishu DM이나 토픽 대화 도중에 즉석에서 ACP 세션을 생성하고 바인딩할 수 있어요.

/acp spawn codex --thread here

참고 사항:

--thread here 옵션은 DM과 Feishu 토픽에서 잘 작동해요.
바인딩된 DM/토픽에서 보내는 후속 메시지는 해당 ACP 세션으로 바로 전달됩니다.
v1 버전에서는 토픽 기능이 없는 일반 그룹 채팅은 지원하지 않아요.

멀티 에이전트 라우팅

bindings 설정을 활용하면 Feishu DM이나 그룹을 서로 다른 에이전트로 연결할 수 있어요.

{
  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" 또는 "group"
match.peer.id: 사용자의 Open ID (ou_xxx) 또는 그룹 ID (oc_xxx)

ID를 찾는 방법은 그룹/사용자 ID 가져오기 섹션을 참고해 보세요.

설정 레퍼런스

전체 설정 정보는 여기서 확인할 수 있어요: Gateway configuration

주요 옵션:

설정 항목	설명	기본값
`channels.feishu.enabled`	채널 활성화/비활성화	`true`
`channels.feishu.domain`	API 도메인 (`feishu` 또는 `lark`)	`feishu`
`channels.feishu.connectionMode`	이벤트 전송 모드	`websocket`
`channels.feishu.defaultAccount`	아웃바운드 라우팅용 기본 계정 ID	`default`
`channels.feishu.verificationToken`	Webhook 모드 사용 시 필수	-
`channels.feishu.encryptKey`	Webhook 모드 사용 시 필수	-
`channels.feishu.webhookPath`	Webhook 라우트 경로	`/feishu/events`
`channels.feishu.webhookHost`	Webhook 바인드 호스트	`127.0.0.1`
`channels.feishu.webhookPort`	Webhook 바인드 포트	`3000`
`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 정책	`pairing`
`channels.feishu.allowFrom`	DM 허용 목록 (open_id 리스트)	-
`channels.feishu.groupPolicy`	그룹 정책	`allowlist`
`channels.feishu.groupAllowFrom`	그룹 허용 목록	-
`channels.feishu.requireMention`	기본 @mention 필수 여부	조건부
`channels.feishu.groups.<chat_id>.requireMention`	그룹별 @mention 필수 여부 오버라이드	상속됨
`channels.feishu.groups.<chat_id>.enabled`	그룹 활성화	`true`
`channels.feishu.textChunkLimit`	메시지 청크 크기	`2000`
`channels.feishu.mediaMaxMb`	미디어 크기 제한	`30`
`channels.feishu.streaming`	스트리밍 카드 출력 활성화	`true`
`channels.feishu.blockStreaming`	블록 스트리밍 활성화	`true`

AI Setup Assistant

다음 단계

dmPolicy 레퍼런스

값	동작
`"pairing"`	기본값. 알 수 없는 사용자는 페어링 코드를 받으며, 반드시 승인되어야 해요
`"allowlist"`	`allowFrom`에 있는 사용자만 채팅할 수 있어요
`"open"`	모든 사용자를 허용해요 (`allowFrom`에 `"*"` 설정이 필요해요)
`"disabled"`	DM 기능을 비활성화해요

지원되는 메시지 유형

수신

✅ Text
✅ Rich text (post)
✅ Images
✅ Files
✅ Audio
✅ Video/media
✅ Stickers

발신

✅ Text
✅ Images
✅ Files
✅ Audio
✅ Video/media
✅ Interactive cards
⚠️ Rich text (포스트 스타일의 포맷팅과 카드를 지원하며, Feishu의 모든 편집 기능을 지원하는 것은 아니에요)

스레드 및 답장

✅ 인라인 답장
✅ Feishu가 reply_in_thread를 노출하는 토픽 스레드 답장
✅ 스레드나 토픽 메시지에 답장할 때 미디어 답장도 스레드 맥락을 유지해요

Drive 댓글

Feishu Drive 문서(Docs, Sheets 등)에 누군가 댓글을 남기면 Agent를 트리거할 수 있어요. Agent는 댓글 텍스트, 문서 컨텍스트, 댓글 스레드 정보를 전달받아 스레드에 답글을 달거나 문서를 직접 수정할 수 있죠.

필수 설정:

Feishu 앱의 이벤트 구독 설정에서 drive.notice.comment_add_v1을 구독해 주세요 (기존 im.message.receive_v1과 함께 설정해야 해요).
Drive 도구는 기본적으로 활성화되어 있어요. 비활성화하려면 channels.feishu.tools.drive: false 설정을 사용하세요.

feishu_drive 도구는 다음과 같은 댓글 액션을 제공해요:

Action	Description
`list_comments`	문서의 댓글 목록 조회
`list_comment_replies`	댓글 스레드의 답글 목록 조회
`add_comment`	새로운 최상위 댓글 추가
`reply_comment`	기존 댓글 스레드에 답글 작성

Agent가 Drive 댓글 이벤트를 처리할 때 다음 정보를 전달받아요:

댓글 텍스트 및 발신자 정보
문서 메타데이터 (제목, 유형, URL)
스레드 내 답글 작성을 위한 댓글 스레드 컨텍스트

문서 편집을 마친 후에는 feishu_drive.reply_comment를 사용해 댓글 작성자에게 알림을 보내는 방식을 추천해요. 그 다음 NO_REPLY를 출력하면 메시지가 중복으로 전송되는 상황을 피할 수 있어요.

런타임 액션 범위

Feishu는 현재 다음과 같은 런타임 액션을 제공하고 있어요:

send
read
edit
thread-reply
pin
list-pins
unpin
member-info
channel-info
channel-list
react 및 reactions (설정에서 reaction이 활성화된 경우)
feishu_drive 댓글 액션: list_comments, list_comment_replies, add_comment, reply_comment

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

Feishu 봇을 OpenClaw에 연결하는 가장 쉬운 방법

Feishu 봇

내장 플러그인

빠른 시작

방법 1: 온보딩 (권장)

방법 2: CLI 설정

1단계: Feishu 앱 만들기

1. Feishu 오픈 플랫폼 열기

2. 앱 생성하기

3. 자격 증명 복사하기

4. 권한 설정하기

5. 봇 기능 활성화하기

6. 이벤트 구독 설정하기

7. 앱 게시하기

2단계: OpenClaw 설정하기

마법사로 설정하기 (권장)

설정 파일로 설정하기

Verification Token 및 Encrypt Key (webhook 모드)

환경 변수로 설정하기

Lark (글로벌) 도메인

할당량 최적화 플래그

Step 3: 시작 및 테스트

1. Gateway 시작하기

2. 테스트 메시지 보내기

3. 페어링 승인하기

개요

액세스 제어

Direct messages

그룹 채팅

그룹 설정 예시

모든 그룹 허용, @mention 불필요 (open 그룹 기본값)

모든 그룹 허용, 하지만 @mention 필요

특정 그룹만 허용

그룹 내 메시지 전송자 제한 (sender allowlist)

그룹/사용자 ID 가져오기

그룹 ID (chat_id)

사용자 ID (open_id)

공통 명령어

Gateway 관리 명령어

문제 해결하기

그룹 채팅에서 봇이 응답하지 않아요

봇이 메시지를 받지 못해요

App Secret이 유출되었어요

메시지 전송 실패

고급 설정

여러 계정 사용하기

메시지 제한

스트리밍

ACP 세션

영구 ACP 바인딩

채팅에서 스레드 기반 ACP 생성

멀티 에이전트 라우팅

설정 레퍼런스

다음 단계

dmPolicy 레퍼런스

지원되는 메시지 유형

수신

발신

스레드 및 답장

Drive 댓글

런타임 액션 범위

관련 문서

다음 단계

아직 막혀 있나요?