Feishu 봇

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

번들 플러그인

Feishu는 현재 OpenClaw 릴리스에 번들로 포함되므로 별도의 플러그인 설치가 필요하지 않습니다.

이전 빌드나 번들 Feishu가 포함되지 않은 커스텀 설치를 사용하는 경우 수동으로 설치합니다:

openclaw plugins install @openclaw/feishu

빠른 시작

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

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

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

openclaw onboard

마법사가 다음을 안내합니다:

1. Feishu 앱 생성 및 자격 증명 수집
2. OpenClaw에 앱 자격 증명 설정
3. 게이트웨이 시작

설정 후 게이트웨이 상태를 확인합니다:

• openclaw gateway status
• openclaw logs --follow

방법 2: CLI 설정

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

openclaw channels add

Feishu를 선택한 후 App ID와 App Secret을 입력합니다.

설정 후 게이트웨이를 관리합니다:

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

1단계: Feishu 앱 생성

1. Feishu 오픈 플랫폼 접속

Feishu 오픈 플랫폼에 방문하여 로그인합니다.

Lark(글로벌) 테넌트는 https://open.larksuite.com/app을 사용하고 Feishu 설정에서 domain: "lark"를 설정합니다.

2. 앱 생성

1. 기업 앱 생성을 클릭합니다
2. 앱 이름 + 설명을 입력합니다
3. 앱 아이콘을 선택합니다

3. 자격 증명 복사

자격 증명 & 기본 정보에서 다음을 복사합니다:

• App ID (형식: cli_xxx)
• App Secret

중요: App Secret을 비공개로 유지하세요.

4. 권한 설정

권한에서 일괄 가져오기를 클릭하고 붙여넣기합니다:

{
  "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"]
  }
}

5. 봇 기능 활성화

앱 기능 > 봇에서:

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

6. 이벤트 구독 설정

경고: 이벤트 구독을 설정하기 전에 다음을 확인하세요:

1. Feishu에 대해 openclaw channels add를 이미 실행했는지
2. 게이트웨이가 실행 중인지 (openclaw gateway status)

이벤트 구독에서:

1. 긴 연결을 사용하여 이벤트 수신 (WebSocket)을 선택합니다
2. 이벤트를 추가합니다: im.message.receive_v1

경고: 게이트웨이가 실행 중이 아니면 긴 연결 설정이 저장에 실패할 수 있습니다.

7. 앱 배포

1. 버전 관리 & 배포에서 버전을 생성합니다
2. 검토를 위해 제출하고 배포합니다
3. 관리자 승인을 기다립니다 (기업 앱은 보통 자동 승인됨)

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

connectionMode: "webhook"을 사용하는 경우 verificationToken과 encryptKey를 모두 설정하세요. Feishu 웹훅 서버는 기본적으로 127.0.0.1에 바인딩됩니다. 의도적으로 다른 바인드 주소가 필요한 경우에만 webhookHost를 설정하세요.

인증 토큰과 암호화 키 (웹훅 모드)

웹훅 모드를 사용할 때 설정에 channels.feishu.verificationToken과 channels.feishu.encryptKey를 모두 설정합니다. 값을 얻으려면:

1. Feishu 오픈 플랫폼에서 앱을 엽니다
2. 개발 → 이벤트 & 콜백 (开发配置 → 事件与回调)으로 이동합니다
3. 암호화 탭 (加密策略)을 엽니다
4. Verification Token과 Encrypt Key를 복사합니다

아래 스크린샷은 Verification Token의 위치를 보여줍니다. Encrypt Key는 동일한 암호화 섹션에 있습니다.

환경 변수로 설정

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이면 타이핑 리액션 호출을 건너뜁니다.
• resolveSenderNames (기본값 true): false이면 발신자 프로필 조회 호출을 건너뜁니다.

최상위 또는 계정별로 설정합니다:

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

3단계: 시작 + 테스트

1. 게이트웨이 시작

openclaw gateway

2. 테스트 메시지 전송

Feishu에서 봇을 찾아 메시지를 보냅니다.

3. 페어링 승인

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

openclaw pairing approve feishu <CODE>

승인 후 정상적으로 채팅할 수 있습니다.

개요

• Feishu 봇 채널: 게이트웨이가 관리하는 Feishu 봇
• 결정적 라우팅: 응답은 항상 Feishu로 돌아갑니다
• 세션 격리: DM은 메인 세션을 공유하며 그룹은 격리됩니다
• WebSocket 연결: Feishu SDK를 통한 긴 연결, 공개 URL 불필요

접근 제어

다이렉트 메시지

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

• 페어링 승인:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• 허용 목록 모드: channels.feishu.allowFrom에 허용된 Open ID를 설정

그룹 채팅

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

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

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

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

그룹 설정 예시

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

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

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

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

특정 그룹만 허용

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu 그룹 ID (chat_id)는 다음과 같은 형식: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

그룹 내 발신자 제한 (발신자 허용 목록)

그룹 자체를 허용하는 것에 더해, 해당 그룹의 모든 메시지는 발신자 open_id로 게이팅됩니다: groups.<chat_id>.allowFrom에 나열된 사용자의 메시지만 처리되며, 다른 멤버의 메시지는 무시됩니다(이는 /reset이나 /new 같은 제어 명령뿐만 아니라 전체 발신자 수준 게이팅입니다).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu 사용자 ID (open_id)는 다음과 같은 형식: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

그룹/사용자 ID 찾기

그룹 ID (chat_id)

그룹 ID는 oc_xxx 형식입니다.

방법 1 (권장)

1. 게이트웨이를 시작하고 그룹에서 봇을 @멘션합니다
2. openclaw logs --follow를 실행하고 chat_id를 찾습니다

방법 2

Feishu API 디버거를 사용하여 그룹 채팅을 나열합니다.

사용자 ID (open_id)

사용자 ID는 ou_xxx 형식입니다.

방법 1 (권장)

1. 게이트웨이를 시작하고 봇에 DM을 보냅니다
2. openclaw logs --follow를 실행하고 open_id를 찾습니다

방법 2

사용자 Open ID의 페어링 요청을 확인합니다:

openclaw pairing list feishu

자주 사용하는 명령

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

게이트웨이 관리 명령

문제 해결

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

1. 봇이 그룹에 추가되었는지 확인합니다
2. 봇을 @멘션하는지 확인합니다 (기본 동작)
3. groupPolicy가 "disabled"로 설정되지 않았는지 확인합니다
4. 로그를 확인합니다: openclaw logs --follow

봇이 메시지를 수신하지 않는 경우

1. 앱이 배포되고 승인되었는지 확인합니다
2. 이벤트 구독에 im.message.receive_v1이 포함되어 있는지 확인합니다
3. 긴 연결이 활성화되어 있는지 확인합니다
4. 앱 권한이 완전한지 확인합니다
5. 게이트웨이가 실행 중인지 확인합니다: openclaw gateway status
6. 로그를 확인합니다: openclaw logs --follow

App Secret 유출

1. Feishu 오픈 플랫폼에서 App Secret을 재설정합니다
2. 설정에서 App Secret을 업데이트합니다
3. 게이트웨이를 재시작합니다

메시지 전송 실패

1. 앱에 im:message:send_as_bot 권한이 있는지 확인합니다
2. 앱이 배포되었는지 확인합니다
3. 로그에서 자세한 오류를 확인합니다

고급 설정

다중 계정

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

defaultAccount는 아웃바운드 API가 accountId를 명시적으로 지정하지 않을 때 사용할 Feishu 계정을 제어합니다.

메시지 제한

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

스트리밍

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

{
  channels: {
    feishu: {
      streaming: true, // 스트리밍 카드 출력 활성화 (기본값 true)
      blockStreaming: true, // 블록 수준 스트리밍 활성화 (기본값 true)
    },
  },
}

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

다중 에이전트 라우팅

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 찾기를 참조하세요.

설정 레퍼런스

전체 설정: Gateway configuration

주요 옵션:

dmPolicy 레퍼런스

지원 메시지 유형

수신

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

발송

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